Get Billing Profile Payer

Returns a single billing profile payer.

Endpoint

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

Path Parameters

Parameter	Type	Required	Description
billing_profile_id	string	Yes	The billing profile this record belongs to.
payer_id	string	Yes	This payer row's own id (from List Billing Profile Payers), not the payer registry id.

Request

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

Response

Success Response

Code: 200 OK

{
  "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"
}

Response Fields

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

• Keep the ETag from this response — writes require it as If-Match.
• The payer_id path parameter is this row's own id — from List Billing Profile Payers. It isn't the payer registry id; that's the body's own payer_id field, set by Create Billing Profile Payer.
• 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.