Patient billing

Get a claim

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

Reads one claim, with the insurer's answer and the payments made on it.

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 claim whose patient you cannot read answers 404 CLAIM_NOT_FOUND.
  • submission says when and through which channel it was last submitted; response is the insurer's answer, null until recorded; payments are the insurers' payments allocated to it.

Example

curl 'https://api.sandbox.ovok.com/v1/patient-billing/claims/<claimId>' \  -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

The claim, with the insurer's answer and the payments on 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 GET 'https://api.sandbox.ovok.com/v1/patient-billing/claims/string'
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"      }    }  ]}

Build a claim from charges POST

Builds a claim to an insurer from the patient's billable charges at one clinic, as a FHIR `Claim`. Its insurer is that of the patient's first insurance coverage in force for the services; `insurance` lists every such coverage in order, the first as focal. The charges turn `billed` in the same commit. **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** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - `clinicId` must be a clinic the patient is enrolled with, else **422** `BILLING_CLINIC_INVALID`. The clinic is the claim's provider. - Only statutory and private coverages count, and only those whose `period` covers a day of the services. Without one, **422** `COVERAGE_NOT_INSURED`. - `chargeIds` and the charge rules are those of issuing an invoice: 49 at most, one currency, **409** `CHARGE_NOT_BILLABLE` or `NO_BILLABLE_CHARGES`. - Building a claim sends nothing. Submit it (`POST /v1/patient-billing/claims/<claimId>/submission`) to get it to the insurer. - `identifier` is optional. With it, the same identifier for the same patient again answers the claim already built, with **200**. A new claim answers **201** with `Location: /v1/patient-billing/claims/<id>`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/<patientId>/claims' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "clinicId": "<clinicId>", "chargeIds": null, "type": "professional" }' ```

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