Skip to main content

Invoices via API

Create, view, update, and adjust invoices (claims), change their status, and reorder their insurances.

Before You Start: Lookups

What you need

Endpoint

Example

Patient insurance (bill to)

GET /v1/patients/{patientId}/insurances

PIf5b1af006f4bdafa8b540aca26806e0d

Billing provider

GET /v1/billing-providers

BP28538d00acea414bbc940e0fda497f92

Service location

GET /v1/organization/locations

OL3b309d00aceae09bd4544bef2658410e

Referring provider

GET /v1/referring-providers

RP01d8eb00863baa596d54c7ab32b5a2d8

Rendering provider

GET /v1/rendering-providers

Price options

GET /v1/price-options

PO73ae8d0060ca90fa4e04893c801275a3

Places of service

GET /v1/place-of-service

12 (Home)

Modifiers

GET /v1/modifiers

NU, RR, KX

Invoice tags

GET /v1/invoice-tags


Create an Invoice

POST /v1/invoices

💡 Payer rules validation is on by default. The invoice is checked against your payer rules when it's created. Set EnablePayerRulesValidation to false to skip it.

Top-level fields

Field

Required

Notes

PatientId

✅

Numeric patient ID

BillTo.Type

✅

Payer or Patient

BillTo.PatientInsuranceId

When Type is Payer

The patient insurance to bill

Options

✅

Claim options (see below)

ServiceLines

✅

One or more service lines (see below)

OrderId

Link the invoice to an order

Status

New, Open, Hold, Submitted, Rejected, Denied, Void, or Closed

HoldReasons

When Status is Hold, e.g. AuthorizationRequired, DocumentationRequired, PrescriptionRequired

Tags

Invoice tag IDs

CustomFields

[{ "FieldId": "...", "Value": "..." }]

AutoPopulatePriceOptions

true to fill in price options and missing amounts from your pricing setup

EnablePayerRulesValidation

Defaults to on

Options

Field

Required

Notes

BillingProviderId

✅

ServiceLocationId

✅

PatientSignatureOnFile

✅

Yes or No

InsuredSignatureOnFile

✅

Yes or No

ProviderSignatureOnFile

✅

Yes or No

ProviderAcceptAssignment

✅

Yes or No

Diagnosis

Claim-level ICD-10 codes, e.g. ["G47.33"]

ReferringProviderId / RenderingProviderId

Provider IDs

PriorAuthorizations

[{ "PatientInsuranceId": "...", "PriorAuthNumber": "..." }]

ResubmissionCode

Original, Corrected, Replacement, or Cancel

OriginalRefNumber

The payer's original claim number, for corrections and replacements

DelayReason

Late-filing reason, e.g. AuthorizationDelays

ClaimCodes / AdditionalInfo

Free text

*SignatureOnFileDate

Dates for each signature

Service lines

Field

Required

Notes

Hcpcs

✅

e.g. E0601

Quantity

✅

Decimal

ServicePeriod.From / .To

✅

Date of service range, YYYY-MM-DD

PlaceOfService

✅

Place of service code, e.g. 12

ItemId

Product ID

Charge / Allowed

Amounts. Leave out with AutoPopulatePriceOptions to use your pricing.

PriceOptionId

From GET /v1/price-options

Modifiers

Level1 to Level4, e.g. { "Level1": "RR", "Level2": "KX" }

Diagnosis

Pointers to diagnosis codes: First (required if used), Second, Third, Fourth

TaxRate

Decimal

PriorAuthorizations

Line-level prior auths

Drug

Drug details: Qualifier (e.g. Ndc), Number, Name, Units, Measure

EnableRental / RentSettings

Start a rental program from this line (see Rentals via API)

Notes

Free text

PriorAuthNumber (on options and service lines) and Drug.Ndc are deprecated. Use PriorAuthorizations and Drug.Qualifier + Drug.Number instead.

Example

POST /v1/invoices
{
"PatientId": "10000105",
"OrderId": "SO05adce00ef4b092b90f42f97b2ec3e36",
"BillTo": {
"Type": "Payer",
"PatientInsuranceId": "PIf5b1af006f4bdafa8b540aca26806e0d"
},
"Options": {
"BillingProviderId": "BP28538d00acea414bbc940e0fda497f92",
"ServiceLocationId": "OL3b309d00aceae09bd4544bef2658410e",
"ReferringProviderId": "RP01d8eb00863baa596d54c7ab32b5a2d8",
"PatientSignatureOnFile": "Yes",
"InsuredSignatureOnFile": "Yes",
"ProviderSignatureOnFile": "Yes",
"ProviderAcceptAssignment": "Yes",
"Diagnosis": ["G47.33"]
},
"ServiceLines": [
{
"Hcpcs": "E0601",
"ItemId": "A05MW34SX96ZF71QT28K",
"Quantity": 1,
"ServicePeriod": { "From": "2026-11-10", "To": "2026-11-10" },
"PlaceOfService": "12",
"Modifiers": { "Level1": "RR", "Level2": "KX" },
"Diagnosis": { "First": "G47.33" }
}
],
"AutoPopulatePriceOptions": true
}

Response: 201 Created

{ "Id": "IN9fa1d300ff4b39ab984449c5267b72f1" }

Search Invoices

GET /v1/invoices

Filter

Notes

patientId / patientName

orderId

status / statuses

Invoice status

payerTypes

Bill-to type

claimHoldReasons

Hold reasons

hcpcsCodes

purchase / rental

true / false

rentProgramId

Invoices from a rental program

agingFrom / agingTo

Days since billing

createdOnRange.from / .to, modifiedOnRange.from / .to

Date ranges

tags, uniqueIds

customField.fieldId + customField.value

pageIndex / pageSize

Paging

V2 also offers GET /v2/invoices for invoice search.

[
{
"Id": "IN9fa1d300ff4b39ab984449c5267b72f1",
"DisplayId": "IN-267B72F1",
"Status": { "Id": "New", "Name": "New" },
"Patient": { "Id": "10000397", "Name": { "FirstName": "Jane", "LastName": "Doe" } },
"OrderId": "SO8f60db00ae4b1de8e434804dc45e20ba",
"BillRecipient": "Example Payer",
"InsurancePriorityOrder": { "Id": "Primary", "Name": "Primary" },
"ServiceHcpcs": ["E1399"],
"Charge": { "Amount": 135, "Currency": "$" },
"Balance": { "Amount": 135, "Currency": "$" },
"Rental": true,
"Purchase": false,
"HoldReasons": []
}
]

Get one invoice: GET /v1/invoices/{id}

Get an invoice's transactions (charges, payments, adjustments): GET /v1/invoices/{id}/transactions


Change Status, Hold Reasons, or Tags

PUT /v1/invoices/{id}/state

⚠️ Send all three fields. Anything you leave out is removed. For example, to change only Status, send the existing Tags too.

{
"Status": "Hold",
"HoldReasons": ["DocumentationRequired"],
"Tags": ["TA8bddf9711e54433b8ea761964a48d3ea"]
}

Response: 200 OK


Update an Invoice

PUT /v1/invoices/{id}

⚠️ Send the entire invoice. Fields you leave out are removed.

Uses the same fields as creating an invoice, with these differences:

  • BillTo uses InvoiceInsuranceId (the insurance on the invoice) instead of PatientInsuranceId.

  • Include each existing service line's Id to update it. Lines without an Id are added.

  • Status is required.

  • PriorAuthorizations use InvoiceInsuranceId.

Response: 200 OK


Post a Provider Adjustment

POST /v1/invoices/{id}/adjust

Posts an adjustment to the invoice, which is applied to its service lines automatically.

Field

Required

Notes

ReasonId

✅

From GET /v1/invoices/provider-adjustments

Amount

✅

Decimal

Date

✅

YYYY-MM-DD

Note

Free text

{
"ReasonId": "string",
"Amount": 25.00,
"Date": "2026-11-10",
"Note": "Small balance write-off"
}

Response: 200 OK


Reorder an Invoice's Insurances

POST /v1/invoices/{invoiceId}/insurances/reorder

List the invoice insurance IDs in priority order. The first becomes primary, the second secondary, and so on.

{
"InvoiceInsuranceIds": [
"II46bd2b00c5eaaaebaf04f17dee14f7e5",
"II9a3f7c01d4e8b26f5a0c9e3d71b4f8a2"
]
}

These are invoice insurance IDs (II…), not patient insurance IDs (PI…). Get them from GET /v1/invoices/{id}.


Delete an Invoice

DELETE /v1/invoices/{id}

The invoice is archived, not permanently deleted, and is no longer visible in the UI.


Get Notified of Changes

Subscribe to invoice.created, invoice.updated, invoice.deleted, invoice.status.updated, and invoice.tags.updated.


Common Errors

Code

Meaning

400

Invalid request, e.g. a missing required option or service line field, or a payer rules validation failure

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Invoice, patient, or referenced record not found

429

Too many requests


Related articles

Did this answer your question?