Contacts
List, create, update, and permanently delete contacts in your workspace.
On this page
Authentication and permissions
Send your workspace API key as an Authorization: Bearer token. The key determines the workspace.
| Endpoint | Required scope |
|---|---|
| GET /api/v1/contacts | audience:read or audience:write |
| POST /api/v1/contacts | audience:write |
| PATCH /api/v1/contacts/{contactId} | audience:write |
| DELETE /api/v1/contacts/{contactId} | audience:write |
Writes and retries
The API key must have been created by a current workspace member. Use a unique Idempotency-Key for each intended write. Reuse it only when retrying the same operation with the same input.
List contacts
Read contacts, newest first, with optional state, list, and email filters.
Create or update a contact
Use POST to create a new contact. Use PATCH with a contact ID to change only the supplied fields.
Delete a contact
Permanently remove a contact and its list memberships by contact ID.
Existing assistant integrations
MCP and existing integrations can continue using contact.list, contact.save, and contact.delete through POST /api/v1/assistant. The legacy contact.save action retains its create-or-update and replacement behavior.