Patient billing

Build a claim from charges

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

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

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

Authorization

bearer
headerAuthorizationBearer <JWT>

Path Parameters

patientId*string

The patient id.

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

Request Body

application/json
  1. body
identifier?

Your id for the claim: the same identifier again is the same claim.

Defaultnull
clinicId*string

The clinic whose charges are billed.

Match^[A-Za-z0-9\-.]{1,64}$
chargeIds?array<>

The billable charges to bill; every billable charge at the clinic when left out, 49 at most.

Items1 <= items <= 49
Defaultnull
type?string

R4 claim type: outpatient or inpatient services.

Default"professional"
Value in"professional""institutional"

Response Body

A claim with this identifier was built before; this is 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 POST 'https://api.sandbox.ovok.com/v1/patient-billing/patients/string/claims' \  -H 'Content-Type: application/json' \  -d '{  "clinicId": "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"      }    }  ]}

List a patient's claims GET

Lists the patient's claims, latest first, a page at a time. **Scope:** the caller's project, with `PATIENT_BILLING_ENABLED` on. ## Behaviour - Your access policy must grant `patient_billing_claims` `read` and let you read the patient, else **403** `PATIENT_BILLING_NOT_ALLOWED` or **404** `PATIENT_BILLING_PATIENT_NOT_FOUND`. - Items leave out the insurer's answer and payments; read a claim for them. - `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>/claims' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Get a claim GET

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 ```bash curl 'https://api.sandbox.ovok.com/v1/patient-billing/claims/<claimId>' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```