Import Credentialing¶

Uploads a spreadsheet of credentialing rows to create or update in bulk.

Endpoint¶

POST /v2/credentialing/imports

Request Body¶

Part	Type	Required	Description
`file`	file	Yes	Spreadsheet, .xlsx or .csv, max 10 MB. First sheet, header row first.

Request¶

curl --location '{base_url}/v2/credentialing/imports' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Idempotency-Key: 7d3f…' \
  --form 'file=@credentialing.xlsx'

Spreadsheet Format¶

.xlsx or .csv, detected by extension (else by content).
First worksheet only. Row 1 is the header.
Header match is case- and whitespace-insensitive; Claim MD and ClaimMD are equivalent.
Blank rows are skipped.
Max 10 MB.
Dates are YYYY-MM-DD text — Excel date cells are not accepted; format the column as text.

Header	Required	Cell rules
`Provider NPI`	required header	Blank, or equal to the Billing Profile NPI → the `GROUP` row. Otherwise 10 digits matching a non-revoked provider.
`Billing Profile NPI`	required header, required per row	Together with Tax ID must match a billing profile exactly.
`Billing Profile Tax ID`	required header, required per row	Nine digits, no hyphen.
`Payer ID`	required header	ClaimMD payer id. At least one of `Payer ID` / `Client Payer Name` per row. No match on the billing profile → payer auto-created `UNVERIFIED` (`PAYER_CREATED`).
`Client Payer Name`	required header	Fallback key when `Payer ID` is blank.
`Network`	optional	`IN`, `OUT`, `IN_NETWORK`, `OUT_OF_NETWORK` (case-insensitive).
`Effective From, Effective To, Submitted, Approved`	optional	`YYYY-MM-DD`. Blank leaves the stored value unchanged on update.
`Committee`	optional	`Y` = true; anything else = false; blank = unchanged.

Duplicate (billing profile, payer, provider) rows within one sheet: the last row wins; earlier ones are reported DUPLICATE_IN_SHEET.

Download the template: Credentialing Import Template.csv

Example¶

Provider NPI,Billing Profile NPI,Billing Profile Tax ID,Payer ID,Client Payer Name,Network,Effective From,Effective To,Submitted,Approved,Committee
,1234567893,831234567,CHP204,,IN,2026-01-01,,2026-06-01,2026-07-15,N
1740398215,1234567893,831234567,CHP204,,OUT,,,,,Y

Row errors¶

Code	Meaning
`PROFILE_UNKNOWN`	No billing profile matches this row's NPI and Tax ID.
`PROVIDER_UNKNOWN`	No non-revoked provider matches this row's Provider NPI.
`PROVIDER_REVOKED`	The provider matching this row's NPI has been revoked.
`INVALID_NPI`	Provider NPI isn't 10 digits.
`INVALID_PAYER`	Both `Payer ID` and `Client Payer Name` are blank.
`INVALID_NETWORK`	`Network` isn't one of the accepted values.
`INVALID_DATE`	A date column isn't `YYYY-MM-DD`.
`DUPLICATE_IN_SHEET`	Another row in this sheet already matched the same billing profile, payer and provider; this row was dropped.
`PAYER_CREATED`	Informational — the row succeeded, and its payer didn't match an existing one so it was auto-created `UNVERIFIED`.

Response¶

Success Response¶

Code: 202 Accepted

200 with the same body means this request replays an already-processed Idempotency-Key.

{
  "import_id": "1e7b9c3d-5a2f-4d8e-b6c1-0f4a7d2e9b35",
  "status": "QUEUED",
  "uploaded_at": "2026-08-27T14:30:00Z"
}

Response Fields¶

Field	Type	Description
`import_id`	string	The import job's id.
`status`	string	Lifecycle state of the record. One of `QUEUED`, `PARSING`, `MATCHING`, `READY`, `FAILED`.
`uploaded_at`	string	When the file was uploaded.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`409 Conflict`	`conflict`	The record conflicts with existing state — see the endpoint's notes.
`412 Precondition Failed`	`precondition_failed`	`If-Match` is stale. Re-read the resource and retry.
`423 Locked`	`locked`	The organisation has a publish in progress. Retry once it finishes.
`428 Precondition Required`	`precondition_required`	`If-Match` is required on this write.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

Poll Get Credentialing Import with the returned import_id for progress.
Idempotency-Key is optional but strongly recommended; without it a retried upload starts a second import. Retrying the same key while an import is in flight returns 409; sending it again after the import finished replays the original result.
status moves QUEUED → PARSING → MATCHING → READY (or FAILED).
A co-signer can't be set from the sheet — assign one afterward with Update Credentialing Row.