> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.beanrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Pagination, search, filters, dates and money.

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

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.