List Payers¶

Searches the insurance payer registry. Use this to find the payer_id required when creating a coverage.

Endpoint¶

GET /v2/payers

Query Parameters¶

Parameter	Type	Required	Description
`page`	integer	Yes	1-based page number. Defaults to `1`.
`page_size`	integer	Yes	Results per page. Defaults to `25`.
`search`	string	No	Matches payer name or clearing-house code. Omit to list the whole registry.

Request¶

curl --location '{base_url}/v2/payers?page=1&page_size=25' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "items": [
    {
      "id": "8206",
      "name": "Cascade Health Plan",
      "payer_code": "CHP204",
      "parent_name": "Cascade Health",
      "type": "commercial",
      "state": "OR",
      "clearing_house": "CLAIM_MD",
      "capabilities": {
        "eligibility": "SUPPORTED",
        "era": "SUPPORTED",
        "institutional_claims": "SUPPORTED",
        "professional_claims": "SUPPORTED",
        "attachments": "SUPPORTED",
        "secondary": true,
        "workers_comp": false
      }
    }
  ],
  "page": 1,
  "page_size": 25,
  "total": 1,
  "total_pages": 1
}

Response Fields¶

Field	Type	Description
`items`	array of object	The page of results. See Items.
`page`	integer	1-based page number.
`page_size`	integer	Results per page.
`total`	integer	Total results matching the query.
`total_pages`	integer	Total pages available.

Items¶

Field	Type	Description
`id`	string	The payer registry id — the value to send as `payer_id` when creating a coverage. For billing-profile payers send `payer_code` instead.
`name`	string
`payer_code`	string or null	The payer's clearing-house code, kept separate from the registry `id`. Two distinct payers can share a name and be told apart only by this. Send this as `payer_id` when adding a payer to a billing profile.
`parent_name`	string or null
`type`	string or null	Payer category, in lower case.
`state`	string or null
`clearing_house`	string or null
`capabilities`	object	Which transactions this payer supports. See Capabilities.

Capabilities¶

Field	Type	Description
`eligibility`	string	Whether the payer supports real-time eligibility. `ENROLLMENT_REQUIRED` means the clinic must enrol with the payer before it works — materially different from `SUPPORTED`, which is why this is not a boolean. One of `SUPPORTED`, `ENROLLMENT_REQUIRED`, `NOT_SUPPORTED`.
`era`	string	ENROLLMENT_REQUIRED means the clinic must enrol with the payer first. One of `SUPPORTED`, `ENROLLMENT_REQUIRED`, `NOT_SUPPORTED`.
`institutional_claims`	string	ENROLLMENT_REQUIRED means the clinic must enrol with the payer first. One of `SUPPORTED`, `ENROLLMENT_REQUIRED`, `NOT_SUPPORTED`.
`professional_claims`	string	ENROLLMENT_REQUIRED means the clinic must enrol with the payer first. One of `SUPPORTED`, `ENROLLMENT_REQUIRED`, `NOT_SUPPORTED`.
`attachments`	string	ENROLLMENT_REQUIRED means the clinic must enrol with the payer first. One of `SUPPORTED`, `ENROLLMENT_REQUIRED`, `NOT_SUPPORTED`.
`secondary`	boolean	Whether the payer accepts secondary claims.
`workers_comp`	boolean

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.
`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¶

The registry is read-only here — you select a payer, you don't create one.
id is the registry id used by coverages. payer_code is the clearing-house (ClaimMD) id used when attaching a payer to a billing profile.