Developers · REST API
API reference
Every endpoint, the scope it needs and what it does.
Base path https://api.example.com/api/v1. Every request needs Authorization: Bearer <API key>. Requests and responses are JSON.
Conversations
| Request | Scope | Does |
|---|---|---|
GET /conversations | inbox:read | List conversations. Filters: search, assignee, team_id, label, bucket (primary or general). |
GET /conversations/:id | inbox:read | One conversation |
GET /conversations/:id/messages | inbox:read | Its messages, with status |
POST /conversations/:id/messages | inbox:send | Send a message. See Send messages. |
POST /conversations/:id/notes | inbox:send | Add an internal note |
POST /conversations/:id/assign | inbox:assign | Assign to a user or team |
POST /conversations/:id/status | inbox:assign | Open, pending or closed |
POST /conversations/:id/snooze | inbox:assign | Snooze until a time |
POST /conversations/:id/read | inbox:read | Mark as read |
Contacts
| Request | Scope | Does |
|---|---|---|
GET /contacts | contact:read | List. Filters: search, tag, stage; paging with limit (max 500) and offset. Returns items and total. |
POST /contacts | contact:create | Create, or update by phone. Body: phone, name, email, tagIds, attributes, phone_number_id. Returns conversation_id. |
GET /contacts/:id | contact:read | One contact |
PATCH /contacts/:id | contact:edit | Update fields |
DELETE /contacts/:id | contact:delete | Delete |
POST /contacts/:id/tags | contact:edit | Add tags |
DELETE /contacts/:id/tags/:tagId | contact:edit | Remove a tag |
GET /contacts/:id/timeline | contact:read | Everything that happened to the contact |
POST /contacts/:id/notes | contact:edit | Add a note |
POST /contacts/:id/conversation | inbox:read | Get or open the contact’s conversation; returns conversation_id. |
POST /contacts/import | contact:import | Import many contacts |
GET /contacts/export.csv | contact:export | Download all contacts as CSV |
Templates
| Request | Scope | Does |
|---|---|---|
GET /templates | template:read | List templates and their status |
GET /templates/resolve?name=&language= | template:read | A template’s variables and a preview |
GET /templates/:id | template:read | One template |
POST /templates/sync | template:sync | Sync with Meta |
Campaigns
| Request | Scope | Does |
|---|---|---|
GET /campaigns | campaign:read | List campaigns |
POST /campaigns | campaign:create | Create a draft campaign |
GET /campaigns/:id | campaign:read | One campaign with its counts |
GET /campaigns/:id/recipients | campaign:read | Each recipient’s status |
GET /campaigns/:id/export.csv | campaign:read | Recipients as CSV |
POST /campaigns/:id/launch | campaign:send | Start sending |
POST /campaigns/:id/pause · /resume | campaign:send | Pause or resume |
POST /campaigns/:id/cancel | campaign:cancel | Cancel |
Segments, tags, workflows, webhooks, search
| Request | Scope | Does |
|---|---|---|
GET /segments | contact:read | List segments |
GET /segments/:id/contacts | contact:read | A segment’s members |
GET /tags · POST /tags | tag:read · tag:create | List or create tags |
GET /automation-flows | workflow:view | Published, active workflows |
POST /automation-flows/:id/run | workflow:execute | Start a workflow for a conversation. Body: {"conversation_id": "…"}. |
GET /outbound-webhooks · POST | webhook:read · webhook:create | List or register webhooks |
GET /search?q= | contact:read and/or inbox:read | Search contacts and conversations |
Note
Endpoints that need a feature outside your plan return
403 FEATURE_NOT_IN_PLAN. See Errors and limits.Still stuck? Contact us with what you were doing and the exact message you saw.