List a patient's benefit statements
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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_invoicesreadand let you read the patient, the same as the patient's invoices, so patients read their own statements. Else 403PATIENT_BILLING_NOT_ALLOWEDor 404PATIENT_BILLING_PATIENT_NOT_FOUND. - A statement exists once the insurer's answer to a claim is recorded, and follows it when it changes.
limitis 1 to 100 (30 when left out). SendnextCursorback ascursorfor the next page; a cursor no page gave answers 400PATIENT_BILLING_CURSOR_INVALID.
Example
curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/benefit-statements' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'bearerAuthorizationBearer <JWT>patientId*stringThe patient id.
^[A-Za-z0-9\-.]{1,64}$cursor?stringnextCursor from the previous page.
1 <= length <= 4000limit?integer1 <= value <= 10030What the patient's insurers decided on their claims, latest first.
application/json- response
items*array<>nextCursor*stringcurl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/benefit-statements'{ "items": [ { "id": "string", "version": "string", "patientId": "string", "claimId": "string", "clinicId": "string", "insurer": { "id": "string", "ik": "string", "name": "string" }, "outcome": "string", "disposition": "string", "createdAt": "string", "items": [ { "sequence": 0, "code": { "system": "string", "code": "string", "display": "string" }, "servicedOn": "string", "net": { "value": 0, "currency": "string" }, "adjudication": [ { "category": "string", "amount": { "value": 0, "currency": "string" } } ] } ], "total": [ { "category": "string", "amount": { "value": 0, "currency": "string" } } ], "payment": { "paidOn": "string", "amount": { "value": 0, "currency": "string" } } } ], "nextCursor": "string"}Record the insurer's answer PUT
Records the insurer's answer to a claim, as clinic staff got it on paper or in a remittance: a FHIR `ClaimResponse` with the outcome, each item's adjudication and the payment it announces. The patient's statement about it, a FHIR `ExplanationOfBenefit`, is derived from the claim and the answer. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_claims` `update` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `CLAIM_NOT_FOUND`. - A claim has one answer: the first answers **201** with `Location: /v1/patient-billing/claims/<claimId>`, a later one replaces it with **200**, and the statement follows. - `outcome` is `complete`, `partial`, or `error` for a rejected claim. Each item names the claim item it adjudicates by `itemSequence`, with amounts per category (`submitted`, `eligible`, `benefit`, `copay`, `deductible`); totals are summed per category. - An unknown `itemSequence` or an amount in another currency than the claim's answers **422** `CLAIM_RESPONSE_INVALID`. A withdrawn claim answers **409** `CLAIM_CANCELLED`. ## Example ```bash curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-billing/claims/<claimId>/response' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "outcome": "complete", "items": [{ "itemSequence": 1, "adjudication": [{ "category": "benefit", "amount": { "value": 15.81, "currency": "EUR" } }] }], "payment": { "paidOn": "2026-11-30", "amount": { "value": 15.81, "currency": "EUR" } } }' ```
Record an eligibility check POST
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 ```bash 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 }' ```