Create and list bills

POST /api/v1/bills creates one ad-hoc invoice in OnboardMe. It does not push the invoice to Xero, and it does not create a proposal billing. Proposal invoices and recurring schedules belong on Proposals. The client must be an Active client. A lead returns an error. Convert the lead first.

Create

Write access is required. Amounts are tax-exclusive. Each line is amount plus either taxAmount or taxPercent.

{
  "entityKey": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "billDate": "2026-04-15",
  "dueDate": "2026-04-30",
  "billDetails": "April bookkeeping",
  "refNo": "INV-1042",
  "billNow": 0,
  "syncNow": false,
  "sendBill": false,
  "lineItems": [
    {
      "amount": 450.00,
      "taxPercent": 10,
      "narration": "Monthly bookkeeping"
    }
  ]
}

billNow is 0 (neither), 1 (upfront), or 2 (on completion). It defaults to 0 when omitted. syncNow and sendBill are stored for later ledger sync and email. This call does not push the invoice to Xero and does not send it unless sendBill is true. sendBill defaults to true when you omit it. Set it false when you only want the invoice stored. If syncNow is true, billNow is stored as 0. A 201 returns the bill detail, the same shape as GET /api/v1/bills/{billingId}. Store billingID. GET /api/v1/bills/{billingId}/pdf returns the PDF. When Xero is connected, GET /api/v1/bills/ledger/status returns xeroConnected: true. Every line then also needs:

extAccountID or extItemID (a Xero account or inventory item)
extTaxID, or a taxPercent that matches a selected Xero tax rate within 0.02 percentage points

A line missing those is rejected. Resolve the ids from the ledger catalog, not from a name you type in:

GET /api/v1/bills/ledger/accounts for extAccountID (code, name)
GET /api/v1/bills/ledger/tax-rates for extTaxID and the matching taxPercent
GET /api/v1/bills/ledger/branding-themes for brandingThemeID on the bill header

The API does not pick a default account.

List by date, not by watermark

Bills do not support lastUpdated. startDate and endDate are required and inclusive on the bill date:

curl -sS "https://anzapi.onboardme.app/api/v1/bills/list?startDate=2026-04-01&endDate=2026-04-30&pageNumber=1" \
  -H "X-OM-Auth-ID: YOUR_CLIENT_ID" \
  -H "X-OM-Auth-Key: YOUR_CLIENT_SECRET"

Optional filters: searchFilter, invoiceStatus (Paid, Unpaid, Partially Paid, Overpaid, Cancelled), and billNowFilter (0, 1, or 2). Page until a short page and upsert on billingID. A bill edited later still has its original billDate, so re-read the window you care about, or GET /api/v1/bills/{billingId}. List rows include billNumber, billTotal, invoiceStatus, clientName, and Xero fields externalID, externalNumber, externalURL once a later sync has run. syncFailedReason is set when that sync failed.

Recurring bills

This guide’s create call is one invoice. Schedules that run on a cadence are recurring billing:

GET /api/v1/recurring-billing/list lists schedules.
GET /api/v1/recurring-billing/{recurringBillingId} is one schedule.
GET /api/v1/recurring-billing/{recurringBillingId}/runs is the history of invoices that schedule produced.

Creating a schedule as part of a proposal is recurringBillings on POST /api/v1/proposals, not POST /api/v1/bills.

Failures

Status	Meaning
400	Lead instead of an Active client, a line missing tax, `billNow` outside 0–2, or a Xero-connected practice missing account or tax on a line.
403	Read-only credential.
404	Unknown `entityKey` or `billingId`.
429	Rate limit. Honour `Retry-After`.

Bills reference

Create, list, get, and the recurring billing routes.

Core Concepts

Guides

Create and list bills

Create

List by date, not by watermark

Recurring bills

Failures

Bills reference

​Create

​List by date, not by watermark

​Recurring bills

​Failures

Bills reference

Create

List by date, not by watermark

Recurring bills

Failures