API reference
Otosheets API
v1.0.0
Programmatic access to an Otosheets organisation: clients, invoices, quotes, jobs, leads, receipts, trips, bookings, time entries and the price book, plus signed webhooks for every change.
Every request is scoped to the organisation the key was created in. Responses are JSON. Lists return newest first.
Base URL
https://api.otosheets.com/v1
Get a key
Otosheets app, Settings, API access. Owners and admins on Starter or Pro can create keys.
First request
curl "https://api.otosheets.com/v1/clients?limit=5" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"{
"data": [ { "clientId": "01J…", "name": "Acme Plumbing", "outstanding": 1240.5, … } ],
"nextToken": "eyJ…"
}Authentication
Send the key as a bearer token on every request. Keys start with osk_live_ in production and osk_test_ elsewhere. A key is shown once when it is created and cannot be retrieved again. Revoking a key takes effect immediately, and removing the member who created it revokes their keys.
Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeys are accepted on /v1 endpoints only. A key presented to any other path is refused with 403.
Scopes
Each key carries a set of scopes chosen when it is created. An endpoint lists the scope it needs. A key without that scope receives 403 with requiredScope in the body. Write scopes are additionally bounded by what the key's creator may do in the app.
| Scope | Grants |
|---|---|
| read:clients | List and read clients |
| write:clients | Create, update, archive and delete clients |
| read:invoices | List and read invoices, quotes and their payments |
| write:invoices | Create, revise, void, delete and send invoices; record payments |
| read:jobs | List and read jobs |
| write:jobs | Create, update and delete jobs |
| read:leads | List and read leads |
| write:leads | Create, update and delete leads |
| read:receipts | List and read expense receipts |
| read:trips | List trips |
| write:trips | Log and delete trips |
| read:bookings | List and read bookings |
| write:bookings | Create, update and delete bookings |
| read:time-entries | List time entries |
| write:time-entries | Log, update and delete time entries |
| read:price-book | List price book items |
| write:price-book | Create, update and delete price book items |
Pagination
List endpoints accept limit (1 to 100, default 20) and return nextToken. Pass the token back unchanged to fetch the next page. The last page returns null. Tokens are opaque and expire when the underlying data changes shape; if one is rejected, start again from the first page.
GET /v1/invoices?limit=50
GET /v1/invoices?limit=50&nextToken=eyJ…Errors
Non-2xx responses carry a message written for a person and an error code written for a program.
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | A field is missing or malformed. The message names it. |
| 401 | unauthorized | The key is missing, invalid, revoked, or its creator is no longer a member. |
| 403 | forbidden | The key lacks the required scope, or the action is not permitted for its creator's role. |
| 404 | not_found | No such record or endpoint. |
| 404 | public_api_disabled | The API is switched off in this environment. |
| 409 | conflict | The record already exists, for example a client with the same email. |
| 429 | rate_limited | The organisation exceeded its budget. Wait for Retry-After seconds. |
{
"message": "This API key does not have the read:invoices scope. Create a key with that scope in Settings → API access.",
"error": "forbidden",
"requiredScope": "read:invoices"
}Rate limits
Per organisation. Calls counts every request; writes counts POST, PUT and DELETE requests. Budgets depend on the organisation's plan. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the tightest relevant budget.
| Plan | Calls per minute | Writes per minute | Writes per hour |
|---|---|---|---|
| free | 40 | 6 | 60 |
| starter | 120 | 20 | 300 |
| pro | 300 | 60 | 1200 |
Idempotency
POST requests accept an Idempotency-Key header with any unique string up to 255 characters. A repeat of the same key within 24 hours returns the original response with Idempotent-Replayed: true and creates nothing. Use it on every write that a retry could duplicate.
Idempotency-Key: order-8812-leadClients
List clients
Clients in the organisation, newest first, with outstanding and overdue balances on each row.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| search | query | string | Match on name, email or phone. |
| status | query | active | archived | all | Which clients to include. Defaults to active. |
| dateFrom | query | date | Inclusive lower bound, YYYY-MM-DD. |
| dateTo | query | date | Inclusive upper bound, YYYY-MM-DD. |
Response
An object with data, an array of Client, and nextToken.
Example
curl "https://api.otosheets.com/v1/clients" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Create a client
Creates an individual or company client. Individuals must have a unique email within the organisation. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| isCompany | boolean | Company (true) or individual (false) | |||||||||||||||||||||
| name | string | Company name. Individuals derive name from first and last name. | |||||||||||||||||||||
| firstName | string | First name (individuals) | |||||||||||||||||||||
| lastName | string | Last name (individuals) | |||||||||||||||||||||
| string | Email address. Must be unique among individuals in the organisation. | ||||||||||||||||||||||
| phone | string | Phone number | |||||||||||||||||||||
| abn | string | Australian Business Number | |||||||||||||||||||||
| address | object | A postal address.
| |||||||||||||||||||||
| contacts | object[] | Contacts (companies only) |
Response
An object with data, one Client.
Example
curl -X POST "https://api.otosheets.com/v1/clients" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"name":"<name>","firstName":"<firstName>","lastName":"<lastName>","email":"jane@example.com","phone":"0400 000 000"}'Update a client
Updates the fields sent. Fields omitted are left as they are.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| isCompany | boolean | Company (true) or individual (false) | |||||||||||||||||||||
| name | string | Company name. Individuals derive name from first and last name. | |||||||||||||||||||||
| firstName | string | First name (individuals) | |||||||||||||||||||||
| lastName | string | Last name (individuals) | |||||||||||||||||||||
| string | Email address. Must be unique among individuals in the organisation. | ||||||||||||||||||||||
| phone | string | Phone number | |||||||||||||||||||||
| abn | string | Australian Business Number | |||||||||||||||||||||
| address | object | A postal address.
| |||||||||||||||||||||
| contacts | object[] | Contacts (companies only) |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/clients/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","firstName":"<firstName>","lastName":"<lastName>","email":"jane@example.com","phone":"0400 000 000"}'Delete a client
Deletes a client that has no invoices. A client with invoices cannot be deleted; archive it instead.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/clients/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Archive a client
Hides the client from pickers. History is kept. Archived clients still appear in lists with status=archived or status=all.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Response
An object with data, one UpdateResult.
Example
curl -X POST "https://api.otosheets.com/v1/clients/<id>/archive" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{}'Unarchive a client
Restores an archived client.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Response
An object with data, one UpdateResult.
Example
curl -X POST "https://api.otosheets.com/v1/clients/<id>/unarchive" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{}'Invoices
List invoices
Invoices in the organisation, newest first. Quotes are excluded; see List quotes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| status | query | DRAFT | SENT | PAID | VOID | Filter by lifecycle status. |
| clientId | query | string | Only invoices for this client. |
| search | query | string | Match on invoice number or client name. |
| dateFrom | query | date | Inclusive lower bound, YYYY-MM-DD. |
| dateTo | query | date | Inclusive upper bound, YYYY-MM-DD. |
| dueDateFrom | query | date | Inclusive lower bound on due date, YYYY-MM-DD. |
| dueDateTo | query | date | Inclusive upper bound on due date, YYYY-MM-DD. |
Response
An object with data, an array of Invoice, and nextToken.
Example
curl "https://api.otosheets.com/v1/invoices" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Create an invoice
Creates a draft invoice for a client with one or more line items. Totals and GST are calculated by Otosheets from the lines and the GST mode. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| clientIdrequired | string | Client to invoice |
| itemsrequired | object[] | Line items, at least one |
| date | date | Issue date. Defaults to today. |
| dueDate | date | Due date. Defaults to 30 days from today. |
| gstMode | EXCLUSIVE | INCLUSIVE | NONE | How GST is applied to line prices. Defaults to EXCLUSIVE. |
| invoiceNumber | string | Your own invoice number. Generated when omitted. |
| notes | string | Notes shown on the invoice |
Response
An object with data, one Invoice.
Example
curl -X POST "https://api.otosheets.com/v1/invoices" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"clientId":"<clientId>","items":[]}'Get an invoice
One invoice by id.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one Invoice.
Example
curl "https://api.otosheets.com/v1/invoices/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Revise or void an invoice
Sending only { "status": "VOID" } voids the invoice. Sending other fields revises it: the original is voided and a new invoice is created with the changes, returned in data with its new invoiceId. Paid invoices cannot be revised.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description |
|---|---|---|
| status | VOID | Send VOID alone to void the invoice. |
| items | object[] | Replacement line items |
| clientId | string | Move the invoice to another client |
| dueDate | date | New due date |
| notes | string | New notes |
| gstMode | EXCLUSIVE | INCLUSIVE | NONE | New GST mode |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/invoices/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{}'Delete an invoice
Deletes an invoice. Prefer voiding for anything that was sent.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/invoices/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Send an invoice
Emails the invoice PDF to the client using the organisation's branding and marks it SENT. Delivery is queued; the response confirms the request was accepted.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Response
An object with data, one UpdateResult.
Example
curl -X POST "https://api.otosheets.com/v1/invoices/<id>/send" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{}'List payments on an invoice
Every payment recorded against the invoice. Not paginated.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, an array of Payment, and nextToken.
Example
curl "https://api.otosheets.com/v1/invoices/<id>/payments" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Record a payment
Records a payment received outside Otosheets (bank transfer, cash). The invoice becomes PAID once payments cover the total. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| amountrequired | number | Amount received, in dollars |
| methodrequired | string | How it was paid, e.g. BANK_TRANSFER, CARD, CASH, CHEQUE |
| date | date | Payment date. Defaults to today. |
| note | string | Free-text note |
Response
An object with data, one Payment.
Example
curl -X POST "https://api.otosheets.com/v1/invoices/<id>/payments" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"amount":0,"method":"<method>"}'Quotes
List quotes
Quotes in the organisation, newest first. A quote has the invoice shape with isQuote true.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| status | query | DRAFT | SENT | CONVERTED | VOID | Filter by status. |
| clientId | query | string | Only quotes for this client. |
| search | query | string | Match on quote number or client name. |
| dueDateFrom | query | date | Inclusive lower bound on expiry date, YYYY-MM-DD. |
| dueDateTo | query | date | Inclusive upper bound on expiry date, YYYY-MM-DD. |
Response
An object with data, an array of Invoice, and nextToken.
Example
curl "https://api.otosheets.com/v1/quotes" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Get a quote
One quote by id.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one Invoice.
Example
curl "https://api.otosheets.com/v1/quotes/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Jobs
List jobs
Jobs in the organisation, newest first.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| status | query | SCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLED | Filter by lifecycle status. |
| clientId | query | string | Only jobs for this client. |
| memberId | query | string | Only jobs assigned to this member. |
| search | query | string | Match on title or address. |
| dateFrom | query | date | Inclusive lower bound, YYYY-MM-DD. |
| dateTo | query | date | Inclusive upper bound, YYYY-MM-DD. |
Response
An object with data, an array of Job, and nextToken.
Example
curl "https://api.otosheets.com/v1/jobs" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Create a job
Creates a job. The address is geocoded and a geofence is set up when geofencing is enabled for the organisation. Assigned members are notified. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| titlerequired | string | Title |
| description | string | Description |
| clientId | string | Client the job is for |
| address | string | Site address. Geocoded on save. |
| scheduledDate | date | Scheduled date |
| scheduledTime | string | Scheduled start time, HH:MM |
| estimatedDuration | number | Estimated duration, in minutes |
| assignedMembers | string[] | Members assigned to the job |
| assignedTeams | string[] | Teams assigned to the job |
| jobType | string | Job type |
| scope | string | Scope of work |
| leadId | string | Lead the job came from |
| materials | object[] | Materials |
Response
An object with data, one Job.
Example
curl -X POST "https://api.otosheets.com/v1/jobs" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"title":"<title>"}'Get a job
One job by id.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one Job.
Example
curl "https://api.otosheets.com/v1/jobs/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Update a job
Updates the fields sent. Status changes must follow the lifecycle: SCHEDULED to DISPATCHED or CANCELLED, DISPATCHED to IN_PROGRESS or CANCELLED, IN_PROGRESS to COMPLETE or CANCELLED, COMPLETE to INVOICED.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description |
|---|---|---|
| title | string | Title |
| description | string | Description |
| clientId | string | Client the job is for |
| address | string | Site address. Geocoded on save. |
| scheduledDate | date | Scheduled date |
| scheduledTime | string | Scheduled start time, HH:MM |
| estimatedDuration | number | Estimated duration, in minutes |
| assignedMembers | string[] | Members assigned to the job |
| assignedTeams | string[] | Teams assigned to the job |
| jobType | string | Job type |
| scope | string | Scope of work |
| leadId | string | Lead the job came from |
| status | SCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLED | New status. Must be a permitted transition from the current status. |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/jobs/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{}'Delete a job
Deletes a job.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/jobs/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Leads
List leads
Leads in the organisation, newest first.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| stage | query | string | Filter by stage. |
| source | query | string | Filter by source. |
| pipelineId | query | string | Only leads in this pipeline. |
| search | query | string | Match on name, phone, email or description. |
Response
An object with data, an array of Lead, and nextToken.
Example
curl "https://api.otosheets.com/v1/leads" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Create a lead
Adds an enquiry to the pipeline. Notifications and workflows fire exactly as for a lead captured on the website. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| clientNamerequired | string | Name of the person enquiring |
| clientPhone | string | Phone number |
| clientEmail | string | Email address |
| suburb | string | Suburb |
| serviceType | string | Requested service |
| description | string | What they asked for |
| urgency | string | Urgency |
| pipelineId | string | Pipeline to place the lead in. Defaults to the pipeline that owns the source. |
| notes | string | Internal notes |
| source | string | Provenance label, e.g. zapier, website, referral. Defaults to manual. |
Response
An object with data, one LeadCreated.
Example
curl -X POST "https://api.otosheets.com/v1/leads" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"clientName":"<clientName>","clientPhone":"0400 000 000","clientEmail":"jane@example.com","suburb":"<suburb>","serviceType":"<serviceType>"}'Get a lead
One lead by id.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one Lead.
Example
curl "https://api.otosheets.com/v1/leads/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Update a lead
Moves the lead to a stage, assigns it, records a quoted amount, or updates notes.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description |
|---|---|---|
| stage | string | Stage to move the lead to |
| assignedTo | string | Member id to assign the lead to |
| quotedAmount | number | Quoted value, in dollars |
| notes | string | Internal notes |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/leads/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{}'Delete a lead
Deletes a lead.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/leads/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Receipts
List receipts
Expense receipts, newest first.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| search | query | string | Match on merchant or description. |
| category | query | string | Filter by expense category. |
| dateFrom | query | date | Inclusive lower bound, YYYY-MM-DD. |
| dateTo | query | date | Inclusive upper bound, YYYY-MM-DD. |
Response
An object with data, an array of Receipt, and nextToken.
Example
curl "https://api.otosheets.com/v1/receipts" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Get a receipt
One receipt by id.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one Receipt.
Example
curl "https://api.otosheets.com/v1/receipts/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Trips
List trips
Logged trips, newest first.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| search | query | string | Match on addresses or notes. |
| purpose | query | string | Filter by purpose. |
| dateFrom | query | date | Inclusive lower bound, YYYY-MM-DD. |
| dateTo | query | date | Inclusive upper bound, YYYY-MM-DD. |
Response
An object with data, an array of Trip, and nextToken.
Example
curl "https://api.otosheets.com/v1/trips" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Log a trip
Logs a vehicle trip. The date is taken from startTime when given. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| distanceKmrequired | number | Distance, in kilometres |
| startTime | datetime | Departure. The trip date is taken from this; defaults to now. |
| endTime | datetime | Arrival |
| startAddress | string | Start address |
| endAddress | string | End address |
| purpose | string | Purpose, e.g. BUSINESS, PERSONAL. Defaults to UNVERIFIED. |
| notes | string | Notes |
| jobId | string | Job the trip was for |
Response
An object with data, one Trip.
Example
curl -X POST "https://api.otosheets.com/v1/trips" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"distanceKm":0}'Delete a trip
Deletes a trip.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/trips/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Bookings
List bookings
Bookings in a date window. Defaults to today through the next 30 days. Not paginated.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| from | query | date | Inclusive start date, YYYY-MM-DD. Defaults to today. |
| to | query | date | Inclusive end date, YYYY-MM-DD. Defaults to 30 days from today. |
Response
An object with data, an array of Booking, and nextToken.
Example
curl "https://api.otosheets.com/v1/bookings" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Create a booking
Books an appointment. The address is geocoded when given. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| daterequired | date | Booking date |
| startTimerequired | string | Start time, HH:MM |
| endTime | string | End time, HH:MM |
| clientNamerequired | string | Customer name |
| clientPhone | string | Customer phone |
| clientEmail | string | Customer email |
| serviceType | string | Requested service |
| suburb | string | Suburb |
| address | string | Site address. Geocoded on save. |
| notes | string | Notes |
| leadId | string | Lead this booking is for |
| pipelineId | string | Pipeline for a lead created from this booking |
| source | string | Provenance label. Defaults to api. |
Response
An object with data, one Booking.
Example
curl -X POST "https://api.otosheets.com/v1/bookings" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"date":"<date>","startTime":"<startTime>","clientName":"<clientName>","clientPhone":"0400 000 000","clientEmail":"jane@example.com","serviceType":"<serviceType>","suburb":"<suburb>"}'Get a booking
One booking by id.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one Booking.
Example
curl "https://api.otosheets.com/v1/bookings/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Update a booking
Updates the fields sent. Setting status to CANCELLED cancels the booking and fires the cancellation flow.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description |
|---|---|---|
| date | date | Booking date |
| startTime | string | Start time, HH:MM |
| endTime | string | End time, HH:MM |
| clientName | string | Customer name |
| clientPhone | string | Customer phone |
| clientEmail | string | Customer email |
| serviceType | string | Requested service |
| suburb | string | Suburb |
| address | string | Site address. Geocoded on save. |
| notes | string | Notes |
| status | CONFIRMED | CANCELLED | Set CANCELLED to cancel |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/bookings/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"clientPhone":"0400 000 000","clientEmail":"jane@example.com","serviceType":"<serviceType>","suburb":"<suburb>"}'Delete a booking
Deletes a booking.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/bookings/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Time entries
List time entries
Logged time, newest first.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| clientId | query | string | Only entries for this client. |
| from | query | date | Inclusive start date, YYYY-MM-DD. |
| to | query | date | Inclusive end date, YYYY-MM-DD. |
| uninvoiced | query | boolean | Only entries not yet on an invoice. |
Response
An object with data, an array of TimeEntry, and nextToken.
Example
curl "https://api.otosheets.com/v1/time-entries" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Log a time entry
Logs a block of time, optionally against a client or job. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| date | date | Date. Defaults to today. |
| durationMinutesrequired | number | Duration, in minutes |
| descriptionrequired | string | What was done |
| clientId | string | Client the time is for |
| jobId | string | Job the time is for |
| startTime | string | Start time |
| endTime | string | End time |
| project | string | Project label |
| billable | boolean | Whether the time is billable. Defaults to true. |
Response
An object with data, one TimeEntryCreated.
Example
curl -X POST "https://api.otosheets.com/v1/time-entries" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"durationMinutes":0,"description":"<description>"}'Update a time entry
Updates the fields sent.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description |
|---|---|---|
| date | date | Date. Defaults to today. |
| durationMinutes | number | Duration, in minutes |
| description | string | What was done |
| clientId | string | Client the time is for |
| jobId | string | Job the time is for |
| startTime | string | Start time |
| endTime | string | End time |
| project | string | Project label |
| billable | boolean | Whether the time is billable. Defaults to true. |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/time-entries/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{}'Delete a time entry
Deletes a time entry.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/time-entries/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Price book
List price book items
Reusable products and services.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| limit | query | integer | Page size, 1 to 100. Defaults to 20. |
| nextToken | query | string | Cursor from the previous page. Omit for the first page. |
| search | query | string | Match on name or description. |
| kind | query | product | service | Filter by kind. |
Response
An object with data, an array of PriceBookItem, and nextToken.
Example
curl "https://api.otosheets.com/v1/price-book" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Create a price book item
Adds a reusable product or service. Send an Idempotency-Key header to make retries safe.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header | string | Any unique string up to 255 characters. A repeat of the same key within 24 hours replays the original response instead of creating a second record. |
Request body
| Field | Type | Description |
|---|---|---|
| namerequired | string | Name |
| description | string | Description. Defaults to the name. |
| unitPricerequired | number | Unit price, in dollars, before GST |
| unit | string | Unit of measure, e.g. hour, each, m2 |
| costPrice | number | Cost price, in dollars |
| qtyOnHand | number | Stock on hand, for tracked products |
| reorderPoint | number | Reorder point, for tracked products |
| supplierId | string | Supplier id |
Response
An object with data, one PriceBookItem.
Example
curl -X POST "https://api.otosheets.com/v1/price-book" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <unique-string>" \
-d '{"name":"<name>","unitPrice":0}'Update a price book item
Updates the fields sent. Changing unitPrice does not change invoices already raised.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Request body
| Field | Type | Description |
|---|---|---|
| name | string | Name |
| description | string | Description. Defaults to the name. |
| unitPrice | number | Unit price, in dollars, before GST |
| unit | string | Unit of measure, e.g. hour, each, m2 |
| costPrice | number | Cost price, in dollars |
| qtyOnHand | number | Stock on hand, for tracked products |
| reorderPoint | number | Reorder point, for tracked products |
| supplierId | string | Supplier id |
Response
An object with data, one UpdateResult.
Example
curl -X PUT "https://api.otosheets.com/v1/price-book/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Delete a price book item
Deletes a price book item. Invoice lines drawn from it are unaffected.
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| idrequired | path | string | The record id. |
Response
An object with data, one DeleteResult.
Example
curl -X DELETE "https://api.otosheets.com/v1/price-book/<id>" \
-H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Webhooks
Subscriptions are created in Settings → API access. Each carries a signing secret shown once. Each delivery is one HTTPS POST with the event below as the body. Respond with any 2xx within 10 seconds. Non-2xx responses and timeouts are retried up to 5 times over roughly 15 minutes. After 20 consecutive failures the subscription is disabled and must be re-enabled from Settings.
Delivery body
{
"id": "01J9…",
"type": "invoice.paid",
"createdAt": "2026-09-03T02:15:00.000Z",
"orgId": "org_…",
"subject": {
"type": "invoice",
"id": "inv_…"
},
"data": {
"invoiceId": "inv_…",
"totalAmount": 1240.5
}
}Headers
| Header | Value |
|---|---|
| X-Otosheets-Event | The topic, e.g. invoice.paid |
| X-Otosheets-Delivery | The event id. Repeated on retries; use it to deduplicate. |
| X-Otosheets-Timestamp | Unix seconds when the delivery was signed. |
| X-Otosheets-Signature | t=<unix seconds>,v1=<hex digest> |
Verifying the signature
Compute HMAC-SHA256 over ${X-Otosheets-Timestamp}.${raw request body} with the subscription's signing secret, hex encode it, and compare it to the v1 value with a constant-time comparison. Reject deliveries whose timestamp is more than 5 minutes old.
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verify(secret, headers, rawBody) {
const sig = Object.fromEntries(headers['x-otosheets-signature'].split(',').map(p => p.split('=')))
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false
const expected = createHmac('sha256', secret).update(`${sig.t}.${rawBody}`).digest('hex')
return expected.length === sig.v1.length && timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig.v1, 'hex'))
}Topics
Subscribe to any set of topics, or to * for every topic including ones added later.
| Topic | Sent when |
|---|---|
| client.created | A client was created |
| client.updated | A client was updated |
| client.deleted | A client was deleted |
| invoice.created | An invoice or quote was created |
| invoice.updated | An invoice was updated |
| invoice.sent | An invoice was emailed to the client |
| invoice.paid | An invoice was paid in full |
| invoice.payment_recorded | A payment was recorded against an invoice |
| invoice.overdue | An invoice passed its due date unpaid |
| invoice.voided | An invoice was voided |
| invoice.deleted | An invoice was deleted |
| payment.received | An online payment was received |
| job.created | A job was created |
| job.updated | A job was updated |
| job.status_changed | A job changed status |
| job.dispatched | A job was dispatched to a member |
| job.completed | A job was completed |
| job.cancelled | A job was cancelled |
| job.deleted | A job was deleted |
| lead.created | A lead was created |
| lead.updated | A lead was updated |
| lead.stage_changed | A lead moved to another stage |
| lead.assigned | A lead was assigned to a member |
| lead.deleted | A lead was deleted |
| booking.created | A booking was made |
| booking.updated | A booking was changed |
| booking.cancelled | A booking was cancelled |
| booking.deleted | A booking was deleted |
| receipt.processed | A receipt finished processing |
| receipt.deleted | A receipt was deleted |
| trip.created | A trip was logged |
| trip.deleted | A trip was deleted |
| time.entry_logged | A time entry was logged |
| order.paid | A shop order was paid |
| order.refunded | A shop order was refunded |
Use with Claude
Otosheets is also a connector for Claude Desktop, claude.ai and Claude Code. A connector session signs in with your Otosheets login and acts as you, with your permissions, over the same rate budget as API keys. No API key is involved, and an owner or admin can turn the connector off for the whole organisation under Settings, API access.
Claude Desktop and claude.ai
- Open Settings, then Connectors, then Add custom connector.
- Name it Otosheets and paste the MCP server URL shown in Settings, API access.
- Choose Connect and sign in with your Otosheets login.
Claude Code
Run once, then sign in when the browser opens. The token refreshes on its own afterwards.
claude mcp add --transport http otosheets <MCP server URL from Settings, API access>| Lane | Credential | Acts as | Scope | Best for |
|---|---|---|---|---|
| Claude connector | Your Otosheets login (OAuth) | You | Everything your role allows | Working in Claude by hand |
| API key | osk_… | The member who created it | Only the scopes chosen | Scripts, Zapier, n8n, servers |
| Webhooks | whsec_… | Otosheets calling you | The topics chosen | Reacting to changes |
Objects
Fields listed here are stable within v1. Objects may carry additional fields not listed; treat unknown fields as optional.
Error
Every non-2xx response carries this body.
| Field | Type | Description |
|---|---|---|
| messagerequired | string | Human-readable explanation of what went wrong and, where possible, how to fix it. |
| error | bad_request | unauthorized | forbidden | not_found | conflict | rate_limited | public_api_disabled | internal | Stable machine-readable code. |
UpdateResult
Returned after an update. Carries the record id, `updated: true`, and any fields the record reports back (for revisions of an invoice, the new invoiceId).
| Field | Type | Description |
|---|---|---|
| idrequired | string | The record id from the request path |
| updatedrequired | boolean | Always true |
DeleteResult
Returned after a delete.
| Field | Type | Description |
|---|---|---|
| idrequired | string | The record id from the request path |
| deletedrequired | boolean | Always true |
Client
A customer of the business.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| clientIdrequired | string | Client id | |||||||||||||||||||||
| namerequired | string | Display name. For individuals this is derived from first and last name. | |||||||||||||||||||||
| isCompany | boolean | True for a company, false for an individual | |||||||||||||||||||||
| firstName | string | First name (individuals) | |||||||||||||||||||||
| lastName | string | Last name (individuals) | |||||||||||||||||||||
| string | Email address (individuals) | ||||||||||||||||||||||
| phone | string | Phone number | |||||||||||||||||||||
| abn | string | Australian Business Number | |||||||||||||||||||||
| address | object | A postal address.
| |||||||||||||||||||||
| contacts | object[] | Contacts (companies) | |||||||||||||||||||||
| archived | boolean | Archived clients are hidden from pickers but keep their history | |||||||||||||||||||||
| outstanding | number | Total unpaid invoice value, in dollars | |||||||||||||||||||||
| overdue | number | Total overdue invoice value, in dollars | |||||||||||||||||||||
| invoiceCount | number | Number of invoices raised for this client | |||||||||||||||||||||
| lifetimeValue | number | Total invoiced value, in dollars | |||||||||||||||||||||
| createdAtrequired | datetime | Created | |||||||||||||||||||||
| updatedAt | datetime | Last updated |
ClientCreate
Fields accepted when creating a client. A company needs name; an individual needs firstName.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| isCompany | boolean | Company (true) or individual (false) | |||||||||||||||||||||
| name | string | Company name. Individuals derive name from first and last name. | |||||||||||||||||||||
| firstName | string | First name (individuals) | |||||||||||||||||||||
| lastName | string | Last name (individuals) | |||||||||||||||||||||
| string | Email address. Must be unique among individuals in the organisation. | ||||||||||||||||||||||
| phone | string | Phone number | |||||||||||||||||||||
| abn | string | Australian Business Number | |||||||||||||||||||||
| address | object | A postal address.
| |||||||||||||||||||||
| contacts | object[] | Contacts (companies only) |
ClientUpdate
Fields accepted when updating a client. Only fields sent are changed.
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| isCompany | boolean | Company (true) or individual (false) | |||||||||||||||||||||
| name | string | Company name. Individuals derive name from first and last name. | |||||||||||||||||||||
| firstName | string | First name (individuals) | |||||||||||||||||||||
| lastName | string | Last name (individuals) | |||||||||||||||||||||
| string | Email address. Must be unique among individuals in the organisation. | ||||||||||||||||||||||
| phone | string | Phone number | |||||||||||||||||||||
| abn | string | Australian Business Number | |||||||||||||||||||||
| address | object | A postal address.
| |||||||||||||||||||||
| contacts | object[] | Contacts (companies only) |
LineItem
One line on an invoice or quote.
| Field | Type | Description |
|---|---|---|
| id | string | Line id |
| description | string | Description |
| quantity | number | Quantity |
| unitPrice | number | Unit price, in dollars, before GST |
| total | number | Line total, in dollars |
| priceBookItemId | string | Price book item this line was drawn from, if any |
Invoice
An invoice or quote.
| Field | Type | Description |
|---|---|---|
| invoiceIdrequired | string | Invoice id |
| invoiceNumberrequired | string | Human-facing invoice number |
| clientId | string | Client the invoice is addressed to |
| isQuote | boolean | True when this document is a quote rather than an invoice |
| statusrequired | DRAFT | SENT | PAID | VOID | CONVERTED | Lifecycle status. Quotes also use CONVERTED once turned into an invoice. |
| daterequired | date | Issue date |
| dueDaterequired | date | Due date (expiry date for quotes) |
| items | LineItem[] | |
| gstMode | EXCLUSIVE | INCLUSIVE | NONE | How GST is applied to line prices |
| subtotal | number | Total before GST, in dollars |
| gstAmount | number | GST, in dollars |
| totalAmountrequired | number | Total including GST, in dollars |
| paidAmount | number | Amount received so far, in dollars |
| notes | string | Notes shown on the document |
| paymentUrl | string | Hosted payment page, when a payment link has been generated |
| lastReminderAt | datetime | When a payment reminder was last sent for this invoice. Absent if none has been sent. |
| createdAt | datetime | Created |
| updatedAt | datetime | Last updated |
InvoiceCreate
Fields accepted when creating an invoice.
| Field | Type | Description |
|---|---|---|
| clientIdrequired | string | Client to invoice |
| itemsrequired | object[] | Line items, at least one |
| date | date | Issue date. Defaults to today. |
| dueDate | date | Due date. Defaults to 30 days from today. |
| gstMode | EXCLUSIVE | INCLUSIVE | NONE | How GST is applied to line prices. Defaults to EXCLUSIVE. |
| invoiceNumber | string | Your own invoice number. Generated when omitted. |
| notes | string | Notes shown on the invoice |
InvoiceUpdate
Fields accepted when revising or voiding an invoice.
| Field | Type | Description |
|---|---|---|
| status | VOID | Send VOID alone to void the invoice. |
| items | object[] | Replacement line items |
| clientId | string | Move the invoice to another client |
| dueDate | date | New due date |
| notes | string | New notes |
| gstMode | EXCLUSIVE | INCLUSIVE | NONE | New GST mode |
Payment
A payment recorded against an invoice.
| Field | Type | Description |
|---|---|---|
| paymentIdrequired | string | Payment id |
| invoiceIdrequired | string | Invoice the payment applies to |
| amountrequired | number | Amount, in dollars |
| method | string | How it was paid, e.g. BANK_TRANSFER, CARD, CASH |
| daterequired | date | Payment date |
| note | string | Free-text note |
| createdAt | datetime | Recorded |
PaymentCreate
Fields accepted when recording a payment.
| Field | Type | Description |
|---|---|---|
| amountrequired | number | Amount received, in dollars |
| methodrequired | string | How it was paid, e.g. BANK_TRANSFER, CARD, CASH, CHEQUE |
| date | date | Payment date. Defaults to today. |
| note | string | Free-text note |
Job
A scheduled piece of work.
| Field | Type | Description |
|---|---|---|
| idrequired | string | Job id |
| jobId | string | Job id (same value as id) |
| titlerequired | string | Title |
| description | string | Description |
| statusrequired | SCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLED | Lifecycle status |
| clientId | string | Client the job is for |
| address | string | Site address |
| scheduledDate | date | Scheduled date |
| scheduledTime | string | Scheduled start time, HH:MM |
| estimatedDuration | number | Estimated duration, in minutes |
| assignedMembers | string[] | Members assigned to the job |
| materials | JobMaterial[] | |
| leadId | string | Lead the job was created from, if any |
| startedAt | datetime | When work started |
| completedAt | datetime | When work was completed |
| createdAtrequired | datetime | Created |
| updatedAt | datetime | Last updated |
JobMaterial
A material used on a job.
| Field | Type | Description |
|---|---|---|
| id | string | Material id |
| name | string | Name |
| quantity | number | Quantity |
| unitCost | number | Unit cost, in dollars |
JobCreate
Fields accepted when creating a job.
| Field | Type | Description |
|---|---|---|
| titlerequired | string | Title |
| description | string | Description |
| clientId | string | Client the job is for |
| address | string | Site address. Geocoded on save. |
| scheduledDate | date | Scheduled date |
| scheduledTime | string | Scheduled start time, HH:MM |
| estimatedDuration | number | Estimated duration, in minutes |
| assignedMembers | string[] | Members assigned to the job |
| assignedTeams | string[] | Teams assigned to the job |
| jobType | string | Job type |
| scope | string | Scope of work |
| leadId | string | Lead the job came from |
| materials | object[] | Materials |
JobUpdate
Fields accepted when updating a job. Only fields sent are changed.
| Field | Type | Description |
|---|---|---|
| title | string | Title |
| description | string | Description |
| clientId | string | Client the job is for |
| address | string | Site address. Geocoded on save. |
| scheduledDate | date | Scheduled date |
| scheduledTime | string | Scheduled start time, HH:MM |
| estimatedDuration | number | Estimated duration, in minutes |
| assignedMembers | string[] | Members assigned to the job |
| assignedTeams | string[] | Teams assigned to the job |
| jobType | string | Job type |
| scope | string | Scope of work |
| leadId | string | Lead the job came from |
| status | SCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLED | New status. Must be a permitted transition from the current status. |
Lead
An enquiry in the pipeline.
| Field | Type | Description |
|---|---|---|
| leadIdrequired | string | Lead id |
| clientNamerequired | string | Name of the person enquiring |
| clientPhone | string | Phone number |
| clientEmail | string | Email address |
| sourcerequired | string | Where the lead came from, e.g. website, manual, facebook |
| pipelineId | string | Pipeline the lead sits in |
| stagerequired | string | Current stage |
| serviceType | string | Requested service |
| suburb | string | Suburb |
| description | string | What they asked for |
| urgency | string | Urgency as stated by the enquirer |
| quotedAmount | number | Quoted value, in dollars |
| assignedTo | string | Member id the lead is assigned to |
| notes | string | Internal notes |
| createdAtrequired | datetime | Created |
| updatedAt | datetime | Last updated |
LeadCreate
Fields accepted when creating a lead.
| Field | Type | Description |
|---|---|---|
| clientNamerequired | string | Name of the person enquiring |
| clientPhone | string | Phone number |
| clientEmail | string | Email address |
| suburb | string | Suburb |
| serviceType | string | Requested service |
| description | string | What they asked for |
| urgency | string | Urgency |
| pipelineId | string | Pipeline to place the lead in. Defaults to the pipeline that owns the source. |
| notes | string | Internal notes |
| source | string | Provenance label, e.g. zapier, website, referral. Defaults to manual. |
LeadCreated
Returned after a lead is created.
| Field | Type | Description |
|---|---|---|
| leadIdrequired | string | The new lead id |
| pipelineId | string | Pipeline the lead was placed in |
LeadUpdate
Fields accepted when updating a lead. Send at least one.
| Field | Type | Description |
|---|---|---|
| stage | string | Stage to move the lead to |
| assignedTo | string | Member id to assign the lead to |
| quotedAmount | number | Quoted value, in dollars |
| notes | string | Internal notes |
Receipt
An expense receipt.
| Field | Type | Description |
|---|---|---|
| idrequired | string | Receipt id |
| daterequired | date | Receipt date |
| merchantrequired | string | Merchant name |
| amountrequired | number | Total, in dollars |
| taxAmount | number | GST, in dollars |
| aiCategory | string | Expense category |
| isDeductible | boolean | Whether the expense was assessed as deductible |
| description | string | Description |
| statusrequired | string | Processing status |
Trip
A logged vehicle trip.
| Field | Type | Description |
|---|---|---|
| tripIdrequired | string | Trip id |
| daterequired | date | Trip date |
| startTime | datetime | Departure |
| endTime | datetime | Arrival |
| startAddress | string | Start address |
| endAddress | string | End address |
| distanceKmrequired | number | Distance, in kilometres |
| purpose | string | Purpose, e.g. BUSINESS, PERSONAL, UNVERIFIED |
| notes | string | Notes |
| jobId | string | Job the trip was for, if any |
| createdAt | datetime | Created |
TripCreate
Fields accepted when logging a trip.
| Field | Type | Description |
|---|---|---|
| distanceKmrequired | number | Distance, in kilometres |
| startTime | datetime | Departure. The trip date is taken from this; defaults to now. |
| endTime | datetime | Arrival |
| startAddress | string | Start address |
| endAddress | string | End address |
| purpose | string | Purpose, e.g. BUSINESS, PERSONAL. Defaults to UNVERIFIED. |
| notes | string | Notes |
| jobId | string | Job the trip was for |
Booking
A booked appointment.
| Field | Type | Description |
|---|---|---|
| bookingIdrequired | string | Booking id |
| daterequired | date | Booking date |
| startTimerequired | string | Start time, HH:MM |
| endTimerequired | string | End time, HH:MM |
| clientNamerequired | string | Customer name |
| clientPhone | string | Customer phone |
| clientEmail | string | Customer email |
| serviceType | string | Requested service |
| address | string | Site address |
| statusrequired | CONFIRMED | CANCELLED | Status |
| source | string | Where the booking came from |
| leadId | string | Lead the booking belongs to, if any |
| createdAt | datetime | Created |
| updatedAt | datetime | Last updated |
BookingCreate
Fields accepted when creating a booking.
| Field | Type | Description |
|---|---|---|
| daterequired | date | Booking date |
| startTimerequired | string | Start time, HH:MM |
| endTime | string | End time, HH:MM |
| clientNamerequired | string | Customer name |
| clientPhone | string | Customer phone |
| clientEmail | string | Customer email |
| serviceType | string | Requested service |
| suburb | string | Suburb |
| address | string | Site address. Geocoded on save. |
| notes | string | Notes |
| leadId | string | Lead this booking is for |
| pipelineId | string | Pipeline for a lead created from this booking |
| source | string | Provenance label. Defaults to api. |
BookingUpdate
Fields accepted when updating a booking. Only fields sent are changed.
| Field | Type | Description |
|---|---|---|
| date | date | Booking date |
| startTime | string | Start time, HH:MM |
| endTime | string | End time, HH:MM |
| clientName | string | Customer name |
| clientPhone | string | Customer phone |
| clientEmail | string | Customer email |
| serviceType | string | Requested service |
| suburb | string | Suburb |
| address | string | Site address. Geocoded on save. |
| notes | string | Notes |
| status | CONFIRMED | CANCELLED | Set CANCELLED to cancel |
TimeEntry
A logged block of time.
| Field | Type | Description |
|---|---|---|
| timeEntryIdrequired | string | Time entry id |
| daterequired | date | Date |
| startTime | string | Start time |
| endTime | string | End time |
| durationMinutesrequired | number | Duration, in minutes |
| descriptionrequired | string | What was done |
| clientId | string | Client the time is for |
| jobId | string | Job the time is for |
| billable | boolean | Whether the time is billable |
| invoiceId | string | Invoice the time was billed on, once invoiced |
| createdAt | datetime | Created |
TimeEntryCreate
Fields accepted when logging time.
| Field | Type | Description |
|---|---|---|
| date | date | Date. Defaults to today. |
| durationMinutesrequired | number | Duration, in minutes |
| descriptionrequired | string | What was done |
| clientId | string | Client the time is for |
| jobId | string | Job the time is for |
| startTime | string | Start time |
| endTime | string | End time |
| project | string | Project label |
| billable | boolean | Whether the time is billable. Defaults to true. |
TimeEntryCreated
Returned after a time entry is logged.
| Field | Type | Description |
|---|---|---|
| timeEntryIdrequired | string | The new time entry id |
TimeEntryUpdate
Fields accepted when updating a time entry. Only fields sent are changed.
| Field | Type | Description |
|---|---|---|
| date | date | Date. Defaults to today. |
| durationMinutes | number | Duration, in minutes |
| description | string | What was done |
| clientId | string | Client the time is for |
| jobId | string | Job the time is for |
| startTime | string | Start time |
| endTime | string | End time |
| project | string | Project label |
| billable | boolean | Whether the time is billable. Defaults to true. |
PriceBookItem
A reusable product or service line.
| Field | Type | Description |
|---|---|---|
| itemIdrequired | string | Item id |
| namerequired | string | Name |
| description | string | Description |
| unitPricerequired | number | Unit price, in dollars, before GST |
| unit | string | Unit of measure, e.g. hour, each, m2 |
| costPrice | number | Cost price, in dollars |
| qtyOnHand | number | Stock on hand, for tracked products |
| reorderPoint | number | Reorder point, for tracked products |
| supplierId | string | Supplier id |
| createdAt | datetime | Created |
| updatedAt | datetime | Last updated |
PriceBookItemCreate
Fields accepted when creating a price book item.
| Field | Type | Description |
|---|---|---|
| namerequired | string | Name |
| description | string | Description. Defaults to the name. |
| unitPricerequired | number | Unit price, in dollars, before GST |
| unit | string | Unit of measure, e.g. hour, each, m2 |
| costPrice | number | Cost price, in dollars |
| qtyOnHand | number | Stock on hand, for tracked products |
| reorderPoint | number | Reorder point, for tracked products |
| supplierId | string | Supplier id |
PriceBookItemUpdate
Fields accepted when updating a price book item. Only fields sent are changed.
| Field | Type | Description |
|---|---|---|
| name | string | Name |
| description | string | Description. Defaults to the name. |
| unitPrice | number | Unit price, in dollars, before GST |
| unit | string | Unit of measure, e.g. hour, each, m2 |
| costPrice | number | Cost price, in dollars |
| qtyOnHand | number | Stock on hand, for tracked products |
| reorderPoint | number | Reorder point, for tracked products |
| supplierId | string | Supplier id |
WebhookEvent
The body of every webhook delivery.
| Field | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| idrequired | string | Event id. Unique per event; the same id is re-sent on retries, so use it to deduplicate. | |||||||||
| typerequired | string | Topic, e.g. invoice.paid | |||||||||
| createdAtrequired | datetime | When the event happened | |||||||||
| orgIdrequired | string | Organisation the event belongs to | |||||||||
| subject | object | The record the event is about.
| |||||||||
| datarequired | object | Topic-specific payload. Always carries the subject id (invoiceId, jobId, leadId, …) and usually the fields that changed. |