Skip to main content
Contacts (also called profiles) are the people in your audience. The Contacts API lets you create them, update them, and read them back. All requests require authentication.

Create or update a contact

POST /api/v1/customer/create Upserts a contact and returns 201 Created. If a contact with the same email or phone already exists, it’s updated; otherwise it’s created. This endpoint does not add anyone to a list — for that, see the Lists API.

Request

You must send email or phone — at least one. Everything else is optional.
string
The contact’s email address. Required unless you send phone.
string
Phone number, 7–20 characters. Required unless you send email. Needed for WhatsApp messaging.
string
Your own identifier for this person (your database ID), for reconciling across systems.
string
Max 100 characters.
string
Max 100 characters.
string
Email marketing consent: SUBSCRIBED, NON_SUBSCRIBED, or UNSUBSCRIBED. Defaults to NON_SUBSCRIBED when omitted. Only send SUBSCRIBED when the person actually opted in.
string
SMS/WhatsApp consent, same values. Defaults to NON_SUBSCRIBED.
boolean
Whether the contact is suppressed. Defaults to false.
boolean
Whether to require email confirmation before the contact counts as subscribed. Defaults to false.
string
Where this contact came from, e.g. booking-platform. Defaults to api.
string
Date of birth as an ISO 8601 date, e.g. 1990-01-15.
string
MALE, FEMALE, or OTHER. Case-sensitive.
string
Max 100 characters. Normalized to a country code on write.
string
Max 100 characters.
string
Max 100 characters.
string
Max 255 characters.
string
Max 255 characters.
string
3–20 characters.
object
Key–value pairs stored as custom fields — usable in segments and personalization. Maximum 30 keys per request, string values.
Omitting email_opt_in creates the contact as NON_SUBSCRIBED, and they will receive no marketing email. Set it explicitly whenever you have consent — this is the single most common reason API-created contacts appear to be ignored by campaigns.
Unrecognized fields are rejected with 400. Send first_name, not firstName.
Example request

Response

201 Created
Keep the id — it’s the stable identifier for fetching this contact later, and for sending events with contactUUID.

Custom properties

  • Maximum 30 keys per request; more returns 400.
  • Values are stored as strings. Numbers and booleans are converted; nested objects are not — they store as unusable text, so flatten them before sending.
  • Empty and whitespace-only values are dropped rather than stored.

Get a contact

GET /api/v1/customer/{id}
Returns the same profile envelope as above, or 404 if no contact has that ID.

List contacts

GET /api/v1/customer Returns contacts in pages.
For a one-time bulk load of an existing audience, the dashboard’s CSV import is faster and friendlier to rate limits than looping over this API.