Patient billing

List a patient's charges

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

Lists the patient's charges, latest service first, a page at a time.

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

Behaviour

  • Your access policy must grant patient_billing_charges read and let you read the patient, else 403 PATIENT_BILLING_NOT_ALLOWED or 404 PATIENT_BILLING_PATIENT_NOT_FOUND.
  • clinicId lists only that clinic's charges. Every status is listed; status says which are still billable.
  • 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>/charges?clinicId=<clinicId>' \  -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
clinicId?string

Only the charges of this clinic.

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

Response Body

The patient's charges, latest service first.

application/json
  1. response
items*array<>
nextCursor*string
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/charges'
Example Response
{  "items": [    {      "id": "string",      "version": "string",      "patientId": "string",      "clinicId": "string",      "accountId": "string",      "identifier": {        "system": "string",        "value": "string"      },      "status": "string",      "code": {        "system": "string",        "code": "string",        "display": "string"      },      "occurredAt": "string",      "quantity": 0,      "unitPrice": {        "value": 0,        "currency": "string"      },      "total": {        "value": 0,        "currency": "string"      },      "overrideReason": "string",      "enteredAt": "string"    }  ],  "nextCursor": "string"}

Remove a price DELETE

Takes a price off the price list. New charges for its code then need a new price or a `priceOverride`. **Scope:** a project admin or an admin ClientApplication, in a project with `PATIENT_BILLING_ENABLED` on. Anyone else: **403** `PATIENT_BILLING_NOT_ALLOWED`. ## Behaviour - The price is retired, not deleted, so the charges entered at it still name it. Removing it again answers **204** too. - Setting the code's price again (`POST /v1/patient-billing/prices`) puts it back on the list. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/patient-billing/prices/<priceId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Enter a charge POST

Enters a charge: one billable service a clinic gave the patient, as a FHIR `ChargeItem`. It goes on the account the clinic keeps for the patient, which Ovok makes with the first charge and which names the patient's coverages in order. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_charges` `create` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - `clinicId` must be a clinic (Organization) the patient is enrolled with, else **422** `BILLING_CLINIC_INVALID`. - The unit price comes from the price list, as it applies on the day of `occurredAt`; without one, **422** `CHARGE_PRICE_MISSING`. `priceOverride` sets the unit price instead and needs an `overrideReason`. - The charge keeps its unit price, so later price changes leave it alone. `total` is the unit price times `quantity`. - `identifier` is optional. With it, the same identifier for the same patient again answers the charge already entered, with **200**. A new charge answers **201** with `Location: /v1/patient-billing/charges/<id>`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/charges' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "clinicId": "<clinicId>", "code": { "system": "http://fhir.de/CodeSystem/kbv/ebm", "code": "03040", "display": null }, "occurredAt": "2026-11-18", "quantity": 1 }' ```