Run an Eligibility Check

Runs a real-time eligibility check and records it against the coverage.

Endpoint

POST /v2/patients/{patient_id}/coverages/{coverage_id}/eligibility-checks

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.
coverage_id	string	Yes	One of the patient's coverages, from GET /v2/patients/{patient_id}/coverages.

Request

curl --location '{base_url}/v2/patients/63120/coverages/90455/eligibility-checks' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response

Success Response

Code: 201 Created

{
  "id": "90455",
  "coverage_id": "90455",
  "status": "ACTIVE",
  "plan_active": true,
  "authorized_visit_count": 24,
  "used_visit_count": 6,
  "remaining_visit_count": 18,
  "checked_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.
coverage_id	string	One of the patient's coverages, from GET /v2/patients/{patient_id}/coverages.
status	string	Lifecycle state of the record.
plan_active	boolean or null
authorized_visit_count	integer or null	Visits the payer authorized.
used_visit_count	integer or null	Visits consumed against the authorization.
remaining_visit_count	integer or null	Visits still available.
checked_at	string (date-time) or null	When the check ran.

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

• Whether a payer supports real-time eligibility at all is reported by List Payers as capabilities.eligibility. ENROLLMENT_REQUIRED means the clinic must enrol with the payer first.