Patient billing

List a patient's benefit statements

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/patient-billing/patients/{patientId}/benefit-statements

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

curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/benefit-statements' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

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

Query Parameters

cursor?string

nextCursor from the previous page.

Length1 <= length <= 4000
limit?integer
Range1 <= value <= 100
Default30

Response Body

What the patient's insurers decided on their claims, latest first.

application/json
  1. response
items*array<>
nextCursor*string
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/benefit-statements'
Example Response
{  "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 }' ```