The Contacts API manages the audience your workspace sends messages to. Each contact is a person identified by email address, phone number, or both.

​
Endpoints

MethodPathDescription
POST/v1/contactsCreate or upsert a contact
GET/v1/contacts/{id}Get a single contact with consent records
PATCH/v1/contacts/{id}Update contact fields
DELETE/v1/contacts/{id}Delete a contact (manager role)
POST/v1/contacts/importBulk import up to 10,000 contacts
GET/v1/contacts/{id}/consentList consent records
POST/v1/contacts/{id}/consentGrant or update consent
DELETE/v1/contacts/{id}/consent/{record_id}Revoke a consent record

​
The contact object

Contacts are returned with their full consent history embedded in consent_records. 
{
  "id": "c_a1b2c3d4",
  "external_id": "usr_9901",
  "email": "jana@example.com",
  "phone": "+4917612345678",
  "first_name": "Jana",
  "last_name": "Müller",
  "status": "ACTIVE",
  "source": "API",
  "tags": ["vip", "germany"],
  "custom_fields": { "loyalty_tier": "gold" },
  "consent_records": [
    {
      "id": "cr_a1b2c3",
      "channel_type": "EMAIL",
      "message_type": "NEWSLETTER",
      "status": "GRANTED",
      "source": "landing_page",
      "proof_text": "Opted in via signup form at shop.example.com/subscribe",
      "granted_at": "2026-01-10T08:00:00Z",
      "revoked_at": null,
      "created_at": "2026-01-10T08:00:00Z"
    }
  ],
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-03-28T09:00:00Z"
}

​
Fields

​
id
string
Platform-assigned contact identifier.
​
external_id
string
Your own identifier for this contact. Unique within the workspace. Useful for syncing with a CRM.
​
email
string
Email address. Used for email channel sends and deduplication.
​
phone
string
Phone number in international format (e.g. +4917612345678). Used for SMS and RCS sends.
​
first_name
string
First name. Available as a merge tag in templates.
​
last_name
string
Last name. Available as a merge tag in templates.
​
status
string
Lifecycle status of the contact.
ValueMeaning
ACTIVECan receive messages
UNSUBSCRIBEDOpted out — blocked from NEWSLETTER sends
BOUNCEDHard bounce — blocked from email sends
BLOCKEDManually or policy blocked — no sends
​
source
string
How the contact entered the system: API, IMPORT, LANDING_PAGE, or MANUAL.
​
tags
array
Free-form string labels. Used for segmentation and filtering in campaigns.
​
custom_fields
object
Arbitrary key-value pairs for extra contact attributes. Values are merged on update.
​
consent_records
array
All consent records for this contact. Each record covers one channel_type + message_type combination. See Consent API for full field reference.

​
Deduplication

A contact is deduplicated by email hash within a workspace. If you POST /v1/contacts with an email that already exists, the platform upserts the record and returns the existing contact with updated fields rather than creating a duplicate.

​
Suppression

Contacts with status UNSUBSCRIBED, BOUNCED, or BLOCKED are automatically suppressed from message sends. Attempting to send to a suppressed contact returns a 422 with reason: "contact_suppressed".

Create contact

Import contacts

Consent