Create or update profiles
- Path
/profiles- Auth
- Secret key · server only
const url = 'https://releva.ai/api/v0/profiles';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"profiles":[{"profile":{"id":"DEMO-CUST-1001","email":"maria@example.com","firstName":"Maria","lastName":"Example","registeredAt":"2026-05-01T09:00:00Z","subscribedAt":"2026-05-01T09:05:00Z","unsubscribeLink":"https://demo-store.example.com/unsubscribe/DEMO-CUST-1001","addTags":["vip"],"custom":{"string":[{"key":"loyaltyTier","values":["gold"]}]}},"subscribedAtChanged":true}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://releva.ai/api/v0/profiles \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "profiles": [ { "profile": { "id": "DEMO-CUST-1001", "email": "maria@example.com", "firstName": "Maria", "lastName": "Example", "registeredAt": "2026-05-01T09:00:00Z", "subscribedAt": "2026-05-01T09:05:00Z", "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-CUST-1001", "addTags": [ "vip" ], "custom": { "string": [ { "key": "loyaltyTier", "values": [ "gold" ] } ] } }, "subscribedAtChanged": true } ] }'Sends bulk profile updates, intended for backfill and bulk sync from your server. Profiles that do not exist
are created. Events recorded by a write (subscribe, register) can start triggered workflows.
Writes go to the domain that owns the secret key. Each entry is matched to an existing
profile by id, email (case-insensitive) or phoneNumber; unmatched entries create a profile.
Fields you omit keep their stored value. addTags/removeTags, addSubscriptions/removeSubscriptions
and addCustom change only what they name; subscriptions and custom replace the whole list or object.
The write is synchronous: the profile can be read back with GET as soon as the response arrives.
Entries without any identifier are skipped; the request fails only if no entry is left.
Send email or phoneNumber (international form, + and digits). To unsubscribe a user, call POST /unsubscribe.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Unknown top-level keys are ignored.
object
object
Send email or phoneNumber with every profile, plus your id. The API skips an entry with none of the three; an entry with only id updates an existing profile with that id and does not create a profile you can read back.
object
Your customer id.
International form (+359888000101) or national form (0888000101). National numbers and values with
spaces or dashes (5-15 characters) are converted to +<digits> with the dialling code of the domain’s country
before validation. The result must match ^\+\d{1,31}$.
ISO-8601 date and time with seconds and a timezone offset, optional milliseconds.
When the user subscribed to your marketing. Omit it and the subscription status does not change (leaving it out
never unsubscribes). Send it only for a subscribed user, with subscribedAtChanged: true on the entry. A date
not later than the last opt-out does not re-subscribe. Do not send null: to unsubscribe, call POST /unsubscribe.
YYYY-MM-DD only.
Replaces the subscription list. To clear it, send an empty array []. Do not send null.
Adds subscriptions to the list. Adding a User Visible Subscription can also subscribe a profile that never answered; use subscribedAt or the Consent API to change consent.
Removes subscriptions from the list (case-insensitive). Removing the last User Visible Subscription can also unsubscribe the profile; use the Consent API to unsubscribe.
Your per-profile unsubscribe URL (http or https). Leave it out if the profile is not subscribed.
Replaces all custom fields.
object
object
object
object
Merges by key; keys you send replace their values, other keys are kept.
object
object
object
object
object
legitimateInterest (default), privacyPolicy, cookiesPolicy or mandatoryCookies. A consent is never
replaced by a lower one (cookiesPolicy = mandatoryCookies > privacyPolicy > legitimateInterest).
Unknown values are ignored.
Send true whenever you send subscribedAt.
Example
{ "profiles": [ { "profile": { "id": "DEMO-CUST-1001", "email": "maria@example.com", "firstName": "Maria", "lastName": "Example", "registeredAt": "2026-05-01T09:00:00Z", "subscribedAt": "2026-05-01T09:05:00Z", "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-CUST-1001", "addTags": [ "vip" ], "custom": { "string": [ { "key": "loyaltyTier", "values": [ "gold" ] } ] } }, "subscribedAtChanged": true } ]}Responses
Section titled “Responses”Accepted for asynchronous processing.
object
Example
{}Authentication or validation error.
object
Human-readable error. Several validation errors are joined with a space.
Examples
{ "message": "Authorization header is missing."}{ "message": "Domain with the provided secret key cannot be found."}{ "message": "The 'profiles' field is required."}{ "message": "The 'profiles' field must contain at least 1 items."}{ "message": "profiles[0].profile: at least one of (id, email, phoneNumber) is required"}{ "message": "The object 'profiles[0].profile' contains forbidden keys: 'tags'."}{ "message": "The 'profiles[0].profile.email' field must be a valid e-mail."}{ "message": "profiles[0].profile.phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got abc instead."}{ "message": "profiles[0].profile.subscribedAt must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-05-01 instead."}{ "message": "The 'profiles[0].profile.unsubscribeLink' field must be a valid URL."}{ "message": "The '' field is required."}The domain is disabled.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "Domain is disabled. Please reach out to support@releva.ai to enable it."}Request body larger than 800 KB.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "request entity too large"}Unexpected server error.
object
Human-readable error. Several validation errors are joined with a space.
Example
{ "message": "An internal error occurred."}