Submit a claim
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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_claimscreateand let you read the patient, else 403PATIENT_BILLING_NOT_ALLOWEDor 404CLAIM_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'bearerAuthorizationBearer <JWT>claimId*stringThe claim id.
^[A-Za-z0-9\-.]{1,64}$What the channel made of the claim: for export, a FHIR Bundle to send.
application/json- response
claimId*stringchannel*stringexport: a FHIR Bundle for the clinic billing software to send.
submittedAt*stringbundle*The claim with its patient, coverages and organizations.
curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/claims/string/submission'{ "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" } } }' ```