Create Coverage

Adds an insurance plan to a patient.

Endpoint

POST /v2/patients/{patient_id}/coverages

Path Parameters

Parameter	Type	Required	Description
patient_id	string	Yes	The patient. Correlate on this — it's a stable id, and there's no external-reference field.

Request Body

Parameter	Type	Required	Description
payer_id	string	Yes	Payer registry id, from List Payers. Not the same as payer_code.
member_id	string	Yes	The member's id on the plan.
rank	string	No	The patient's general coordination-of-benefits order. Separate from a case's coverage pointers, which say which plans bill that episode — they legitimately differ. null when the card is unallocated. One of PRIMARY, SECONDARY, TERTIARY.
group_number	string	No
group_name	string	No
plan_name	string	No
plan_type	string	No
coverage_type	string	No	How this plan is billed. One of COMMERCIAL, MEDICARE, MEDICAID, WORKERS_COMP, MVC, SELF_PAY.
subscriber	object	No	The plan's subscriber, when it is not the patient. See Subscriber.
effective_from	string (date)	No	YYYY-MM-DD.
effective_to	string (date)	No	YYYY-MM-DD.

Subscriber

Parameter	Type	Required	Description
relationship	string	Yes	The subscriber's relationship to the patient. One of SELF, SPOUSE, CHILD, OTHER.
first_name	string or null	Yes
last_name	string or null	Yes
date_of_birth	string (date) or null	Yes	YYYY-MM-DD.

Request

curl --location '{base_url}/v2/patients/63120/coverages' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "payer_id": "8206",
  "member_id": "K631204418",
  "rank": "PRIMARY",
  "group_number": "GRP-4471",
  "group_name": null,
  "plan_name": "Cascade Choice PPO",
  "plan_type": "PPO",
  "coverage_type": "COMMERCIAL",
  "subscriber": {
    "relationship": "SELF",
    "first_name": "Morgan",
    "last_name": "Delgado",
    "date_of_birth": "1991-07-23"
  },
  "effective_from": "2026-01-01",
  "effective_to": null
}'

Response

Success Response

Code: 201 Created

{
  "id": "90455",
  "patient_id": "63120",
  "rank": "PRIMARY",
  "payer": {
    "id": "90455",
    "name": "Example Therapy \u2014 Riverside"
  },
  "member_id": "K631204418",
  "group_number": "GRP-4471",
  "group_name": null,
  "plan": {
    "name": "Example Therapy \u2014 Riverside",
    "type": "PPO"
  },
  "coverage_type": "COMMERCIAL",
  "subscriber": {
    "relationship": "SELF",
    "first_name": "Morgan",
    "last_name": "Delgado",
    "date_of_birth": "1991-07-23"
  },
  "effective_from": "2026-01-01",
  "effective_to": null,
  "status": "ACTIVE",
  "created_at": "2026-08-27T14:30:00Z",
  "updated_at": "2026-08-27T14:30:00Z"
}

The Location header carries the URL of the created resource.

Response Fields

Field	Type	Description
id	string	The coverage id.
patient_id	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
rank	string or null	The patient's general coordination-of-benefits order. Separate from a case's coverage pointers, which say which plans bill that episode — they legitimately differ. null when the card is unallocated. One of PRIMARY, SECONDARY, TERTIARY.
payer	object	The insurance payer, as a registry reference. See Payer.
member_id	string or null	The member's id on the plan.
group_number	string or null
group_name	string or null
plan	object	The plan on this coverage. See Plan.
coverage_type	string or null	How this plan is billed. One of COMMERCIAL, MEDICARE, MEDICAID, WORKERS_COMP, MVC, SELF_PAY.
subscriber	object or null	The plan's subscriber, when it is not the patient. See Subscriber.
effective_from	string (date) or null	YYYY-MM-DD.
effective_to	string (date) or null	YYYY-MM-DD.
status	string	Lifecycle state of the record.
created_at	string (date-time) or null
updated_at	string (date-time) or null

Payer

Field	Type	Description
id	string or null	The coverage id.
name	string or null

Plan

Field	Type	Description
name	string or null
type	string or null

Subscriber

Field	Type	Description
relationship	string	The subscriber's relationship to the patient. One of SELF, SPOUSE, CHILD, OTHER.
first_name	string or null
last_name	string or null
date_of_birth	string (date) or null	YYYY-MM-DD.

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

• payer_id is a registry id from List Payers and is required.