Patient billing

Record an eligibility check

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/patient-billing/coverages/{coverageId}/eligibility-checks

Records a check that the coverage is in force, as the clinic ran it, such as the health card's online check in its practice software: a FHIR CoverageEligibilityRequest and the insurer's CoverageEligibilityResponse. Ovok does not reach the insurer itself.

Scope: the caller's project, with PATIENT_BILLING_ENABLED on.

Behaviour

  • Your access policy must grant patient_billing_claims create and let you read the patient, else 403 PATIENT_BILLING_NOT_ALLOWED. A coverage you cannot see answers 404 COVERAGE_NOT_FOUND.
  • A self-pay coverage has no insurer: 422 COVERAGE_NOT_INSURED. clinicId must be a clinic the patient is enrolled with, else 422 BILLING_CLINIC_INVALID.
  • inForce is what the insurer answered; outcome: error records a check that failed. Answers 201 with Location: /v1/patient-billing/eligibility-checks/<id>.
  • identifier is optional. With it, the same identifier for the same patient again answers the check already recorded, with 200.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/coverages/<coverageId>/eligibility-checks' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \  -H 'Content-Type: application/json' \  -d '{ "clinicId": "<clinicId>", "servicedOn": "2026-11-18", "outcome": "complete", "inForce": true }'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

coverageId*string

The coverage id.

Match^[A-Za-z0-9\-.]{1,64}$

Request Body

application/json
  1. body
identifier?

Your id for the check: the same identifier again is the same check.

Defaultnull
clinicId*string

The clinic (Organization) that checked; one the patient is enrolled with.

Match^[A-Za-z0-9\-.]{1,64}$
checkedAt?string

When the check ran; now when left out.

Formatdate-time
Defaultnull
servicedOn?string

The day of service the check was for.

Defaultnull
outcome?string

complete when the insurer answered, error when the check failed.

Default"complete"
Value in"complete""error"
inForce*boolean

Whether the insurer confirmed the coverage is in force.

disposition?string

The insurer's message, if any.

Length1 <= length <= 200
Defaultnull

Response Body

A check with this identifier was recorded before; this is it.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

responseId*string
patientId*string
coverageId*string
clinicId*string
insurer*
checkedAt*string
servicedOn*string
outcome*string
inForce*boolean
disposition*string
Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/coverages/string/eligibility-checks' \  -H 'Content-Type: application/json' \  -d '{  "clinicId": "string",  "inForce": true}'
Example Response
{  "id": "string",  "version": "string",  "responseId": "string",  "patientId": "string",  "coverageId": "string",  "clinicId": "string",  "insurer": {    "id": "string",    "ik": "string",    "name": "string"  },  "checkedAt": "string",  "servicedOn": "string",  "outcome": "string",  "inForce": true,  "disposition": "string"}

List a patient's benefit statements GET

Lists what the patient's insurers decided on their claims, latest first: FHIR `ExplanationOfBenefit` statements, each with the services claimed, what was paid per category and the payment. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_invoices` `read` and let you read the patient, the same as the patient's invoices, so patients read their own statements. Else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - A statement exists once the insurer's answer to a claim is recorded, and follows it when it changes. - `limit` is 1 to 100 (30 when left out). Send `nextCursor` back as `cursor` for the next page; a cursor no page gave answers **400** `PATIENT_BILLING_CURSOR_INVALID`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/benefit-statements' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Get an eligibility check GET

Reads one eligibility check and its answer. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_claims` `read`, else **403** `PATIENT_BILLING_NOT_ALLOWED`. A check whose patient you cannot read answers **404** `ELIGIBILITY_CHECK_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/eligibility-checks/<checkId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```