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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys 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.

ScopeGrants
read:clientsList and read clients
write:clientsCreate, update, archive and delete clients
read:invoicesList and read invoices, quotes and their payments
write:invoicesCreate, revise, void, delete and send invoices; record payments
read:jobsList and read jobs
write:jobsCreate, update and delete jobs
read:leadsList and read leads
write:leadsCreate, update and delete leads
read:receiptsList and read expense receipts
read:tripsList trips
write:tripsLog and delete trips
read:bookingsList and read bookings
write:bookingsCreate, update and delete bookings
read:time-entriesList time entries
write:time-entriesLog, update and delete time entries
read:price-bookList price book items
write:price-bookCreate, 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.

StatusCodeMeaning
400bad_requestA field is missing or malformed. The message names it.
401unauthorizedThe key is missing, invalid, revoked, or its creator is no longer a member.
403forbiddenThe key lacks the required scope, or the action is not permitted for its creator's role.
404not_foundNo such record or endpoint.
404public_api_disabledThe API is switched off in this environment.
409conflictThe record already exists, for example a client with the same email.
429rate_limitedThe 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.

PlanCalls per minuteWrites per minuteWrites per hour
free40660
starter12020300
pro300601200

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-lead

Clients

GET/v1/clientsscope: read:clients

List clients

Clients in the organisation, newest first, with outstanding and overdue balances on each row.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
searchquerystringMatch on name, email or phone.
statusqueryactive | archived | allWhich clients to include. Defaults to active.
dateFromquerydateInclusive lower bound, YYYY-MM-DD.
dateToquerydateInclusive 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"
POST/v1/clientsscope: write:clients

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

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
isCompanybooleanCompany (true) or individual (false)
namestringCompany name. Individuals derive name from first and last name.
firstNamestringFirst name (individuals)
lastNamestringLast name (individuals)
emailstringEmail address. Must be unique among individuals in the organisation.
phonestringPhone number
abnstringAustralian Business Number
addressobjectA postal address.
FieldTypeDescription
line1stringStreet address
line2stringSecond address line
suburbstringSuburb or locality
statestringState or territory
postcodestringPostcode
countrystringCountry
contactsobject[]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"}'
PUT/v1/clients/{id}scope: write:clients

Update a client

Updates the fields sent. Fields omitted are left as they are.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
isCompanybooleanCompany (true) or individual (false)
namestringCompany name. Individuals derive name from first and last name.
firstNamestringFirst name (individuals)
lastNamestringLast name (individuals)
emailstringEmail address. Must be unique among individuals in the organisation.
phonestringPhone number
abnstringAustralian Business Number
addressobjectA postal address.
FieldTypeDescription
line1stringStreet address
line2stringSecond address line
suburbstringSuburb or locality
statestringState or territory
postcodestringPostcode
countrystringCountry
contactsobject[]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/v1/clients/{id}scope: write:clients

Delete a client

Deletes a client that has no invoices. A client with invoices cannot be deleted; archive it instead.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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"
POST/v1/clients/{id}/archivescope: write:clients

Archive a client

Hides the client from pickers. History is kept. Archived clients still appear in lists with status=archived or status=all.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.
Idempotency-KeyheaderstringAny 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 '{}'
POST/v1/clients/{id}/unarchivescope: write:clients

Unarchive a client

Restores an archived client.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.
Idempotency-KeyheaderstringAny 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

GET/v1/invoicesscope: read:invoices

List invoices

Invoices in the organisation, newest first. Quotes are excluded; see List quotes.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
statusqueryDRAFT | SENT | PAID | VOIDFilter by lifecycle status.
clientIdquerystringOnly invoices for this client.
searchquerystringMatch on invoice number or client name.
dateFromquerydateInclusive lower bound, YYYY-MM-DD.
dateToquerydateInclusive upper bound, YYYY-MM-DD.
dueDateFromquerydateInclusive lower bound on due date, YYYY-MM-DD.
dueDateToquerydateInclusive 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"
POST/v1/invoicesscope: write:invoices

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

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
clientIdrequiredstringClient to invoice
itemsrequiredobject[]Line items, at least one
datedateIssue date. Defaults to today.
dueDatedateDue date. Defaults to 30 days from today.
gstModeEXCLUSIVE | INCLUSIVE | NONEHow GST is applied to line prices. Defaults to EXCLUSIVE.
invoiceNumberstringYour own invoice number. Generated when omitted.
notesstringNotes 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/v1/invoices/{id}scope: read:invoices

Get an invoice

One invoice by id.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Response

An object with data, one Invoice.

Example

curl "https://api.otosheets.com/v1/invoices/<id>" \
  -H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
PUT/v1/invoices/{id}scope: write:invoices

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

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
statusVOIDSend VOID alone to void the invoice.
itemsobject[]Replacement line items
clientIdstringMove the invoice to another client
dueDatedateNew due date
notesstringNew notes
gstModeEXCLUSIVE | INCLUSIVE | NONENew 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/v1/invoices/{id}scope: write:invoices

Delete an invoice

Deletes an invoice. Prefer voiding for anything that was sent.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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"
POST/v1/invoices/{id}/sendscope: write:invoices

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

ParameterInTypeDescription
idrequiredpathstringThe record id.
Idempotency-KeyheaderstringAny 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 '{}'
GET/v1/invoices/{id}/paymentsscope: read:invoices

List payments on an invoice

Every payment recorded against the invoice. Not paginated.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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"
POST/v1/invoices/{id}/paymentsscope: write:invoices

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

ParameterInTypeDescription
idrequiredpathstringThe record id.
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
amountrequirednumberAmount received, in dollars
methodrequiredstringHow it was paid, e.g. BANK_TRANSFER, CARD, CASH, CHEQUE
datedatePayment date. Defaults to today.
notestringFree-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

GET/v1/quotesscope: read:invoices

List quotes

Quotes in the organisation, newest first. A quote has the invoice shape with isQuote true.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
statusqueryDRAFT | SENT | CONVERTED | VOIDFilter by status.
clientIdquerystringOnly quotes for this client.
searchquerystringMatch on quote number or client name.
dueDateFromquerydateInclusive lower bound on expiry date, YYYY-MM-DD.
dueDateToquerydateInclusive 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/v1/quotes/{id}scope: read:invoices

Get a quote

One quote by id.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/jobsscope: read:jobs

List jobs

Jobs in the organisation, newest first.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
statusquerySCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLEDFilter by lifecycle status.
clientIdquerystringOnly jobs for this client.
memberIdquerystringOnly jobs assigned to this member.
searchquerystringMatch on title or address.
dateFromquerydateInclusive lower bound, YYYY-MM-DD.
dateToquerydateInclusive 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"
POST/v1/jobsscope: write:jobs

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

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
titlerequiredstringTitle
descriptionstringDescription
clientIdstringClient the job is for
addressstringSite address. Geocoded on save.
scheduledDatedateScheduled date
scheduledTimestringScheduled start time, HH:MM
estimatedDurationnumberEstimated duration, in minutes
assignedMembersstring[]Members assigned to the job
assignedTeamsstring[]Teams assigned to the job
jobTypestringJob type
scopestringScope of work
leadIdstringLead the job came from
materialsobject[]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/v1/jobs/{id}scope: read:jobs

Get a job

One job by id.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Response

An object with data, one Job.

Example

curl "https://api.otosheets.com/v1/jobs/<id>" \
  -H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
PUT/v1/jobs/{id}scope: write:jobs

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

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
titlestringTitle
descriptionstringDescription
clientIdstringClient the job is for
addressstringSite address. Geocoded on save.
scheduledDatedateScheduled date
scheduledTimestringScheduled start time, HH:MM
estimatedDurationnumberEstimated duration, in minutes
assignedMembersstring[]Members assigned to the job
assignedTeamsstring[]Teams assigned to the job
jobTypestringJob type
scopestringScope of work
leadIdstringLead the job came from
statusSCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLEDNew 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/v1/jobs/{id}scope: write:jobs

Delete a job

Deletes a job.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/leadsscope: read:leads

List leads

Leads in the organisation, newest first.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
stagequerystringFilter by stage.
sourcequerystringFilter by source.
pipelineIdquerystringOnly leads in this pipeline.
searchquerystringMatch 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"
POST/v1/leadsscope: write:leads

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

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
clientNamerequiredstringName of the person enquiring
clientPhonestringPhone number
clientEmailstringEmail address
suburbstringSuburb
serviceTypestringRequested service
descriptionstringWhat they asked for
urgencystringUrgency
pipelineIdstringPipeline to place the lead in. Defaults to the pipeline that owns the source.
notesstringInternal notes
sourcestringProvenance 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/v1/leads/{id}scope: read:leads

Get a lead

One lead by id.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Response

An object with data, one Lead.

Example

curl "https://api.otosheets.com/v1/leads/<id>" \
  -H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
PUT/v1/leads/{id}scope: write:leads

Update a lead

Moves the lead to a stage, assigns it, records a quoted amount, or updates notes.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
stagestringStage to move the lead to
assignedTostringMember id to assign the lead to
quotedAmountnumberQuoted value, in dollars
notesstringInternal 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/v1/leads/{id}scope: write:leads

Delete a lead

Deletes a lead.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/receiptsscope: read:receipts

List receipts

Expense receipts, newest first.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
searchquerystringMatch on merchant or description.
categoryquerystringFilter by expense category.
dateFromquerydateInclusive lower bound, YYYY-MM-DD.
dateToquerydateInclusive 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/v1/receipts/{id}scope: read:receipts

Get a receipt

One receipt by id.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/tripsscope: read:trips

List trips

Logged trips, newest first.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
searchquerystringMatch on addresses or notes.
purposequerystringFilter by purpose.
dateFromquerydateInclusive lower bound, YYYY-MM-DD.
dateToquerydateInclusive 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"
POST/v1/tripsscope: write:trips

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

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
distanceKmrequirednumberDistance, in kilometres
startTimedatetimeDeparture. The trip date is taken from this; defaults to now.
endTimedatetimeArrival
startAddressstringStart address
endAddressstringEnd address
purposestringPurpose, e.g. BUSINESS, PERSONAL. Defaults to UNVERIFIED.
notesstringNotes
jobIdstringJob 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/v1/trips/{id}scope: write:trips

Delete a trip

Deletes a trip.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/bookingsscope: read:bookings

List bookings

Bookings in a date window. Defaults to today through the next 30 days. Not paginated.

Parameters

ParameterInTypeDescription
fromquerydateInclusive start date, YYYY-MM-DD. Defaults to today.
toquerydateInclusive 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"
POST/v1/bookingsscope: write:bookings

Create a booking

Books an appointment. The address is geocoded when given. Send an Idempotency-Key header to make retries safe.

Parameters

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
daterequireddateBooking date
startTimerequiredstringStart time, HH:MM
endTimestringEnd time, HH:MM
clientNamerequiredstringCustomer name
clientPhonestringCustomer phone
clientEmailstringCustomer email
serviceTypestringRequested service
suburbstringSuburb
addressstringSite address. Geocoded on save.
notesstringNotes
leadIdstringLead this booking is for
pipelineIdstringPipeline for a lead created from this booking
sourcestringProvenance 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/v1/bookings/{id}scope: read:bookings

Get a booking

One booking by id.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Response

An object with data, one Booking.

Example

curl "https://api.otosheets.com/v1/bookings/<id>" \
  -H "Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
PUT/v1/bookings/{id}scope: write:bookings

Update a booking

Updates the fields sent. Setting status to CANCELLED cancels the booking and fires the cancellation flow.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
datedateBooking date
startTimestringStart time, HH:MM
endTimestringEnd time, HH:MM
clientNamestringCustomer name
clientPhonestringCustomer phone
clientEmailstringCustomer email
serviceTypestringRequested service
suburbstringSuburb
addressstringSite address. Geocoded on save.
notesstringNotes
statusCONFIRMED | CANCELLEDSet 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/v1/bookings/{id}scope: write:bookings

Delete a booking

Deletes a booking.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/time-entriesscope: read:time-entries

List time entries

Logged time, newest first.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
clientIdquerystringOnly entries for this client.
fromquerydateInclusive start date, YYYY-MM-DD.
toquerydateInclusive end date, YYYY-MM-DD.
uninvoicedquerybooleanOnly 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"
POST/v1/time-entriesscope: write:time-entries

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

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
datedateDate. Defaults to today.
durationMinutesrequirednumberDuration, in minutes
descriptionrequiredstringWhat was done
clientIdstringClient the time is for
jobIdstringJob the time is for
startTimestringStart time
endTimestringEnd time
projectstringProject label
billablebooleanWhether 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>"}'
PUT/v1/time-entries/{id}scope: write:time-entries

Update a time entry

Updates the fields sent.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
datedateDate. Defaults to today.
durationMinutesnumberDuration, in minutes
descriptionstringWhat was done
clientIdstringClient the time is for
jobIdstringJob the time is for
startTimestringStart time
endTimestringEnd time
projectstringProject label
billablebooleanWhether 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/v1/time-entries/{id}scope: write:time-entries

Delete a time entry

Deletes a time entry.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

GET/v1/price-bookscope: read:price-book

List price book items

Reusable products and services.

Parameters

ParameterInTypeDescription
limitqueryintegerPage size, 1 to 100. Defaults to 20.
nextTokenquerystringCursor from the previous page. Omit for the first page.
searchquerystringMatch on name or description.
kindqueryproduct | serviceFilter 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"
POST/v1/price-bookscope: write:price-book

Create a price book item

Adds a reusable product or service. Send an Idempotency-Key header to make retries safe.

Parameters

ParameterInTypeDescription
Idempotency-KeyheaderstringAny 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

FieldTypeDescription
namerequiredstringName
descriptionstringDescription. Defaults to the name.
unitPricerequirednumberUnit price, in dollars, before GST
unitstringUnit of measure, e.g. hour, each, m2
costPricenumberCost price, in dollars
qtyOnHandnumberStock on hand, for tracked products
reorderPointnumberReorder point, for tracked products
supplierIdstringSupplier 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}'
PUT/v1/price-book/{id}scope: write:price-book

Update a price book item

Updates the fields sent. Changing unitPrice does not change invoices already raised.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe record id.

Request body

FieldTypeDescription
namestringName
descriptionstringDescription. Defaults to the name.
unitPricenumberUnit price, in dollars, before GST
unitstringUnit of measure, e.g. hour, each, m2
costPricenumberCost price, in dollars
qtyOnHandnumberStock on hand, for tracked products
reorderPointnumberReorder point, for tracked products
supplierIdstringSupplier 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/v1/price-book/{id}scope: write:price-book

Delete a price book item

Deletes a price book item. Invoice lines drawn from it are unaffected.

Parameters

ParameterInTypeDescription
idrequiredpathstringThe 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

HeaderValue
X-Otosheets-EventThe topic, e.g. invoice.paid
X-Otosheets-DeliveryThe event id. Repeated on retries; use it to deduplicate.
X-Otosheets-TimestampUnix seconds when the delivery was signed.
X-Otosheets-Signaturet=<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.

TopicSent when
client.createdA client was created
client.updatedA client was updated
client.deletedA client was deleted
invoice.createdAn invoice or quote was created
invoice.updatedAn invoice was updated
invoice.sentAn invoice was emailed to the client
invoice.paidAn invoice was paid in full
invoice.payment_recordedA payment was recorded against an invoice
invoice.overdueAn invoice passed its due date unpaid
invoice.voidedAn invoice was voided
invoice.deletedAn invoice was deleted
payment.receivedAn online payment was received
job.createdA job was created
job.updatedA job was updated
job.status_changedA job changed status
job.dispatchedA job was dispatched to a member
job.completedA job was completed
job.cancelledA job was cancelled
job.deletedA job was deleted
lead.createdA lead was created
lead.updatedA lead was updated
lead.stage_changedA lead moved to another stage
lead.assignedA lead was assigned to a member
lead.deletedA lead was deleted
booking.createdA booking was made
booking.updatedA booking was changed
booking.cancelledA booking was cancelled
booking.deletedA booking was deleted
receipt.processedA receipt finished processing
receipt.deletedA receipt was deleted
trip.createdA trip was logged
trip.deletedA trip was deleted
time.entry_loggedA time entry was logged
order.paidA shop order was paid
order.refundedA 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

  1. Open Settings, then Connectors, then Add custom connector.
  2. Name it Otosheets and paste the MCP server URL shown in Settings, API access.
  3. 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>
LaneCredentialActs asScopeBest for
Claude connectorYour Otosheets login (OAuth)YouEverything your role allowsWorking in Claude by hand
API keyosk_…The member who created itOnly the scopes chosenScripts, Zapier, n8n, servers
Webhookswhsec_…Otosheets calling youThe topics chosenReacting 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.

FieldTypeDescription
messagerequiredstringHuman-readable explanation of what went wrong and, where possible, how to fix it.
errorbad_request | unauthorized | forbidden | not_found | conflict | rate_limited | public_api_disabled | internalStable 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).

FieldTypeDescription
idrequiredstringThe record id from the request path
updatedrequiredbooleanAlways true

DeleteResult

Returned after a delete.

FieldTypeDescription
idrequiredstringThe record id from the request path
deletedrequiredbooleanAlways true

Client

A customer of the business.

FieldTypeDescription
clientIdrequiredstringClient id
namerequiredstringDisplay name. For individuals this is derived from first and last name.
isCompanybooleanTrue for a company, false for an individual
firstNamestringFirst name (individuals)
lastNamestringLast name (individuals)
emailstringEmail address (individuals)
phonestringPhone number
abnstringAustralian Business Number
addressobjectA postal address.
FieldTypeDescription
line1stringStreet address
line2stringSecond address line
suburbstringSuburb or locality
statestringState or territory
postcodestringPostcode
countrystringCountry
contactsobject[]Contacts (companies)
archivedbooleanArchived clients are hidden from pickers but keep their history
outstandingnumberTotal unpaid invoice value, in dollars
overduenumberTotal overdue invoice value, in dollars
invoiceCountnumberNumber of invoices raised for this client
lifetimeValuenumberTotal invoiced value, in dollars
createdAtrequireddatetimeCreated
updatedAtdatetimeLast updated

ClientCreate

Fields accepted when creating a client. A company needs name; an individual needs firstName.

FieldTypeDescription
isCompanybooleanCompany (true) or individual (false)
namestringCompany name. Individuals derive name from first and last name.
firstNamestringFirst name (individuals)
lastNamestringLast name (individuals)
emailstringEmail address. Must be unique among individuals in the organisation.
phonestringPhone number
abnstringAustralian Business Number
addressobjectA postal address.
FieldTypeDescription
line1stringStreet address
line2stringSecond address line
suburbstringSuburb or locality
statestringState or territory
postcodestringPostcode
countrystringCountry
contactsobject[]Contacts (companies only)

ClientUpdate

Fields accepted when updating a client. Only fields sent are changed.

FieldTypeDescription
isCompanybooleanCompany (true) or individual (false)
namestringCompany name. Individuals derive name from first and last name.
firstNamestringFirst name (individuals)
lastNamestringLast name (individuals)
emailstringEmail address. Must be unique among individuals in the organisation.
phonestringPhone number
abnstringAustralian Business Number
addressobjectA postal address.
FieldTypeDescription
line1stringStreet address
line2stringSecond address line
suburbstringSuburb or locality
statestringState or territory
postcodestringPostcode
countrystringCountry
contactsobject[]Contacts (companies only)

LineItem

One line on an invoice or quote.

FieldTypeDescription
idstringLine id
descriptionstringDescription
quantitynumberQuantity
unitPricenumberUnit price, in dollars, before GST
totalnumberLine total, in dollars
priceBookItemIdstringPrice book item this line was drawn from, if any

Invoice

An invoice or quote.

FieldTypeDescription
invoiceIdrequiredstringInvoice id
invoiceNumberrequiredstringHuman-facing invoice number
clientIdstringClient the invoice is addressed to
isQuotebooleanTrue when this document is a quote rather than an invoice
statusrequiredDRAFT | SENT | PAID | VOID | CONVERTEDLifecycle status. Quotes also use CONVERTED once turned into an invoice.
daterequireddateIssue date
dueDaterequireddateDue date (expiry date for quotes)
itemsLineItem[]
gstModeEXCLUSIVE | INCLUSIVE | NONEHow GST is applied to line prices
subtotalnumberTotal before GST, in dollars
gstAmountnumberGST, in dollars
totalAmountrequirednumberTotal including GST, in dollars
paidAmountnumberAmount received so far, in dollars
notesstringNotes shown on the document
paymentUrlstringHosted payment page, when a payment link has been generated
lastReminderAtdatetimeWhen a payment reminder was last sent for this invoice. Absent if none has been sent.
createdAtdatetimeCreated
updatedAtdatetimeLast updated

InvoiceCreate

Fields accepted when creating an invoice.

FieldTypeDescription
clientIdrequiredstringClient to invoice
itemsrequiredobject[]Line items, at least one
datedateIssue date. Defaults to today.
dueDatedateDue date. Defaults to 30 days from today.
gstModeEXCLUSIVE | INCLUSIVE | NONEHow GST is applied to line prices. Defaults to EXCLUSIVE.
invoiceNumberstringYour own invoice number. Generated when omitted.
notesstringNotes shown on the invoice

InvoiceUpdate

Fields accepted when revising or voiding an invoice.

FieldTypeDescription
statusVOIDSend VOID alone to void the invoice.
itemsobject[]Replacement line items
clientIdstringMove the invoice to another client
dueDatedateNew due date
notesstringNew notes
gstModeEXCLUSIVE | INCLUSIVE | NONENew GST mode

Payment

A payment recorded against an invoice.

FieldTypeDescription
paymentIdrequiredstringPayment id
invoiceIdrequiredstringInvoice the payment applies to
amountrequirednumberAmount, in dollars
methodstringHow it was paid, e.g. BANK_TRANSFER, CARD, CASH
daterequireddatePayment date
notestringFree-text note
createdAtdatetimeRecorded

PaymentCreate

Fields accepted when recording a payment.

FieldTypeDescription
amountrequirednumberAmount received, in dollars
methodrequiredstringHow it was paid, e.g. BANK_TRANSFER, CARD, CASH, CHEQUE
datedatePayment date. Defaults to today.
notestringFree-text note

Job

A scheduled piece of work.

FieldTypeDescription
idrequiredstringJob id
jobIdstringJob id (same value as id)
titlerequiredstringTitle
descriptionstringDescription
statusrequiredSCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLEDLifecycle status
clientIdstringClient the job is for
addressstringSite address
scheduledDatedateScheduled date
scheduledTimestringScheduled start time, HH:MM
estimatedDurationnumberEstimated duration, in minutes
assignedMembersstring[]Members assigned to the job
materialsJobMaterial[]
leadIdstringLead the job was created from, if any
startedAtdatetimeWhen work started
completedAtdatetimeWhen work was completed
createdAtrequireddatetimeCreated
updatedAtdatetimeLast updated

JobMaterial

A material used on a job.

FieldTypeDescription
idstringMaterial id
namestringName
quantitynumberQuantity
unitCostnumberUnit cost, in dollars

JobCreate

Fields accepted when creating a job.

FieldTypeDescription
titlerequiredstringTitle
descriptionstringDescription
clientIdstringClient the job is for
addressstringSite address. Geocoded on save.
scheduledDatedateScheduled date
scheduledTimestringScheduled start time, HH:MM
estimatedDurationnumberEstimated duration, in minutes
assignedMembersstring[]Members assigned to the job
assignedTeamsstring[]Teams assigned to the job
jobTypestringJob type
scopestringScope of work
leadIdstringLead the job came from
materialsobject[]Materials

JobUpdate

Fields accepted when updating a job. Only fields sent are changed.

FieldTypeDescription
titlestringTitle
descriptionstringDescription
clientIdstringClient the job is for
addressstringSite address. Geocoded on save.
scheduledDatedateScheduled date
scheduledTimestringScheduled start time, HH:MM
estimatedDurationnumberEstimated duration, in minutes
assignedMembersstring[]Members assigned to the job
assignedTeamsstring[]Teams assigned to the job
jobTypestringJob type
scopestringScope of work
leadIdstringLead the job came from
statusSCHEDULED | DISPATCHED | IN_PROGRESS | COMPLETE | INVOICED | CANCELLEDNew status. Must be a permitted transition from the current status.

Lead

An enquiry in the pipeline.

FieldTypeDescription
leadIdrequiredstringLead id
clientNamerequiredstringName of the person enquiring
clientPhonestringPhone number
clientEmailstringEmail address
sourcerequiredstringWhere the lead came from, e.g. website, manual, facebook
pipelineIdstringPipeline the lead sits in
stagerequiredstringCurrent stage
serviceTypestringRequested service
suburbstringSuburb
descriptionstringWhat they asked for
urgencystringUrgency as stated by the enquirer
quotedAmountnumberQuoted value, in dollars
assignedTostringMember id the lead is assigned to
notesstringInternal notes
createdAtrequireddatetimeCreated
updatedAtdatetimeLast updated

LeadCreate

Fields accepted when creating a lead.

FieldTypeDescription
clientNamerequiredstringName of the person enquiring
clientPhonestringPhone number
clientEmailstringEmail address
suburbstringSuburb
serviceTypestringRequested service
descriptionstringWhat they asked for
urgencystringUrgency
pipelineIdstringPipeline to place the lead in. Defaults to the pipeline that owns the source.
notesstringInternal notes
sourcestringProvenance label, e.g. zapier, website, referral. Defaults to manual.

LeadCreated

Returned after a lead is created.

FieldTypeDescription
leadIdrequiredstringThe new lead id
pipelineIdstringPipeline the lead was placed in

LeadUpdate

Fields accepted when updating a lead. Send at least one.

FieldTypeDescription
stagestringStage to move the lead to
assignedTostringMember id to assign the lead to
quotedAmountnumberQuoted value, in dollars
notesstringInternal notes

Receipt

An expense receipt.

FieldTypeDescription
idrequiredstringReceipt id
daterequireddateReceipt date
merchantrequiredstringMerchant name
amountrequirednumberTotal, in dollars
taxAmountnumberGST, in dollars
aiCategorystringExpense category
isDeductiblebooleanWhether the expense was assessed as deductible
descriptionstringDescription
statusrequiredstringProcessing status

Trip

A logged vehicle trip.

FieldTypeDescription
tripIdrequiredstringTrip id
daterequireddateTrip date
startTimedatetimeDeparture
endTimedatetimeArrival
startAddressstringStart address
endAddressstringEnd address
distanceKmrequirednumberDistance, in kilometres
purposestringPurpose, e.g. BUSINESS, PERSONAL, UNVERIFIED
notesstringNotes
jobIdstringJob the trip was for, if any
createdAtdatetimeCreated

TripCreate

Fields accepted when logging a trip.

FieldTypeDescription
distanceKmrequirednumberDistance, in kilometres
startTimedatetimeDeparture. The trip date is taken from this; defaults to now.
endTimedatetimeArrival
startAddressstringStart address
endAddressstringEnd address
purposestringPurpose, e.g. BUSINESS, PERSONAL. Defaults to UNVERIFIED.
notesstringNotes
jobIdstringJob the trip was for

Booking

A booked appointment.

FieldTypeDescription
bookingIdrequiredstringBooking id
daterequireddateBooking date
startTimerequiredstringStart time, HH:MM
endTimerequiredstringEnd time, HH:MM
clientNamerequiredstringCustomer name
clientPhonestringCustomer phone
clientEmailstringCustomer email
serviceTypestringRequested service
addressstringSite address
statusrequiredCONFIRMED | CANCELLEDStatus
sourcestringWhere the booking came from
leadIdstringLead the booking belongs to, if any
createdAtdatetimeCreated
updatedAtdatetimeLast updated

BookingCreate

Fields accepted when creating a booking.

FieldTypeDescription
daterequireddateBooking date
startTimerequiredstringStart time, HH:MM
endTimestringEnd time, HH:MM
clientNamerequiredstringCustomer name
clientPhonestringCustomer phone
clientEmailstringCustomer email
serviceTypestringRequested service
suburbstringSuburb
addressstringSite address. Geocoded on save.
notesstringNotes
leadIdstringLead this booking is for
pipelineIdstringPipeline for a lead created from this booking
sourcestringProvenance label. Defaults to api.

BookingUpdate

Fields accepted when updating a booking. Only fields sent are changed.

FieldTypeDescription
datedateBooking date
startTimestringStart time, HH:MM
endTimestringEnd time, HH:MM
clientNamestringCustomer name
clientPhonestringCustomer phone
clientEmailstringCustomer email
serviceTypestringRequested service
suburbstringSuburb
addressstringSite address. Geocoded on save.
notesstringNotes
statusCONFIRMED | CANCELLEDSet CANCELLED to cancel

TimeEntry

A logged block of time.

FieldTypeDescription
timeEntryIdrequiredstringTime entry id
daterequireddateDate
startTimestringStart time
endTimestringEnd time
durationMinutesrequirednumberDuration, in minutes
descriptionrequiredstringWhat was done
clientIdstringClient the time is for
jobIdstringJob the time is for
billablebooleanWhether the time is billable
invoiceIdstringInvoice the time was billed on, once invoiced
createdAtdatetimeCreated

TimeEntryCreate

Fields accepted when logging time.

FieldTypeDescription
datedateDate. Defaults to today.
durationMinutesrequirednumberDuration, in minutes
descriptionrequiredstringWhat was done
clientIdstringClient the time is for
jobIdstringJob the time is for
startTimestringStart time
endTimestringEnd time
projectstringProject label
billablebooleanWhether the time is billable. Defaults to true.

TimeEntryCreated

Returned after a time entry is logged.

FieldTypeDescription
timeEntryIdrequiredstringThe new time entry id

TimeEntryUpdate

Fields accepted when updating a time entry. Only fields sent are changed.

FieldTypeDescription
datedateDate. Defaults to today.
durationMinutesnumberDuration, in minutes
descriptionstringWhat was done
clientIdstringClient the time is for
jobIdstringJob the time is for
startTimestringStart time
endTimestringEnd time
projectstringProject label
billablebooleanWhether the time is billable. Defaults to true.

PriceBookItem

A reusable product or service line.

FieldTypeDescription
itemIdrequiredstringItem id
namerequiredstringName
descriptionstringDescription
unitPricerequirednumberUnit price, in dollars, before GST
unitstringUnit of measure, e.g. hour, each, m2
costPricenumberCost price, in dollars
qtyOnHandnumberStock on hand, for tracked products
reorderPointnumberReorder point, for tracked products
supplierIdstringSupplier id
createdAtdatetimeCreated
updatedAtdatetimeLast updated

PriceBookItemCreate

Fields accepted when creating a price book item.

FieldTypeDescription
namerequiredstringName
descriptionstringDescription. Defaults to the name.
unitPricerequirednumberUnit price, in dollars, before GST
unitstringUnit of measure, e.g. hour, each, m2
costPricenumberCost price, in dollars
qtyOnHandnumberStock on hand, for tracked products
reorderPointnumberReorder point, for tracked products
supplierIdstringSupplier id

PriceBookItemUpdate

Fields accepted when updating a price book item. Only fields sent are changed.

FieldTypeDescription
namestringName
descriptionstringDescription. Defaults to the name.
unitPricenumberUnit price, in dollars, before GST
unitstringUnit of measure, e.g. hour, each, m2
costPricenumberCost price, in dollars
qtyOnHandnumberStock on hand, for tracked products
reorderPointnumberReorder point, for tracked products
supplierIdstringSupplier id

WebhookEvent

The body of every webhook delivery.

FieldTypeDescription
idrequiredstringEvent id. Unique per event; the same id is re-sent on retries, so use it to deduplicate.
typerequiredstringTopic, e.g. invoice.paid
createdAtrequireddatetimeWhen the event happened
orgIdrequiredstringOrganisation the event belongs to
subjectobjectThe record the event is about.
FieldTypeDescription
typestringRecord type, e.g. invoice
idstringRecord id
datarequiredobjectTopic-specific payload. Always carries the subject id (invoiceId, jobId, leadId, …) and usually the fields that changed.