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.

Request

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 'Content-Type: application/merge-patch+json' \
  --data '{}'

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

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