# Conventions

> Names, IDs, times, phone numbers, money and the shape of every answer. The same rules apply to every call.

Last updated: 2026-10-30. Source: https://docs.smartchat.marketing/en/concepts/conventions/

## Names

- Everything is English. Fields, parameters, values, error codes, event names and tool names use `snake_case` (events use `resource.event`, for example `contact.created`).
- Paths use lower case with hyphens and plural nouns, for example `/contacts` and `/webhook-endpoints`. A path with a single object per account is singular, for example `/landing-page`.
- Actions are sub-paths with a verb, for example `/contacts/{contact_id}/unsubscribe`.

## IDs

Every ID has a prefix that tells you the kind of object. If you send an ID of the wrong kind, the answer is [`validation_failed`](https://docs.smartchat.marketing/en/errors/#validation_failed), not "not found".

| Object | ID starts with | Example |
|---|---|---|
| Contact | `con_` | `con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Conversation | `cnv_` | `cnv_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Send | `snd_` | `snd_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Template | `tpl_` | `tpl_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Newsletter | `nwl_` | `nwl_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Automation | `aut_` | `aut_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Automation run | `run_` | `run_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Follow-up sequence | `fup_` | `fup_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Follow-up step | `stp_` | `stp_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Learned answer | `ans_` | `ans_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Knowledge document | `doc_` | `doc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Media file | `med_` | `med_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Webhook endpoint | `whe_` | `whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Webhook delivery | `whd_` | `whd_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Event | `evt_` | `evt_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Preview plan | `pln_` | `pln_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Contact export | `exp_` | `exp_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| API key | `key_` | `key_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |
| Account | `acc_` | `acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234` |

Objects of other accounts look the same as objects that do not exist: you always get a "not found" answer. This is on purpose.

## Times, phone numbers, money

- Times are ISO 8601 in UTC with `Z`, for example `2026-10-25T09:41:07Z`. Events have milliseconds. Field names end in `_at` for a point in time and `_on` for a date (`YYYY-MM-DD`). You may send a time with an offset such as `+01:00`; you get UTC back.
- Phone numbers use the E.164 format, for example `+4915112345678`. An invalid number gives [`invalid_phone_number`](https://docs.smartchat.marketing/en/errors/#invalid_phone_number).
- Money is a whole number in the smallest unit plus `currency` in lower case (`eur`). Credits are whole numbers. There are no floating point numbers for money.
- Booleans are `true` and `false`. A value that is not set is `null`, never `""`.

## Fixed values

| Field | Values | Meaning |
|---|---|---|
| optin_whatsapp | `none`, `pending`, `confirmed`, `opted_out` | WhatsApp opt-in state of a contact. |
| send status | `queued`, `sent`, `delivered`, `read`, `failed`, `skipped` | State of a single send. |
| template status | `draft`, `pending`, `approved`, `rejected`, `paused` | State of a message template. |
| newsletter status | `draft`, `scheduled`, `sending`, `paused`, `completed`, `canceled`, `failed` | State of a newsletter. |
| automation status | `draft`, `active`, `paused` | State of an automation. A new automation without a status is a draft. |
| conversation status | `open`, `closed` | State of a conversation. |
| acquisition | `landing_page`, `import`, `api`, `manual`, `automation`, `service` | Where a contact came from. |
| contact status (`status`) | `confirmed`, `unconfirmed`, `opted_out`, `automation`, `support` | Kind of a contact. `confirmed` and `unconfirmed` say if the opt-in is done, `opted_out` is a contact who unsubscribed. |
| purpose | `marketing`, `automation`, `service` | Why a contact was created: for marketing, for an automation or for service messages. |
| tag origin (`origin`) | `system`, `manual`, `ai` | Who set a tag: the system, a person, or the AI. |

## The shape of an answer

An object is returned flat, with `object` (the kind) and `id`:

```json
{
  "object": "contact",
  "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "name": "Mia Muster",
  "phone": "+4915112345678",
  "email": null,
  "tags": ["regular customer"],
  "optin_whatsapp": "confirmed",
  "created_at": "2026-10-25T09:41:07Z"
}
```

A list wraps objects in `data` ([pagination](https://docs.smartchat.marketing/en/concepts/pagination/)):

```json
{ "object": "list", "data": [], "has_more": false, "next_cursor": null, "url": "/v1/contacts" }
```

There is no `ok` or `success` field. Success is the HTTP status; a problem is an [error](https://docs.smartchat.marketing/en/concepts/errors-overview/).

## Headers on every answer

| Header | Meaning |
|---|---|
| `Request-Id` | ID of this request (`req_...`). Give it to support. |
| `SmartChat-Version` | Version of the API that answered ([versioning](https://docs.smartchat.marketing/en/concepts/versioning/)). |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Class` | Your [rate limit](https://docs.smartchat.marketing/en/concepts/rate-limits/). |

New fields can appear in answers at any time. Ignore fields you do not know.