Contacts

Contacts are the people you interact with across all channels. Each contact can have custom attributes, multiple identities, consent preferences, tags, and a score.

List Contacts

GET /api/workspaces/{workspaceId}/contacts

Paginated list of contacts with optional filtering.

Auth: Session required

Query Parameters:

Response:

{
  "data": [
    {
      "id": "ct_abc123",
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "score": 42,
      "attributes": { "plan": "pro" },
      "tags": [{ "id": "tag_1", "name": "VIP" }],
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "totalPages": 25
  }
}

Create Contact

POST /api/workspaces/{workspaceId}/contacts

Auth: Session required

Request Body:

{
  "email": "jane@example.com",
  "phone": "+1234567890",
  "firstName": "Jane",
  "lastName": "Smith",
  "externalId": "ext_123",
  "attributes": { "plan": "pro", "company": "Acme" },
  "tags": ["VIP", "Enterprise"]
}

Response (201): Contact object with tags and consents.

Get Contact

GET /api/workspaces/{workspaceId}/contacts/{contactId}

Returns the full contact profile including identities, consents, tags, recent events (50), recent messages (50), active segment memberships, and push subscriptions.

Auth: Session required

Update Contact

PATCH /api/workspaces/{workspaceId}/contacts/{contactId}

Partially updates a contact’s profile fields.

Auth: Session required

Request Body: Any subset of email, phone, firstName, lastName, externalId, attributes.

Delete Contact

DELETE /api/workspaces/{workspaceId}/contacts/{contactId}

Permanently deletes a contact and all associated data.

Auth: Session required

Import Contacts (Bulk)

POST /api/workspaces/{workspaceId}/contacts/import

Bulk import contacts with deduplication.

Auth: Session required

Request Body:

{
  "contacts": [
    {
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "tags": ["imported"]
    },
    {
      "email": "john@example.com",
      "firstName": "John"
    }
  ],
  "deduplicateBy": "email",
  "updateExisting": true
}

Response:

{
  "total": 100,
  "created": 85,
  "updated": 10,
  "skipped": 5,
  "errors": [
    { "index": 23, "error": "Invalid email format" }
  ]
}

Merge Contacts

POST /api/workspaces/{workspaceId}/contacts/merge

Merges two contacts — the source contact’s data is transferred to the target, and the source is deleted.

Auth: Session required

Request Body:

{
  "sourceContactId": "ct_source",
  "targetContactId": "ct_target"
}

Transfers: events, messages, enrollments, segment memberships, inbox threads, identities, tags, and attributes.

Contact Timeline

GET /api/workspaces/{workspaceId}/contacts/{contactId}/timeline

Returns a unified reverse-chronological activity timeline.

Query Parameters:

Response:

{
  "timeline": [
    {
      "id": "evt_123",
      "type": "page_view",
      "category": "event",
      "timestamp": "2026-01-15T10:00:00.000Z",
      "data": { "pageUrl": "/pricing" }
    },
    {
      "id": "msg_456",
      "type": "SENT",
      "category": "message",
      "timestamp": "2026-01-15T09:30:00.000Z",
      "data": { "channel": "EMAIL", "subject": "Welcome!" }
    }
  ],
  "hasMore": true
}

Consent Management

GET /api/workspaces/{workspaceId}/contacts/{contactId}/consent

Lists all consent records for a contact.

PUT /api/workspaces/{workspaceId}/contacts/{contactId}/consent

Creates or updates consent status for a specific channel.

Request Body:

{
  "channel": "EMAIL",
  "status": "OPTED_IN",
  "source": "preference-center"
}

Data Export (DSR)

GET /api/workspaces/{workspaceId}/contacts/{contactId}/export

“Export My Data” — Returns all data associated with a contact (identities, consents, tags, events, messages, segments, enrollments, push subscriptions, threads).

POST /api/workspaces/{workspaceId}/contacts/{contactId}/export

“Forget Me” — Anonymizes the contact by nulling PII, deleting identities and push subscriptions. Requires ADMIN role. Logs an audit event.

Response:

{
  "success": true,
  "message": "Contact data has been anonymized"
}