Patient billing

Submit a claim

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
POST
/v1/patient-billing/claims/{claimId}/submission

Submits a claim through the project's claim channel, and answers what the channel made of it. Today the only channel is export: the claim as a FHIR Bundle (type collection) with the patient's identity (identifiers, name, gender, birth date, address), the coverages, the clinic and the insurers, every reference from one to another pointed at its entry, for the clinic's billing software to send to the insurer. Nothing leaves Ovok.

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 or 404 CLAIM_NOT_FOUND.
  • A withdrawn claim answers 409 CLAIM_CANCELLED.
  • The claim records when and through which channel it was submitted. Submitting again exports it again.

Example

curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/claims/<claimId>/submission' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

claimId*string

The claim id.

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

Response Body

What the channel made of the claim: for export, a FHIR Bundle to send.

application/json
  1. response
claimId*string
channel*string

export: a FHIR Bundle for the clinic billing software to send.

submittedAt*string
bundle*

The claim with its patient, coverages and organizations.

Example Request
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/claims/string/submission'
Example Response
{  "claimId": "string",  "channel": "string",  "submittedAt": "string",  "bundle": {    "property1": null,    "property2": null  }}

Withdraw a claim DELETE

Withdraws a claim the insurer has not adjudicated or paid, for example one built from the wrong charges or rejected by the insurer. It is cancelled, its charges turn `billable` again, and the patient's statement about a rejection is cancelled too, in the same commit. **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 with an answer of outcome `complete` or `partial`, or with a payment, answers **409** `CLAIM_ANSWERED`. A rejected claim (outcome `error`) may be withdrawn. - A claim already withdrawn answers **204** again. Another change to the patient's charges running at the same time answers **409**; send yours again. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/patient-billing/claims/<claimId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

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