Update Billing Profile Payer

Updates a billing profile payer and returns the updated record.

Endpoint

PATCH /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.

Headers

Header	Required	Description
If-Match	Yes	ETag from a prior read, or *. A missing value returns 428; a stale one 412.

Request Body

Parameter	Type	Required	Description
client_payer_name	string or null	No	Payer name as your organisation knows it.
client_payer_id	string or null	No	Your own identifier for this payer. Free text, not used for matching.
payer_id	string or null	No	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.
payer_type	string or null	No	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.
plan_type	string or null	No	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.
network_status	string or null	No	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.
accept_assignment	boolean or null	No	Whether the provider accepts the payer's allowed amount as full payment.
fee_schedule_ref	string or null	No	Fee schedule this payer relationship bills against.
effective_from	string or null	No	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	No	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 or null	No	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.
credentialed_by	string or null	No	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	No	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.

Request

Send only the fields to change:

curl --location '{base_url}/v2/billing-profiles/b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14/payers/9f1c8a2e-4b31-4d0a-9c77-2f5ab8e10c44' \
  --request PATCH \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'If-Match: "<etag>"' \
  --header 'Content-Type: application/merge-patch+json' \
  --data '{
  "client_payer_name": "Cascade Health Plan"
}'

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.
409 Conflict	conflict	The record conflicts with existing state — see the endpoint's notes.
412 Precondition Failed	precondition_failed	If-Match is stale. Re-read the resource and retry.
423 Locked	locked	The organisation has a publish in progress. Retry once it finishes.
428 Precondition Required	precondition_required	If-Match is required on this write.
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

• PATCH is a JSON Merge Patch (RFC 7386): an omitted field is left alone, an explicit null clears it, and an array replaces the existing one wholesale.
• Send at least one field — an empty body returns 400.
• Send If-Match with the ETag from a prior read. * opts into last-writer-wins. A stale value returns 412; a missing one returns 428.
• The payer_id path parameter is this row's own id, not the payer registry id.
• In the body, payer_id is the ClaimMD payer id — payer_code on List Payers, not its id. Leave it blank and the payer is created UNVERIFIED until matched.
• Only the fields listed above are accepted; any other returns 400. plan_type (or payer_type; both with different values returns 400) sets the payer type.
• credentialed_by and routed_payer_id are for billing-profiles organisations: elsewhere sending any of them — even as null — returns 400 BILLING_PROFILES_ONLY.
• On a billing-profiles organisation network_status, effective_from and effective_to write the clinic (GROUP) credentialing row of this payer's plan instead of the payer row, which is created when a date or IN_NETWORK is sent: IN_NETWORK keeps the row, OUT_OF_NETWORK ends a row that covered past dates today, otherwise clears its dates. A change that would leave a past date of service uncovered on a row billing already holds returns 400 PAST_COVERAGE_LOCKED. A plan override can't change the fields its DEFAULT row owns (payer type, fee schedule, enrollment).
• 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.
• When onboarding refuses a write, each errors[] entry carries a code naming the rule that failed, and field names the field in snake_case, as this API spells it (an empty field means the whole row, or the whole create, not one field). A 400 for a body that fails this API's own schema check (an unknown field, a wrong type, a value outside the listed ones) has no code; its field is the JSON pointer of the offending value (/effective_from) or the name of the missing field. Codes from this endpoint: PAYER_ENTRY_UNKNOWN (routed_payer_id isn't a row of this profile), PAYER_ID_HELD_BY_HISTORY (409, on payer_id: a history credentialing row on any billing profile that carries this payer already uses the new ClaimMD payer id, and this payer has its own row for the same provider; remove that row, let the removal publish, then retry), PAST_COVERAGE_LOCKED, ROUTED_PAYER_NOT_ATTACHED, ROUTED_PAYER_SELF, ROUTED_PAYER_NO_PAYER_ID (the routed payer has no ClaimMD payer_id), ROUTED_PAYER_CHAIN, PAYER_ROUTED_TO (another payer routes to this one), PLAN_OVERRIDE_FIELD_LOCKED, BILLING_PROFILES_ONLY.