> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Payer identities

> Search practice payers and preserve source identity separately from electronic codes

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