Record the insurer's answer
- Sandbox: available
- On your own host? Choose https://{host} in the playground.
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_claimsupdateand let you read the patient, else 403PATIENT_BILLING_NOT_ALLOWEDor 404CLAIM_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. outcomeiscomplete,partial, orerrorfor a rejected claim. Each item names the claim item it adjudicates byitemSequence, with amounts per category (submitted,eligible,benefit,copay,deductible); totals are summed per category.- An unknown
itemSequenceor an amount in another currency than the claim's answers 422CLAIM_RESPONSE_INVALID. A withdrawn claim answers 409CLAIM_CANCELLED.
Example
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" } } }'bearerAuthorizationBearer <JWT>claimId*stringThe claim id.
^[A-Za-z0-9\-.]{1,64}$application/json- body
identifier?The insurer's reference for its answer.
nulloutcome*stringerror when the insurer rejected the claim.
"complete""partial""error"disposition?stringThe insurer's message.
1 <= length <= 200nullreceivedAt?stringWhen the answer came; now when left out.
date-timenullitems?array<>items <= 49[]payment?What the insurer says it pays for the claim.
nullThe claim with the answer recorded over the one before. The patient's statement follows it.
application/json- response
id*stringversion*stringSend it as If-Match: W/"<version>" to change only this version.
patientId*stringclinicId*stringidentifier*status*stringactive, or cancelled once withdrawn.
type*stringcreatedAt*stringinsurer*coverageIds*array<string>The patient's coverages the claim names, focal first.
items*array<>total*submission*When and how it was last submitted; null before.
response*The insurer's answer; null until recorded.
payments*array<>curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-billing/claims/string/response' \ -H 'Content-Type: application/json' \ -d '{ "outcome": "complete"}'{ "id": "string", "version": "string", "patientId": "string", "clinicId": "string", "identifier": { "system": "string", "value": "string" }, "status": "string", "type": "string", "createdAt": "string", "insurer": { "id": "string", "ik": "string", "name": "string" }, "coverageIds": [ "string" ], "items": [ { "sequence": 0, "chargeId": "string", "code": { "system": "string", "code": "string", "display": "string" }, "servicedOn": "string", "quantity": 0, "unitPrice": { "value": 0, "currency": "string" }, "net": { "value": 0, "currency": "string" } } ], "total": { "value": 0, "currency": "string" }, "submission": { "channel": "string", "submittedAt": "string" }, "response": { "id": "string", "identifier": { "system": "string", "value": "string" }, "outcome": "string", "disposition": "string", "receivedAt": "string", "items": [ { "itemSequence": 0, "adjudication": [ { "category": "string", "amount": { "value": 0, "currency": "string" } } ] } ], "total": [ { "category": "string", "amount": { "value": 0, "currency": "string" } } ], "payment": { "paidOn": "string", "amount": { "value": 0, "currency": "string" } } }, "payments": [ { "paymentId": "string", "paidOn": "string", "amount": { "value": 0, "currency": "string" } } ]}Submit a claim POST
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 ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/claims/<claimId>/submission' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```
List a patient's benefit statements GET
Lists what the patient's insurers decided on their claims, latest first: FHIR `ExplanationOfBenefit` statements, each with the services claimed, what was paid per category and the payment. **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, the same as the patient's invoices, so patients read their own statements. Else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - A statement exists once the insurer's answer to a claim is recorded, and follows it when it changes. - `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 ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/benefit-statements' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```