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

# Conventions

> Paths, ids, paging, errors and time in the Partner API.

## Base address and paths

All routes start with `https://api.impellabs.tech/api/v1/partner/`. Every path ends with a slash. A request without the
final slash does not work: a `GET` is redirected and a `POST` fails. Bodies are JSON, except a file upload, which is
multipart form data.

## Ids

| Id | What it is |
| - | - |
| `external_ref` | Your own id for a tenant. Plain text with no slash. It cannot be `list`, `.` or `..`. It is the key of every tenant route. |
| `id` of a tenant | The id of the workspace. UUID. |
| `phone_number_id` | The WhatsApp number id from Meta. It is the `{pnid}` in a path. |
| `page_id` | The Facebook Page id from Meta. |
| Conversation, message, endpoint | UUIDs that ImpelLabs makes. |

## Tenants are yours only

A tenant of another partner, and a tenant that does not exist, both answer 404. No call tells you which of the two it
is.

## Paging

Tenant lists use pages. Send `page`. The answer holds `results`, `page`, `page_size` (100), `total` and `has_more`.

Conversation lists and message lists use a cursor. Send `limit`, and `after` with the `next_cursor` of the page before.
The answer holds `has_more` and `next_cursor`. An `after` that names nothing answers 400.

The list of webhook deliveries shows the last 200 and has no paging.

## Errors

An error has a 4xx or 5xx status and one of two shapes.

```json theme={null}
{ "detail": "Tenant not found." }
```

```json theme={null}
{ "error": { "code": "outside_customer_service_window", "message": "The 24-hour customer service window is closed. Send an approved template instead." } }
```

Some errors add `code` or `field` beside `detail`. A validation error names the field that failed. Branch on `code`
when it is present. Do not branch on `message`.

| Status | Meaning |
| - | - |
| 400 | The body or a parameter is not valid. Do not repeat it unchanged. |
| 401 | The key is missing, wrong, revoked or expired. |
| 403 | The scope is missing, the request came from a browser, or your partner account is suspended. |
| 404 | The tenant or the item is not yours or does not exist. |
| 409 | The request is valid but the state is not ready. Read `code`, for example `human_control`, `number_claimed`, `no_binding`, `no_return_url`, `opted_out`. |
| 422 | A channel rule refused it, for example `outside_customer_service_window`, `text_only` or `tag_unsupported`. |
| 502 | The channel provider refused the call. Read `error.message`. |
| 503 | WhatsApp sign-up is not set up on this server. |

## Repeating a call

Creating a tenant is safe to repeat: the same `external_ref` answers 200 with the tenant that exists. Sending the
WhatsApp sign-up `code` is not safe to repeat, because the code works once. Read the channel before you decide.

## Time

Times are ISO 8601. They are stored in UTC. Show them in the zone of your viewer.


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