Patient billing

Record the insurer's answer

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

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

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

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

claimId*string

The claim id.

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

Request Body

application/json
  1. body
identifier?

The insurer's reference for its answer.

Defaultnull
outcome*string

error when the insurer rejected the claim.

Value in"complete""partial""error"
disposition?string

The insurer's message.

Length1 <= length <= 200
Defaultnull
receivedAt?string

When the answer came; now when left out.

Formatdate-time
Defaultnull
items?array<>
Itemsitems <= 49
Default[]
payment?

What the insurer says it pays for the claim.

Defaultnull

Response Body

The claim with the answer recorded over the one before. The patient's statement follows it.

application/json
  1. response
id*string
version*string

Send it as If-Match: W/"<version>" to change only this version.

patientId*string
clinicId*string
identifier*
status*string

active, or cancelled once withdrawn.

type*string
createdAt*string
insurer*
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<>
Example Request
curl -X PUT 'https://api.sandbox.ovok.com/v1/patient-billing/claims/string/response' \  -H 'Content-Type: application/json' \  -d '{  "outcome": "complete"}'
Example Response
{  "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' ```