API reference
Every route api.billingmart.com answers, read from the OpenAPI document the server publishes: 333 operations in 14 sections. A connection given every scope an assistant may hold is offered 323 tools: the API operations under their tool names, plus search and fetch.
Before the first call
Four things every route shares
Read these once. Each section below assumes them.
Base URL
https://api.billingmart.com/v1. The version is in the path. Our build checks every contract against a recorded baseline for a removed or renamed field.
Authentication
Authorization: Bearer with an API key (bmk_live_… or bmk_test_…). An OAuth access token works only against the MCP service.
Envelope
Success is { data, meta }. Failure is { error: { code, message, fields? }, meta }.
Money
Integer minor units with the currency beside them. The server computes every total.
14 sections
Browse by what you are building
Each section is one page: the routes in it, their parameters and bodies, what they return, and the objects they return.
Workspace and access
31 routesThe workspace a credential acts in, its plan, how it pays for it, usage and AI credits, the connection an assistant holds, the people, keys and apps with access, and resetting a sandbox to its demo data.
- GET
/v1/business - POST
/v1/business/item-presets - GET
/v1/business/item-presets - POST
/v1/business/item-presets/{key}/archive - POST
/v1/business/item-presets/{key}/restore
and 26 more
Clients
7 routesThe people and companies you bill. Contact details come back masked unless the credential holds contacts:read.
- GET
/v1/clients - POST
/v1/clients - GET
/v1/clients/find - GET
/v1/clients/{clientId} - PATCH
/v1/clients/{clientId}
and 2 more
Invoices
53 routesDrafts, lines, deposits, progress billing and reminders. Every write here produces or edits a draft; sending is an action, approved by a person or the owner’s capped rule.
- GET
/v1/invoices - POST
/v1/invoices - GET
/v1/invoices/{invoiceId} - PATCH
/v1/invoices/{invoiceId} - POST
/v1/jobs/{jobId}/invoices
and 48 more
Estimates
6 routesQuotes before the work, converted into an invoice once the client accepts.
- GET
/v1/estimates - POST
/v1/estimates - GET
/v1/estimates/{estimateId} - PATCH
/v1/estimates/{estimateId} - POST
/v1/estimates/{estimateId}/convert
and 1 more
Payments
18 routesWhat was paid, how, and what is still owed. Recording and refunding are API-key scopes or approved actions, never a connected assistant on its own.
- GET
/v1/payments - GET
/v1/payments/{paymentId} - GET
/v1/payment-links - GET
/v1/payment-links/{linkId} - GET
/v1/payment-links/{linkId}/summary
and 13 more
Recurring and automation
7 routesSchedules that raise invoices on their own, the reminder cadence, and what the scheduled jobs will do next.
- GET
/v1/recurring - GET
/v1/recurring/{recurringId} - PATCH
/v1/recurring/{recurringId} - POST
/v1/recurring/{recurringId}/pause - GET
/v1/automation/upcoming
and 2 more
Work logged during the month, billed onto an invoice exactly once, and paper read from a photo or PDF into a draft a person files. A CSV of clients, items or open invoices can be dry-run here; a person runs the import in the console.
- GET
/v1/time-entries - POST
/v1/time-entries - GET
/v1/expenses - POST
/v1/expenses - GET
/v1/mileage
and 20 more
Bills and vendors
19 routesThe other side of the ledger: vendors, the bills they send, and what has been paid against them.
- GET
/v1/recurring-bills - POST
/v1/recurring-bills - GET
/v1/recurring-bills/{recurringBillId} - POST
/v1/recurring-bills/{recurringBillId}/pause - GET
/v1/bills
and 14 more
Reports and exports
20 routesAgeing, income, tax, settlement and reconciliation, computed from stored amounts, plus the accounting export.
- GET
/v1/reports/ar-ageing - GET
/v1/reports/ap-ageing - GET
/v1/reports/income - GET
/v1/reports/tax-categories - GET
/v1/tax-categories
and 15 more
Templates and pay themes
11 routesHow an invoice and its pay page look. Drafts only; publishing is an approved action.
- GET
/v1/templates - POST
/v1/templates - GET
/v1/templates/{templateId} - PATCH
/v1/templates/{templateId} - GET
/v1/templates/{templateId}/preview
and 6 more
Messages and activity
8 routesThe delivery log of every email and text, the audit trail of who did what, and your own notifications and their settings.
and 3 more
Actions and approvals
109 routesAnything that sends, moves money or changes the workspace is proposed here and waits for a signed-in person, or for the owner’s capped rule.
- GET
/v1/actions - POST
/v1/actions - GET
/v1/actions/{actionId} - POST
/v1/actions/sendInvoice - POST
/v1/actions/sendEstimate
and 104 more
Webhooks
9 routesEndpoints BillingMart signs and posts events to, and the log of every attempt.
- GET
/v1/admin/webhook-endpoints - GET
/v1/admin/webhook-deliveries - GET
/v1/webhooks - POST
/v1/webhooks - PATCH
/v1/webhooks/{endpointId}
and 4 more
Work setup and job types
10 routesHow a business sets up its work records: its terminology, the record types it can use, the industry packs it can adopt and the setup questions a pack asks. A record type is saved here as a draft; publishing it is an approved action.
- GET
/v1/work-config - GET
/v1/industry-packs - GET
/v1/business-types/{key}/setup-questions - GET
/v1/job-types - POST
/v1/job-types
and 5 more
41 scopes that routes name
Scopes
A credential holds a set of scopes. Each route needs the scope on its entry, and a few also need a second one, which their summary says. A write scope also reads what it writes.
| Scope | Routes that need it |
|---|---|
actions:admin | 37 |
actions:deliver | 14 |
actions:money | 22 |
actions:propose | 3 |
actions:read | 3 |
actions:records | 31 |
activity:read | 2 |
admin:read | 12 |
bills:approve | 2 |
bills:read | 8 |
bills:write | 11 |
business:read | 19 |
clients:read | 4 |
clients:write | 6 |
estimates:read | 2 |
estimates:write | 4 |
expenses:read | 1 |
expenses:write | 3 |
invoices:read | 6 |
invoices:write | 21 |
jobs:read | 21 |
jobs:write | 19 |
messages:read | 3 |
mileage:read | 1 |
mileage:write | 2 |
organizer:read | 2 |
organizer:write | 4 |
payments:notes | 1 |
payments:read | 12 |
payments:record | 1 |
payments:refund | 1 |
recurring:read | 2 |
recurring:write | 3 |
reports:read | 17 |
sandbox:reset | 1 |
templates:read | 5 |
templates:write | 7 |
time:read | 3 |
time:write | 7 |
webhooks:manage | 7 |
workConfig:write | 3 |
How a request is handled
Rate limits, idempotency, environments, errors and the envelope, in the order the server applies them.
Get a test key
Every workspace has a sandbox. A bmk_test_ key works only there, so nothing you try reaches a real customer.