Create Billing Profile Payer

Adds a payer to a billing profile, creating the shared payer record if it doesn't already exist.

Endpoint

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

Request Body

Parameter	Type	Required	Description
client_payer_name	string	Yes	Payer name as your organisation knows it.
client_payer_id	string	No	Your own identifier for this payer. Free text, not used for matching.
payer_id	string	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.
plan_type	string	No	Payer category for this relationship. One of COMMERCIAL, MEDICARE, MEDICAID, BCBS, WORKERS_COMP, CHAMPUS, SELF_PAY, OTHER.
enrollment_seeds	object	No	See Enrollment Seeds.

Enrollment Seeds

Parameter	Type	Required	Description
claims	boolean	No	Whether to seed the claims channel into enrollment tracking (enrollment.claims) instead of leaving it NOT_APPLICABLE.
eligibility	boolean	No	Whether to seed the eligibility channel into enrollment tracking (enrollment.eligibility) instead of leaving it NOT_APPLICABLE.
era	boolean	No	Whether to seed the ERA channel into enrollment tracking (enrollment.era) instead of leaving it NOT_APPLICABLE.

Request

curl --location '{base_url}/v2/billing-profiles/b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14/payers' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "client_payer_name": "Cascade Health Plan",
  "client_payer_id": "AET-01",
  "payer_id": "CHP204",
  "plan_type": "COMMERCIAL",
  "enrollment_seeds": {
    "claims": true,
    "eligibility": true,
    "era": true
  }
}'

Response

Success Response

Code: 201 Created

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

The Location header carries the URL of the created resource.

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

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