Before You Start: Lookups
What you need | Endpoint | Example |
Patient insurance (bill to) |
|
|
Billing provider |
|
|
Service location |
|
|
Referring provider |
|
|
Rendering provider |
|
|
Price options |
|
|
Places of service |
|
|
Modifiers |
|
|
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 |
| ✅ | Numeric patient ID |
| ✅ |
|
| When | The patient insurance to bill |
| ✅ | Claim options (see below) |
| ✅ | One or more service lines (see below) |
|
| Link the invoice to an order |
|
|
|
|
| When |
|
| Invoice tag IDs |
|
|
|
|
|
|
|
| Defaults to on |
Options
Field | Required | Notes |
| ✅ |
|
| ✅ |
|
| ✅ |
|
| ✅ |
|
| ✅ |
|
| ✅ |
|
|
| Claim-level ICD-10 codes, e.g. |
|
| Provider IDs |
|
|
|
|
|
|
|
| The payer's original claim number, for corrections and replacements |
|
| Late-filing reason, e.g. |
|
| Free text |
|
| Dates for each signature |
Service lines
Field | Required | Notes |
| ✅ | e.g. |
| ✅ | Decimal |
| ✅ | Date of service range, |
| ✅ | Place of service code, e.g. |
|
| Product ID |
|
| Amounts. Leave out with |
|
| From |
|
|
|
|
| Pointers to diagnosis codes: |
|
| Decimal |
|
| Line-level prior auths |
|
| Drug details: |
|
| Start a rental program from this line (see Rentals via API) |
|
| 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 |
|
|
|
|
| Invoice status |
| Bill-to type |
| Hold reasons |
|
|
|
|
| Invoices from a rental program |
| Days since billing |
| Date ranges |
|
|
|
|
| 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:
BillTousesInvoiceInsuranceId(the insurance on the invoice) instead ofPatientInsuranceId.Include each existing service line's
Idto update it. Lines without anIdare added.Statusis required.PriorAuthorizationsuseInvoiceInsuranceId.
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 |
| ✅ | From |
| ✅ | Decimal |
| ✅ |
|
|
| 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.
See Webhooks API.
Common Errors
Code | Meaning |
| Invalid request, e.g. a missing required option or service line field, or a payer rules validation failure |
| Token missing, expired, or invalid |
| You don't have permission to access this resource |
| Invoice, patient, or referenced record not found |
| Too many requests |
