List Billing Profile Payers¶

Lists the payers attached to a billing profile.

Endpoint¶

GET /v2/billing-profiles/{billing_profile_id}/payers

Path Parameters¶

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

Query Parameters¶

Parameter	Type	Required	Description
`q`	string	No	Substring match on `client_payer_name`, `master_name`, `payer_id`, `client_payer_id`.
`state`	string	No	Whether this payer mapping is confirmed against the clearing-house master.
`claims_status`	string	No	Filter by the claims channel's enrollment status.
`eligibility_status`	string	No	Filter by the eligibility channel's enrollment status.
`era_status`	string	No	Filter by the ERA channel's enrollment status.
`limit`	integer	No	Page size. Defaults to 50, max 500.
`cursor`	string	No	Opaque pagination cursor from a previous page's `next_cursor`.

Request¶

curl --location '{base_url}/v2/billing-profiles/b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14/payers' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response¶

Success Response¶

Code: 200 OK

{
  "data": [
    {
      "id": "9f1c8a2e-4b31-4d0a-9c77-2f5ab8e10c44",
      "billing_profile_id": "b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14",
      "payer_sec_id": null,
      "client_payer_name": "Cascade Health Plan",
      "client_payer_id": "AET-01",
      "payer_id": "CHP204",
      "master_name": "Cascade Health Plan",
      "state": "VERIFIED",
      "plan_type": "COMMERCIAL",
      "network_status": "IN_NETWORK",
      "accept_assignment": true,
      "fee_schedule_ref": null,
      "effective_from": "2026-01-01",
      "effective_to": null,
      "enrollment": {
        "claims": {
          "status": "NOT_STARTED",
          "branch": "FIXED",
          "exceptions": {}
        },
        "eligibility": {
          "status": "NOT_STARTED",
          "branch": "FIXED",
          "exceptions": {}
        },
        "era": {
          "status": "NOT_STARTED",
          "branch": "FIXED",
          "exceptions": {}
        }
      },
      "issues": [
        {
          "code": "PAYER_ID_NOT_IN_MASTER",
          "severity": "error",
          "message": "Payer id not found in the clearing-house master list."
        }
      ],
      "clearing_house": "CLAIM_MD",
      "rollup_statuses": {
        "claims": "IN_PROGRESS",
        "eligibility": "COMPLETE",
        "era": "NOT_APPLICABLE"
      },
      "display_labels": null,
      "profile_payer_contract_id": null
    }
  ],
  "next_cursor": null
}

Response Fields¶

Field	Type	Description
`data`	array of object	See Data.
`next_cursor`	string	Cursor for the next page. `null` on the last page.

Data¶

Field	Type	Description
`id`	string	This payer row's own id.
`billing_profile_id`	string	The billing profile this record belongs to.
`payer_sec_id`	string or null	Id of the underlying payer record, shared across every billing profile that uses it.
`client_payer_name`	string or null	Payer name as your organisation knows it.
`client_payer_id`	string or null	Your own identifier for this payer. Free text, not used for matching.
`payer_id`	string or null	ClaimMD payer id — the `payer_code` from List Payers, not its `id`. Matched against the clearing-house master; an unknown value creates the payer as `UNVERIFIED`.
`master_name`	string or null	The payer's name in the clearing-house master list, once resolved.
`state`	string	Whether this payer mapping is confirmed against the clearing-house master. One of `VERIFIED`, `UNVERIFIED`, `PAPER_ONLY`, `ARCHIVED`.
`plan_type`	string or null	Payer category for this relationship. One of `COMMERCIAL`, `MEDICARE`, `MEDICAID`, `BCBS`, `WORKERS_COMP`, `CHAMPUS`, `SELF_PAY`, `OTHER`.
`network_status`	string or null	Whether the relationship is in-network or out-of-network. One of `IN_NETWORK`, `OUT_OF_NETWORK`.
`accept_assignment`	boolean or null	Whether the provider accepts the payer's allowed amount as full payment.
`fee_schedule_ref`	string or null	Fee schedule this payer relationship bills against.
`effective_from`	string or null
`effective_to`	string or null
`enrollment`	object	Enrollment status per channel — `claims`, `eligibility` and `era` — each with a per-dimension `status` (`NOT_STARTED`, `REQUIREMENT_GATHERING`, `APPLICATION_SUBMITTED`, `COMPLETE`, `NOT_APPLICABLE`), a `branch` (`FIXED`, `MANUAL`, `NA`), and per-provider `exceptions` mapping a provider id to its own status. See Enrollment.
`issues`	array of object	Problems found while resolving this payer — for example an unrecognised payer id. See Issues.
`clearing_house`	string or null	One of `CLAIM_MD`, `AVAILITY`, `OFFICE_ALLY`, `OTHER`.
`rollup_statuses`	object	Aggregated enrollment status per channel: `NOT_STARTED`, `IN_PROGRESS`, `COMPLETE`, `NOT_APPLICABLE`. `IN_PROGRESS` is rollup-only — it never appears in `enrollment.*.status`.
`display_labels`	any	Precomputed label strings for the dashboard's payer list.
`profile_payer_contract_id`	integer or null	A stable id in the downstream billing system, once published. `null` before publish.

Enrollment¶

Field	Type	Description
`claims`	object	Whether to seed the claims channel into enrollment tracking (`enrollment.claims`) instead of leaving it `NOT_APPLICABLE`. See Claims.
`eligibility`	object	Whether to seed the eligibility channel into enrollment tracking (`enrollment.eligibility`) instead of leaving it `NOT_APPLICABLE`. See Eligibility.
`era`	object	Whether to seed the ERA channel into enrollment tracking (`enrollment.era`) instead of leaving it `NOT_APPLICABLE`. See Era.

Claims¶

Field	Type	Description
`status`	string	Lifecycle state of the record. One of `NOT_STARTED`, `REQUIREMENT_GATHERING`, `APPLICATION_SUBMITTED`, `COMPLETE`, `NOT_APPLICABLE`.
`branch`	string	One of `FIXED`, `MANUAL`, `NA`.
`exceptions`	object

Eligibility¶

Field	Type	Description
`status`	string	Lifecycle state of the record. One of `NOT_STARTED`, `REQUIREMENT_GATHERING`, `APPLICATION_SUBMITTED`, `COMPLETE`, `NOT_APPLICABLE`.
`branch`	string	One of `FIXED`, `MANUAL`, `NA`.
`exceptions`	object

Era¶

Field	Type	Description
`status`	string	Lifecycle state of the record. One of `NOT_STARTED`, `REQUIREMENT_GATHERING`, `APPLICATION_SUBMITTED`, `COMPLETE`, `NOT_APPLICABLE`.
`branch`	string	One of `FIXED`, `MANUAL`, `NA`.
`exceptions`	object

Issues¶

Field	Type	Description
`code`	string	Machine-readable issue code.
`severity`	string	Whether this issue blocks resolution or is informational.
`message`	string	Human-readable detail for this issue.

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¶

state filters on VERIFIED, UNVERIFIED, PAPER_ONLY, ARCHIVED.