Skip to main content
Profiles are contacts. Every write is confined to your workspace by row-level security, and every consent change is logged. All endpoints authenticate with the X-Sender-Tenant + X-API-Key headers.

​
The profile object

​
id
string
Contact UUID.
​
email
string
​
phone
string
​
firstName
string
​
lastName
string
​
timezone
string
​
locale
string
​
emailConsent
string
subscribed / unsubscribed / never_subscribed / cleaned.
​
smsConsent
string
​
pushConsent
string
​
emailConsentTimestamp
string
​
smsConsentTimestamp
string
​
pushConsentTimestamp
string
​
emailValidationState
string
​
customProperties
object
​
tags
string[]
​
rfmTier
string
​
notes
string
​
emailSuppressed
boolean
​
createdAt
string
​
updatedAt
string

​
List profiles

​
limit
integer
default:"50"
Page size 1–100.
​
offset
integer
default:"0"
Records to skip.
​
page
integer
1-based page (alternative to offset).
​
search
string
Free-text search (max 255).
​
segmentId
string
Filter to a segment (UUID).
​
consent
string
subscribed / unsubscribed / never_subscribed / cleaned.
​
channel
string
email or sms.
​
sort
string
Sort key, e.g. -createdAt, -updatedAt.
Returns a paginated list of profile objects.

​
Get a profile by email

​
email
string
required
The email to look up.
Returns the profile object, or 404 Profile not found.

​
Get a profile by ID

Returns the profile object.

​
Create a profile

​
email
string
Max 320.
​
phone
string
Max 32.
​
firstName
string
Max 128.
​
lastName
string
Max 128.
​
timezone
string
Max 64.
​
locale
string
Max 10.
​
emailConsent
string
Consent enum.
​
smsConsent
string
Consent enum.
​
pushConsent
string
Consent enum.
​
emailConsentSource
string
Max 64.
​
smsConsentSource
string
Max 64.
​
pushConsentSource
string
Max 64.
​
tags
string[]
​
customProperties
object
​
notes
string
Max 4000, or null.

​
Upsert a profile

Same body as create. Matches an existing contact by email or phone and creates one if none matches. Requires at least one of email / phone.

​
Update a profile by email

The email is a lookup key — it isn’t rewritten unless you pass newEmail. Returns 404 if the email isn’t found.
​
email
string
required
Lookup key (max 320).
​
newEmail
string
Rename the contact’s email.
​
phone
string
​
firstName
string
​
lastName
string
​
timezone
string
​
locale
string
​
emailConsent
string
Consent enum.
​
smsConsent
string
Consent enum.
​
pushConsent
string
Consent enum.
​
tags
string[]
​
customProperties
object
​
notes
string
Max 4000, or null.
​
city
string
​
country
string
​
stateProvince
string
​
zip
string
​
address1
string
​
address2
string
​
dateOfBirth
string
​
gender
string
​
jobTitle
string
Address-style fields (city, country, zip, DOB, gender, job title) merge into customProperties — they aren’t native columns.

​
Update a profile by ID

Same field set as create, addressed by UUID.

​
Blacklist

​
email
string
Required unless contactId is given.
​
contactId
string
Contact UUID.
​
channel
string
email, sms, or both.
POST suppresses the contact on the channel; DELETE lifts it. Both return the profile object.