Skip to main content
Main families: contacts, tags, topics, segments, campaigns, tasks. Campaigns also need send scopes per channel (whatsapp:send, sms:send, …).
Each scope unlocks one type of Contacts operation. Use only what your integration needs.

​
How to send the key

Recommended
Alternative
The API Key belongs to one workspace. You cannot access another workspace with the same key.

​
Common combinations

Read database only

contacts:read, tags:read

Sync CRM

contacts:read, contacts:create, contacts:update, tags:read, tags:create

Task queue

tasks:read (workspace list) + contacts:update (create/update on contact)

Campaigns via API

campaigns:read, campaigns:create, campaigns:run + channel send scopes

Full management

All contacts:*, tags:*, topics:*, segments:*, campaigns:*
An empty scope list on create = ADMIN access. Always restrict in production.

​
Contacts (contacts:*)

List and get contact by ID.
Create contact (phone and/or email required).
Edit record, tags, fields, and CRM tasks (POST/PATCH /v1/contacts/{id}/tasks).
Delete contact.

​
Tasks (tasks:read)

CRM tasks appear at two levels: on the contact and workspace view.
GET /v1/tasks — paginated workspace list (status, overdueOnly, assignedUserId). Default: OPEN tasks.
Create and update tasks use scope contacts:update (POST and PATCH on /v1/contacts/{id}/tasks). List tasks on a contact uses contacts:read. There is no DELETE in API v1 — use PATCH with status: CANCELLED to cancel.

​
Tags (tags:*)

List and get tag.
Create reusable label.
Rename tag.
Delete tag.

​
Topics (topics:*)

Marketing theme consent. Same as Audience → Topics in the dashboard.
List and get topic.
Create topic with stable slug.
Edit name, description, and default opt-in.
Delete topic.

​
Segments (segments:*)

Audiences with rules (tags, fields, topics, marketing). Includes preview.
List, get, and preview (paginated audience sample).
Create segment with JSON version: 1, match, rules.
Edit segment rules.
Delete segment.

​
Campaigns (campaigns:*)

List, get, statistics, and recipients per run.
Create campaign (optionally with scheduledFor).
Edit campaign and cancel (DRAFT/SCHEDULED → CANCELLED).
Delete campaign.
Dispatch now (Run), queues sends on campaign channels.
Running a campaign requires campaigns:run and send scopes for each channel (whatsapp:send, sms:send, email:send, telegram:send, push:send, rcs:send, instagram:send) when the queue processes messages.

​
Common errors

Check the operation scope (Missing scope: contacts:read, etc.).
Expired or suspended plan (WORKSPACE_BLOCKED). Fix in the dashboard.
Topic/segment/campaign limits (PLAN_LIMIT_CRM, PLAN_LIMIT_TEMPLATES) or trial without top-up. Code 403, not 402.
Phone or email already registered in the workspace.

​
Next steps