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, 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.
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:

{
  "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):

{ "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.

#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).
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Class`	Your rate limit.

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