/ Docs
API ReferenceContacts

List Contacts

Page Tools
GET/contacts

Cursor-paginated list of the brand's contacts, newest first. Archived contacts are hidden by default (status=active).

Authenticate with your brand’s x-api-key.Authentication

Query Parameters

statusstring

Default: active

Allowed values"active""archived""all"
  • Default: "active"
tagmultiple types

Filter by tag; repeat the parameter to require multiple tags

Show child fieldsHide child fields for query.tag

Use one of these shapes.

string

Filter by tag; repeat the parameter to require multiple tags

  • 1–100 characters
emailstring

Exact email lookup (case-insensitive)

  • Format: email
phoneNumberstring

Exact phone lookup (E.164 or digits-only)

cursorstring

Opaque cursor from pagination.nextCursor

limitinteger

1-100, default 50

  • Minimum: 1
  • Maximum: 100
  • Default: 50

Responses

Page of contacts

dataarray of objectrequired
Show item detailsHide item details for response-200.data

Each item

idstringrequired
phoneNumberstringrequired

Always returned in E.164 format

activebooleanrequired

false when the contact has been archived (DELETE)

firstNamestring · nullablerequired
lastNamestring · nullablerequired
emailstring · nullablerequired
statestring · nullablerequired
countrystring · nullablerequired
dobstring · nullablerequired

Date of birth (YYYY-MM-DD)

genderstring · nullablerequired
preferredLanguagestring · nullablerequired
tagsarray of stringrequired
Show item detailsHide item details for response-200.data[].tags

Each item

string
customFieldsobjectrequired

Stored custom-field values keyed by field name. See create/update request schemas for accepted write types and limits.

Show child fieldsHide child fields for response-200.data[].customFields
[key]any

Additional keys may contain any JSON value.

marketingConsentobjectrequired
Show child fieldsHide child fields for response-200.data[].marketingConsent
channelstringrequired
Allowed values"MOBILE"
statusstringrequired

Campaigns are only sent to OPTED_IN contacts. Contacts created via the API start as UNKNOWN until consent is set.

Allowed values"UNKNOWN""SENT""OPTED_IN""OPTED_OUT"
updatedAtstring · nullablerequired
createdAtstringrequired
updatedAtstringrequired
paginationobjectrequired
Show child fieldsHide child fields for response-200.pagination
limitnumberrequired
hasMorebooleanrequired
nextCursorstring · nullablerequired

Opaque cursor for the next page; null on the last page

Execute a Workflow Batch

POST /workflows/{workflowDefinitionId}/execute

Create or Update a Contact

POST /contacts