Conventions

Requests and responses

Send Accept: application/json, and Content-Type: application/json on requests with a body.
A single record comes back as { "data": { ... } }.
Create and update calls return 200 with the full record.
To change a record, send the fields you want it to end up with. Create and update share the same validation rules.

Pagination

List endpoints return one page at a time.

{
  "data": [ { "id": 101 }, { "id": 100 } ],
  "links": {
    "first": "https://{host}/api/public/v1/contacts?page=1",
    "last": "https://{host}/api/public/v1/contacts?page=8",
    "prev": null,
    "next": "https://{host}/api/public/v1/contacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 8,
    "per_page": 10,
    "from": 1,
    "to": 10,
    "total": 74
  }
}

Parameter	Description
`limit`	Records per page. The default is 10 and the maximum is 100. Larger values are lowered to 100.
`page`	Page number, starting at 1.

To read everything, request pages until links.next is null.

Search and filters

Every list accepts search, a free-text match over the record’s main fields, such as its number, name or email.

Resource	Filters
Contacts	`lifecycle_stage`, `status`, `user_id`
Works	`status`, `contact_id`, `vehicle_id`, `zone_id`, `from`, `to`
Invoices and quotations	`status`, `contact_id`, `from`, `to`

from and to take YYYY-MM-DD and include the whole day in the workspace timezone.

Dates and times

Dates you send, such as work_date and document_date, are YYYY-MM-DD. Times, such as time_window_from, are HH:mm. Both are in the workspace timezone, not UTC. Dates and times in responses are also shown in the workspace timezone.

Money

Amounts you send and receive are in major currency units, for example 250.00 for two hundred and fifty ringgit. This applies to unit_amount, amount_paid, final_amount and the other totals. Do not send or expect cents. Each document carries its own currency. Totals are calculated by BeanRails from the items, taxes and discounts, so you cannot set them directly.

Statuses

Works, invoices, quotations and contacts have a status value and a status_name. Use status in your code. Workspaces can rename statuses and add their own, so status_name can differ between customers.

Resource	Built-in values
Works	`new`, `vehicle_assigned`, `in_progress`, `failed`, `cancelled`, `completed`
Invoices	`draft`, `unpaid`, `partially_paid`, `paid`, `voided`, `refunded`
Quotations	`draft`, `pending`, `invoiced`, `completed`, `cancelled`

Custom fields

If your workspace has custom fields on contacts, works or addresses, they appear on records and can be sent on create and update. Their keys follow the names set up in the workspace.

Getting started

Essentials

Requests and responses

Search and filters

Dates and times

Money

Statuses

Custom fields

​Requests and responses

​Pagination

​Search and filters

​Dates and times

​Money

​Statuses

​Custom fields

Requests and responses

Pagination

Search and filters

Dates and times

Money

Statuses

Custom fields