# Use the Quoterium API

> Generate your organisation's API token, make requests, and what the API can and can't do, with its limits and errors.

The Quoterium API lets your own systems — a CRM, an accounting or project tool, a spreadsheet script — read and write your organisation's **clients**, **contacts** and **quotes**. Typical uses: keep clients and contacts in step with your CRM, import quotes prepared elsewhere as drafts, and export quotes and their PDFs.

The full reference, with every field and a way to try requests, is the [API reference](https://app.quoterium.com/api/v1/docs). It is also available as an [OpenAPI description](https://app.quoterium.com/api/v1/openapi.json) for tools that generate code.

## Generate the token

Each organisation has one API token. Admins manage it:

1. Go to [**Settings → Integrations**](https://app.quoterium.com/settings/integrations) and scroll to **API**.
2. Choose **Generate token**.
3. Copy the token from the dialog and store it somewhere safe, such as your system's secret settings or a password manager. It is shown only once.
4. Choose **Done**.

The API section then shows the token's first characters, who generated it, when, and when it was last used.

- **Generate new token** replaces the token: the old one stops working at once, so update anything that uses it.
- **Revoke** removes the token: every request using it is refused until you generate a new one.

Anyone with the token can read and change your clients, contacts and quotes, so treat it like a password: call the API from your server, never from a web page in the browser (the API has no cross-origin access anyway). Requests act as the person who generated the token: quotes they import are owned by that person and their history says *Created through the API*. If that person leaves the organisation, the token keeps working and acts as the owner.

## Making requests

Send the token in the `Authorization` header of every request, and JSON in the body when you create or update something. The base URL is shown in the API section of Settings → Integrations.

```
curl https://app.quoterium.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Responses are JSON. The result is in `data`; lists also have `meta` with `page`, `per_page` (up to 200) and `total`. Times are in UTC.

## What you can do

- **Clients**: list and search them, get one with its contacts, create and update.
- **Contacts**: list, search or look up by email address, get one, create and update.
- **Quotes**: list them with filters, get one with its items, totals, payment schedule and recipients, download its PDF, and import a new quote as a draft.
- **Reference lists**: your templates, tax rates and sales categories, for imports.

Nothing can be deleted through the API. To retire a client or contact, set `is_archived` to `true`. Quotes can't be sent, accepted or changed through the API: you check and send imported drafts in Quoterium as usual.

## Limits

- 120 requests a minute per token. Beyond that the API answers **429** with a `Retry-After` header giving the seconds to wait.
- Imported quotes count towards your plan's quotes per month, like quotes created in the app.
- While your account is locked (the trial has ended or the subscription was cancelled) every request answers **402**. Choose a plan to continue. See [When access is locked](https://quoterium.com/help/billing-and-plans/account-locked).

## Errors

- **401**: the token is missing, wrong, replaced or revoked.
- **404**: the record doesn't exist in your organisation.
- **422**: something you sent isn't valid. `errors` names each field, for example `"items.2.unit_price"` for the third item's price.

See also [Import quotes with the API](https://quoterium.com/help/api/import-quotes-with-the-api) and [Sync clients and contacts with the API](https://quoterium.com/help/api/sync-clients-and-contacts-with-the-api).

Source: https://quoterium.com/help/api/use-the-api