Skip to content

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.
include_plan_overrides boolean No Also list each payer's plan override rows, right after its DEFAULT row. Default false: DEFAULT rows only.
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",
      "payer_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,
      "plan": "DEFAULT",
      "credentialed_by": "EACH_THERAPIST"
    }
  ],
  "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 — the same value as payer_type, and the field to send until the payer-credentialing release; it stays accepted after it as a deprecated alias. Sending both with different values returns 400. One of COMMERCIAL, MEDICARE, MEDICAID, BCBS, WORKERS_COMP, CHAMPUS, SELF_PAY, OTHER.
payer_type string or null Payer category for this relationship — the new name of plan_type. Arrives with the payer-credentialing release; until then send plan_type. 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. On a billing-profiles organisation it's derived from the clinic (GROUP) credentialing row of this payer and plan — IN_NETWORK when that row is in network on its dates — and writing it updates that row: IN_NETWORK keeps or creates it, OUT_OF_NETWORK ends a row that covered past dates today, otherwise clears its dates. 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 First day of the payer contract, YYYY-MM-DD. On a billing-profiles organisation it's the date of the clinic (GROUP) credentialing row for this payer and plan, and writing it writes that row.
effective_to string or null Last day of the payer contract, YYYY-MM-DD; null while open-ended. On a billing-profiles organisation it's the date of the clinic (GROUP) credentialing row for this payer and plan, and writing it writes that row.
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.
plan string DEFAULT (every plan) or the card plan type this row overrides. Billing-profiles organisations only; absent elsewhere.
credentialed_by string Who the payer credentials: EACH_THERAPIST, CLINIC_ONLY (the clinic's contract covers its therapists; provider rows are optional) or NONE. A row that never set it reads EACH_THERAPIST. Billing-profiles organisations only. One of EACH_THERAPIST, CLINIC_ONLY, NONE.
routed_payer_id string or null Another payer on this billing profile whose contract this payer's claims are sent under — for a payer that hands its claims to another company. The other payer's row id (its DEFAULT row); it must not route anywhere itself. null clears. Billing-profiles organisations only; left out of responses when unset.

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.
  • One row per payer — its DEFAULT row — unless include_plan_overrides=true, which also lists each payer's plan override rows right after its DEFAULT row. A plan override has its own id.
  • Plans, payer policy and the dated credentialing facts exist on billing-profiles organisations only; elsewhere those fields are absent from responses.
  • payer_type, plan, include_plan_overrides, the plan override and the payer policy fields (credentialed_by, routed_payer_id) arrive with the payer-credentialing release. Until it reaches your environment they are absent from responses and refused on writes (400); send the payer type as plan_type, which keeps working after it.