Import Billing Profile Payers¶

Uploads a spreadsheet of payers to create or update in bulk.

Endpoint¶

POST /v2/billing-profiles/{billing_profile_id}/payers/imports

Path Parameters¶

Parameter	Type	Required	Description
`billing_profile_id`	string	Yes	The billing profile this record belongs to.

Request Body¶

Part	Type	Required	Description
`file`	file	Yes	Spreadsheet, .xlsx or .csv, max 10 MB. First sheet, header row first.
`overwrite`	boolean	No	Replace existing payer rows that match; default false.

Request¶

curl --location '{base_url}/v2/billing-profiles/b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14/payers/imports' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Idempotency-Key: 7d3f…' \
  --form 'file=@payers.xlsx' \
  --form 'overwrite=true'

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.

Header	Required	Cell rules
`Payer Names`	required header	Payer name as your organisation knows it. Stored as `client_payer_name`.
`Name on ClaimMD`	required header	Name in the clearing-house master. Optional per row; a mismatch is recorded as an informational issue.
`Confirmed Payer ID's on ClaimMD`	required header, required per row	ClaimMD payer id (`payer_code` on List Payers). Blank or a placeholder (`-`, `N/A`, `NONE`, `TBD`, `?`) leaves the row `UNVERIFIED` with `MISSING_KEY`. `SELFPAY` is reserved and rejected. Unknown in the master → `UNVERIFIED` with `PAYER_ID_NOT_IN_MASTER`. Duplicates within the sheet: first row wins, later rows flagged.
`Payer Type`	optional	`COMMERCIAL`, `MEDICARE`, `MEDICAID`, `BCBS`, `WORKERS_COMP`, `CHAMPUS`, `SELF_PAY`, `OTHER`, or common aliases (`mcare`, `wc`, `tricare`, …). Unknown → `OTHER` with a warning. Blank → inherited from the master.
`Client Payer ID`	optional	Your own identifier. Not used for matching.

Download the template: Payer Import Template.xlsx

Example¶

Payer Names,Name on ClaimMD,Confirmed Payer ID's on ClaimMD,Payer Type,Client Payer ID
Cascade Health Plan,Cascade Health Plan,CHP204,COMMERCIAL,AET-01
Example Regional Health,Example Regional Health,MCR100,MEDICARE,

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",
  "billing_profile_id": "b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14",
  "status": "QUEUED",
  "uploaded_at": "2026-08-27T14:30:00Z"
}

Response Fields¶

Field	Type	Description
`import_id`	string	The import job's id.
`billing_profile_id`	string or null	The billing profile this record belongs to.
`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 Payer 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).