Guides
Contacts
The marketing contact store — CRUD, batch upserts, CSV import/export, and how contacts are grouped.
Contacts are the marketing audience store: upserts, attributes, CSV import/export, plus static audiences (lists) and saved segments (filters).
Contacts
| Endpoint | Purpose |
|---|---|
POST /v1/contacts | Create (or fails cleanly if taken) |
GET /v1/contacts | List (?limit=, ?cursor=, tag/attribute filters) |
GET /v1/contacts/{id} | Fetch one |
PATCH /v1/contacts/{id} | Update |
DELETE /v1/contacts/{id} | Delete |
POST /v1/contacts/batch | Bulk upsert in one call |
Attributes are flat and schemaless — an object with at most 50 keys, ≤8 KiB serialised, values must be string/number/bool/null (no nesting):
{
"email": "ada@lovelace.io",
"attributes": { "name": "Ada", "plan": "payg", "seats": 3 }
}Reaching your plan's contact cap returns 402 contact_limit_reached.
Import & export
POST /v1/contacts/import— upload a CSV (multipart;empty_file,file_too_largeare the guardrails), then pollGET /v1/contacts/imports/{id}until the job finishes.POST /v1/contacts/export→ pollGET /v1/contacts/exports/{id}→ download atGET /v1/contacts/exports/{id}/download.
Grouping contacts
Two ways to address a set of contacts, each with its own guide:
- Audiences — static lists holding exactly whoever you put in them.
- Segments — saved filters over contact attributes, evaluated when you use them.
Reach for a segment when membership is a rule, and an audience when it is a decision.
Contacts power broadcasts
Broadcasts target an audience or segment; contacts are also where unsubscribes and preference-centre state live.