Patient billing

Get an eligibility check

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

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

curl 'https://api.sandbox.ovok.com/v1/patient-billing/eligibility-checks/<checkId>' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

checkId*string

The eligibility check id.

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

Response Body

The check and its answer.

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 GET 'https://api.sandbox.ovok.com/v1/patient-billing/eligibility-checks/string'
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"}

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 }' ```

Record an insurer's payment POST

Records an insurer's payment to a clinic from its remittance: a FHIR `PaymentReconciliation` that splits it across the claims it pays, and a `PaymentNotice` per claim. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_claims` `update` and let you read each claim's patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `CLAIM_NOT_FOUND`. - Every claim must be active, of the clinic `clinicId` names, and to the same insurer, which is the payer. The allocations must add up to `amount`, in its currency. Else **422** `PAYMENT_ALLOCATION_INVALID`. - Amounts are more than zero. Every claim's total must be in the payment's currency. - `identifier` is the insurer's id for the payment: the same identifier at the same clinic again answers the payment already recorded, with **200**. A new one answers **201** with `Location: /v1/patient-billing/payments/<id>`. - It is recorded holding the locks of the patients whose claims it pays, so none is withdrawn meanwhile; another change to one of them running at the same time answers **409**; send it again. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/payments' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "identifier": { "system": "https://example.com/remittances", "value": "R-2026-11-0042" }, "clinicId": "<clinicId>", "paidOn": "2026-11-30", "amount": { "value": 31.62, "currency": "EUR" }, "allocations": [{ "claimId": "<claimId>", "amount": { "value": 31.62, "currency": "EUR" } }], "disposition": null }' ```