Create or update profiles
POST https://releva.ai/api/v0/profiles sends bulk profile updates to Releva. Any profile that does not exist in Releva is created. For how Releva identifies a person across id, email and phone number, read How customer profiles work.
When to use it
Section titled “When to use it”This API is intended for backfill and bulk sync from your server:
- Bootstrap Releva with your existing profile data when you start.
- Custom integrations where you change profile properties based on internal events of your system, and the general-purpose push method of the front-end integration does not work for your use case.
It is not meant to be called for every sign-up: for a sign-up without a subscribe date, use Record a registration. To record that a shopper subscribed or unsubscribed through a form, use the Consent API, which is made for consent decisions.
You can attach tags and custom fields to profiles. Custom fields can be used to build segments and conditions in workflows.
To change a few fields of an existing profile and keep everything else, send only those fields, use addCustom instead of custom, and use addTags and removeTags for tags. See Update some fields and keep the rest.
Authentication
Section titled “Authentication”Send your shop’s Secret Key as a bearer token. Call this endpoint from your server only: the key must never reach a browser or an app.
authorization: Bearer $RELEVA_SECRET_KEYFind the key in the admin under Settings › Shop & Integration; see Find your Access Token and Secret Key. Authentication failures answer 400, not 401 (see Errors).
Request
Section titled “Request”POST /api/v0/profiles with content-type: application/json.
| Field | Type | Required | Notes |
|---|---|---|---|
profiles |
array | yes | List of profiles to create or update. At least 1 entry. Each entry is { "profile": { ... } }. |
profiles[].profile |
object | yes | Profile attributes. See Profile object. |
profiles[].subscribedAtChanged |
boolean | recommended with subscribedAt |
Send "subscribedAtChanged": true whenever you send subscribedAt. |
The example sends two profiles. The first is identified by your customer id and is subscribed. The second is identified by email only and is not subscribed, so it has no subscribedAt, subscribedAtChanged or unsubscribeLink. Both send custom, which replaces all custom fields of the profile. To change only some keys and keep the others, use addCustom: see Update some fields and keep the rest.
curl -X POST 'https://releva.ai/api/v0/profiles' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "profiles": [ { "profile": { "id": "DEMO-1001", "email": "maria@example.com", "firstName": "Maria", "lastName": "Example", "phoneNumber": "+15555550199", "registeredAt": "2026-01-15T10:00:00Z", "subscribedAt": "2026-01-15T10:05:00Z", "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-1001", "location": { "lat": 42.6977, "lon": 23.3219 }, "addTags": ["vip", "acceptingMessages"], "custom": { "string": [ { "key": "loyaltyTier", "values": ["gold"] }, { "key": "ageGroup", "values": ["30-40"] } ], "numeric": [{ "key": "ordersCount", "values": [3] }] }, "subscriptions": ["weeklyNewsletter", "promo"], "consent": "privacyPolicy" }, "subscribedAtChanged": true }, { "profile": { "email": "alex@example.com", "firstName": "Alex", "lastName": "Example", "registeredAt": "2026-02-03T08:30:00Z", "birthday": "1990-05-12", "addTags": ["acceptingMessages"], "custom": { "string": [{ "key": "ageGroup", "values": ["30-40"] }] } } } ] }'Profile object
Section titled “Profile object”Send email or phoneNumber with every profile, plus your customer id when you have one. An entry with only id updates an existing profile with that id; it does not create a profile you can read back. The object is validated strictly: a key that is not in this table is rejected.
| Field | Type | Notes |
|---|---|---|
id |
string | Your customer id. It must uniquely identify each user in your database and match the profile.id you send in the front-end integration. Other profile calls take it as profileId. |
email |
string | The user’s email address. Send it unless you send phoneNumber. Matched ignoring case. |
phoneNumber |
string | The user’s phone number. Send it unless you send email. It must start with + followed by digits only, for example +49875345976. |
firstName, lastName |
string | |
registeredAt |
string | When the user created their account. ISO-8601 with seconds and a time zone offset, for example 2026-01-15T10:00:00Z. Replaces the stored value. |
subscribedAt |
string | When the user subscribed to your marketing. Same format as registeredAt. If you do not send this field, the subscription status does not change. Send it only for a subscribed user, together with "subscribedAtChanged": true. Do not send null. See Subscription data. |
birthday |
string | The user’s birthday, a date without time: YYYY-MM-DD, for example 1989-09-16. A time part is rejected. |
unsubscribeLink |
string | Your own unsubscribe page for this user, an http or https URL. Leave it out if the profile is not subscribed. |
custom |
object | Custom fields: string, numeric and date lists of { "key": "...", "values": [...] }. Can be used to build segments and conditions in workflows. Replaces all custom fields of the profile. date values are YYYY-MM-DD or ISO-8601 with seconds and an offset. |
addCustom |
object | Same shape as custom. Replaces the values of the keys it names and keeps the other keys. |
addTags |
array of strings | Tags to add. Tags the profile already has stay. |
removeTags |
array of strings | Tags to remove. |
subscriptions |
array of strings | The topics the user subscribed to, for segmenting when you have several subscriptions. Replaces the profile’s subscription list. To clear existing subscriptions, send an empty array []. Do not send null. |
addSubscriptions |
array of strings | Subscriptions to add to the list. The others stay. |
removeSubscriptions |
array of strings | Subscriptions to remove from the list. The others stay. |
location |
object | The user’s location as coordinates in decimal notation: { "lat": <number>, "lon": <number> }, for example 39.123 and 23.234. Both are required when you send location. |
consent |
string | One of legitimateInterest, privacyPolicy, mandatoryCookies or cookiesPolicy. legitimateInterest is the default: every user has it until you send another value. A stored consent is never lowered: cookiesPolicy and mandatoryCookies rank above privacyPolicy, which ranks above legitimateInterest. Any other value is ignored. |
There is no tags field here: use addTags and removeTags.
National phone numbers are converted with your shop’s country code, for example 0888000101 on a Bulgarian shop becomes +359888000101. Send the international form anyway, so the number does not depend on the shop’s settings.
Update some fields and keep the rest
Section titled “Update some fields and keep the rest”Fields you leave out keep their stored value. Two fields replace everything stored, so avoid them for partial updates: custom replaces all custom fields and subscriptions replaces the whole subscription list. Use addCustom, addTags/removeTags and addSubscriptions/removeSubscriptions instead. They change only what they name.
The example updates one customer’s loyalty tier and order count, adds the tag vip and removes the tag newCustomer. Name, subscription status, other tags and other custom fields stay as they are.
curl -X POST 'https://releva.ai/api/v0/profiles' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "profiles": [ { "profile": { "id": "DEMO-1001", "email": "maria@example.com", "addTags": ["vip"], "removeTags": ["newCustomer"], "addCustom": { "string": [{ "key": "loyaltyTier", "values": ["gold"] }], "numeric": [{ "key": "ordersCount", "values": [4] }] } } } ] }'| You send | Stored custom fields before | Stored custom fields after |
|---|---|---|
"addCustom": { "string": [{ "key": "loyaltyTier", "values": ["gold"] }] } |
loyaltyTier: silver, ageGroup: 30-40 |
loyaltyTier: gold, ageGroup: 30-40 |
"custom": { "string": [{ "key": "loyaltyTier", "values": ["gold"] }] } |
loyaltyTier: silver, ageGroup: 30-40 |
loyaltyTier: gold only |
The front-end push takes addCustom the same way, but not tags. See the profile object of the JavaScript SDK.
Subscription data
Section titled “Subscription data”- To subscribe a user, send
subscribedAtwith the date they subscribed,"subscribedAtChanged": trueon the entry, and theirunsubscribeLinkif you manage unsubscribes yourself. If the user’s last unsubscribe is at the same time or later than the date you send, they stay unsubscribed, so an old date never undoes a newer opt-out. - For a user who is not subscribed, leave out
subscribedAt,subscribedAtChangedandunsubscribeLink. The subscription status does not change. Leaving the fields out never unsubscribes: a user who is subscribed in Releva stays subscribed. - To unsubscribe a user, call Unsubscribe a customer (
POST /api/v0/unsubscribe). Do not sendsubscribedAt: nullin this API. For a bulk load, such as a backfill that includes users who opted out, call Unsubscribe a customer for each user who opted out.
A write that subscribes a profile and names no subscriptions also gives it the shop’s User Visible Subscriptions. You edit that list under Settings › Messaging, General tab.
Response
Section titled “Response”202 Accepted with an empty body {}. Changes are available according to our SLA; in practice, Get a profile usually shows the change on the next request.
An entry with none of id, email or phoneNumber is skipped and the other entries are written. The request fails with 400 only when no entry has an identifier.
Errors
Section titled “Errors”Errors have one shape, { "message": "..." }. When several fields fail, the messages are joined with a space.
| Status | When | Message |
|---|---|---|
400 |
No authorization header |
Authorization header is missing. |
400 |
The header is not Bearer <token> |
Authorization header is malformed. It should look like `Bearer <string>`. |
400 |
The token is not a UUID | Authorization header contains an invalid Bearer token. |
400 |
No shop has this key | Domain with the provided secret key cannot be found. |
400 |
Plain HTTP instead of HTTPS | We do not support non-HTTPS requests. |
400 |
No profiles key |
The 'profiles' field is required. |
400 |
Empty profiles array |
The 'profiles' field must contain at least 1 items. |
400 |
No entry has an identifier | profiles[0].profile: at least one of (id, email, phoneNumber) is required |
400 |
Unknown key, for example tags |
The object 'profiles[0].profile' contains forbidden keys: 'tags'. |
400 |
Bad email | The 'profiles[0].profile.email' field must be a valid e-mail. |
400 |
subscribedAt or registeredAt without a time, for example 2026-05-01 |
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. |
400 |
birthday not YYYY-MM-DD |
profiles[0].profile.birthday must be a valid ISO-8601 date such as 2020-01-01 with optional time ... Got 17/05/1990 instead. (despite the text, only YYYY-MM-DD is accepted) |
400 |
unsubscribeLink that is not an http or https URL |
The 'profiles[0].profile.unsubscribeLink' field must be a valid URL. |
400 |
Phone number that is not + and digits after conversion |
profiles[0].profile.phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got abc instead. |
402 |
The shop is disabled | Domain is disabled. Please reach out to support@releva.ai to enable it. |
413 |
Body larger than 800 KB | request entity too large |
500 |
Unexpected error | An internal error occurred. Retry later. |
Limits
Section titled “Limits”- Body size: 800 KB per request. There is no other limit on the number of profiles in one request.
- Rate limits: none on this endpoint.
- Entries in one request are written in parallel. Do not put two entries for the same person in one request.
- Unknown keys are rejected, so add a new field only after it appears in this reference.