Skip to content

Area: Developers

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.

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.

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_KEY

Find 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).

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"] }]
}
}
}
]
}'

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.

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.

  • To subscribe a user, send subscribedAt with the date they subscribed, "subscribedAtChanged": true on the entry, and their unsubscribeLink if 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, subscribedAtChanged and unsubscribeLink. 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 send subscribedAt: null in 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.

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 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.
  • 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.

See also