Skip to main content

​
Choose a payer

Call GET /v4/payers?q=blue&limit=25 with the practice organization header and an API key authorized for read:payers. This returns { data: { payers, nextCursor } }. Each payer includes id, name, payerCode, payerCodeType, instanceId, instanceLabel, isActive, and ehrStatus. Search matches name words without case or punctuation sensitivity, literal electronic codes, or an exact source UUID. An empty query lists active practice payers, including records with no code or patient policies. Records without an EHR payer id are never listed, because POST /v4/patients/{id}/insurance:exact cannot accept them. Keep q unchanged and pass nextCursor as cursor for the next page; null means the end. limit defaults to 25 and is capped at 100; q is limited to 200 characters. Paging uses ascending source UUID, not relevance ranking. Display the name, code namespace, and source instance together. Equal names or codes can represent distinct source records and must remain separate choices. Store the selected id, never the user’s unfinished search text. GET /v4/payers/{id} resolves saved selections, including inactive or deleted source records still retained by MaxAI. Inactive records and records without an EHR payer id are absent from search, including an exact-UUID q, and must not be offered for new selections. Another practice’s records and global records return 404. Missing read:payers on either the installation or API key returns 403. Retry rate limits according to Retry-After; preserve the selected record through failed searches.

​
Payers for a patient’s chart

POST /v4/patients/{id}/insurance:exact accepts only payers in the chart’s EHR instance. Pick from that set:
  • GET /v4/patients/{id} and POST /v4/patients return the chart’s instanceId (a raw UUID on every version, equal to instanceId on payer records). Other v4 resources may show the same instance as ins_…; send either form as a query param.
  • GET /v4/payers?patientId={id} lists that instance’s payers. It also needs read:patients; without it the request is a 403. An unknown patient is a 404 patient_not_found.
  • GET /v4/payers?instanceId={instanceId} needs only read:payers. An instanceId that matches no instance returns an empty list, so take it from the patient or from GET /v4/payers/capabilities. Capabilities lists every instance but not which one a new chart lands in; see below for that.
Pass only one of patientId, instanceId and newChart=true (400). q, cursor and limit work as above. A listed payer can still be refused with 422 payer_not_writable (for example ehr_payer_missing), so handle that error. To file secondary coverage, send coverageOrder: 2 (1 is primary). The policy is then written at exactly that rank or refused with nothing written: 409 coverage_rank_taken when another policy holds it, 409 coverage_rank_out_of_order when the chart has no primary yet. Without coverageOrder the EHR files the policy at its next free rank. Send Prefer: handling=strict with these requests. A server without these filters then answers 400 instead of ignoring them and returning every payer in the practice.

​
Payers for a chart you are about to create

Before POST /v4/patients, call GET /v4/payers?newChart=true. It lists the payers of the EHR instance that create would put the chart in. If the create will send primaryFacilityId, pass the same value here: GET /v4/payers?newChart=true&primaryFacilityId={facilityId}. Use a facility from GET /v4/facilities (dashed UUID or fac_…). Omit it when the create omits it or sends an empty value. It needs only read:payers. It answers 400 for a primaryFacilityId outside your organization and 503 no_booking_identity when no live system connector can create the chart. q, cursor and limit work as above. Send Prefer: handling=strict here too. The answer can change if the practice’s connectors change before you create the chart. After POST /v4/patients, compare the picked payer’s instanceId with the response’s instanceId. If they differ, pick again with GET /v4/payers?instanceId={instanceId} from that response.

​
Preserve the identity namespace

payerId on insurance policies, claims, and ERA service lines is the same raw source UUID used by the directory on all API versions. It identifies a MaxAI source payer record, not a worldwide carrier or clearinghouse code. Store it with the organization boundary. payerCode is an electronic identifier and may be null. Preserve leading zeroes. payerCodeType describes its namespace; the same code can occur on different records or EHR instances. Neither a name nor a code can prove that two source records are the same payer. Manufacturer portal Account IDs are separate identifiers. The source relationship matters:
  • A policy reports its insurance plan’s payer.
  • A claim reports its own payer; payerPosition is a nullable number (1 primary, 2 secondary). primaryInsurance describes bill coverage and must not replace a secondary claim’s payer.
  • An ERA line reports its ERA header’s payer, including unmatched or undated lines. It does not borrow the patient’s current coverage.
An explicit null is unknown. Do not fill it from a previous payer observation or a similarly named record. Read the identity fields as a tuple. A joined payer name or code can change without the policy, claim, or ERA line’s updatedAt changing, so periodically reconcile retained resources in addition to incremental sync. A missing resource in a partial scan does not establish deletion. Source IDs alone do not allocate bill-level money between primary and secondary payers. Verify the amount’s own provenance before assigning it to a payer.