Patient billing

List a patient's billing accounts

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

Lists the patient's billing accounts: FHIR Account resources of type PBILLACCT whose subject is the patient. Ovok makes one per patient, with the first plan or invoice, and it names the plan coverage. Each clinic that enters a charge for the patient gets its own account too: clinicId names the clinic, and coverageIds the patient's coverages in order.

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, else 403 PATIENT_BILLING_NOT_ALLOWED or 404 PATIENT_BILLING_PATIENT_NOT_FOUND.

Example

curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/accounts' \  -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}$

Response Body

The patient's billing accounts.

application/json
  1. response
items*array<>
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/accounts'
Example Response
{  "items": [    {      "id": "string",      "version": "string",      "patientId": "string",      "status": "string",      "clinicId": "string",      "coverageIds": [        "string"      ]    }  ]}

Set a patient's plan PUT

Sets the app plan the patient pays for, from your server's payment or store webhooks, or ends it. Ovok keeps one plan `Coverage` per patient, names it on the patient's billing `Account`, and tags the `Patient` with the plan so `_tag` finds patients by plan. **Scope:** a project admin or an admin ClientApplication, in a project with `PATIENT_BILLING_ENABLED` on. Anyone else: **403** `PATIENT_BILLING_NOT_ALLOWED`. ## Behaviour - `plan` is your coding of the plan; `period` is the paid period, and may not end before it starts (**422**). The plan is written as sent, so send the whole of it every time. - The first plan answers **201** with `Location`; later ones **200**. Sending the same plan again changes nothing. - `{ "plan": null }` ends the plan: it is cancelled, its period ending no later than now, and the tag is removed. A patient with no plan answers **204**. - Retries and late webhooks land on the same records. ## Example ```bash curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/plan' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "plan": { "system": "https://example.com/plans", "code": "plus", "display": "Plus" }, "period": { "start": "2026-11-02T10:14:00Z", "end": "2026-12-02T10:14:00Z" } }' ```

Get a billing account GET

Gets one billing account. **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 account's patient. An account you cannot see answers **404** `ACCOUNT_NOT_FOUND`. ## Example ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/accounts/<accountId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```