Providers

Add a provider

POST/api/v1/providers

Adds a dentist who renders treatment, so a claim can name them as its rendering provider. The NPI must be 10 digits with a valid check digit, and one provider can have it in an organization and mode. Names and the license number are sent on the claim: none may contain control characters, and the license number may hold only letters, digits, spaces and basic punctuation (no * ~ : ^ |; in a name those are replaced with a space in the claim file). Needs an Idempotency-Key header and a key with the submit permission.

Needs a key with submit permission.

Request

Headers

Headers
Name	Type	Required	Description
Idempotency-Key	string	required	Makes the request safe to repeat: a request with the same key and body returns the first answer (the reply has an idempotent-replayed header), and the same key with a different request is refused. 1 to 255 printable characters; a UUID is a good choice.At least 1 character.At most 255 characters.Matches `^[\x21-\x7e]{1,255}$`.

Body

Body
Name	Type	Required	Description
first_name	string	required	The provider's first name.At most 35 characters.
last_name	string	required	The provider's last name.At most 60 characters.
credential	string	optional	The credential after the name, such as DDS or DMD.At most 10 characters.
npi	string	required	The provider's individual NPI: 10 digits with a valid check digit. One provider per NPI in an organization and mode.
license	object or null	optional	The state license: sent on the claim as the rendering provider's secondary identification.
license.number	string	required	The state license number.At most 30 characters.
license.state	string	required	The two-letter code of the state that issued the license.
taxonomy_code	string	optional	The NUCC taxonomy code sent on the claim: 9 letters or digits and a final X. Default 1223G0001X (general dentist).
status	string	optional	inactive providers stay on the claims that name them but cannot be chosen for new ones. Default active.One of: `active`, `inactive`.

Response

The provider. Status 200.

Response fields
Name	Type	Description
id	string	An ID that starts with prv_.
object	string	Always `provider`.
first_name	string	At most 35 characters.
last_name	string	At most 60 characters.
credential	string	The credential after the name, such as DDS. Empty when there is none.At most 10 characters.
npi	string	The provider's individual NPI.
license	object or null	The state license sent on claims, or null when none is on file.
license.number	string
license.state	string	The two-letter code of the state that issued the license.
taxonomy_code	string	The NUCC taxonomy code sent on claims.
specialty	string	The specialty the taxonomy code stands for (General dentistry, Orthodontics...), or the code itself when it is not one of the dental codes.
status	string	One of: `active`, `inactive`.
mode	string	One of: `test`, `live`.
created_at	string (date-time)
updated_at	string (date-time)

Errors

Errors
HTTP status	Code	What it means
401	UNAUTHORIZED	A valid API key is required. Send it as "Authorization: Bearer <key>".
403	PERMISSION_DENIED	This API key is not allowed to do that.
422	INVALID_REQUEST	The request is not valid.
400	IDEMPOTENCY_KEY_REQUIRED	POST and PATCH requests need an Idempotency-Key header.
422	IDEMPOTENCY_KEY_REUSED	That Idempotency-Key was already used with a different request.
409	IDEMPOTENCY_KEY_IN_USE	A request with that Idempotency-Key is still running. Retry shortly.
413	PAYLOAD_TOO_LARGE	The request body is larger than 1 MB.
504	TIMEOUT	The request took too long to finish. It may still have taken effect: look it up before sending it again with a new Idempotency-Key. What it made is found with GET /api/v1/eligibility?request_id=<this request_id>, and the same filter on /api/v1/claims and /api/v1/attachments (a key with read permission).
500	INTERNAL	Something went wrong on our side. Quote the request ID if you contact us.

Example

Example request

Shell

curl -X POST "https://sandbox.myclaimhouse.com/api/v1/providers" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "first_name": "Riley",
  "last_name": "Example",
  "credential": "DDS",
  "npi": "1999990017",
  "license": {
    "number": "GA-000000",
    "state": "GA"
  }
}'

Example response: 200

JSON

{
  "id": "prv_01JM000000E008000000000005",
  "object": "provider",
  "first_name": "Riley",
  "last_name": "Example",
  "credential": "DDS",
  "npi": "1999990017",
  "license": {
    "number": "GA-000000",
    "state": "GA"
  },
  "taxonomy_code": "1223G0001X",
  "specialty": "General dentistry",
  "status": "active",
  "mode": "test",
  "created_at": "2026-01-15T14:00:00+00:00",
  "updated_at": "2026-01-15T14:00:00+00:00"
}