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. 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 are absent from search 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.

​
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.