Skip to content

Area: Developers

How customer profiles work

Releva keeps one profile per person per shop (domain). Segments, campaigns, workflows, recommendations and the subscription manager all read from it. This page explains how a profile is identified, how it gets there, and what the fields mean, so that the admin, imports and the API give the same result.

A profile is one person, found by three identifiers

Section titled “A profile is one person, found by three identifiers”

A profile has up to three identifiers: id (your customer id; profileId in query strings), email and phoneNumber. Any of them finds the profile; a write with none of them is rejected.

  • Email is matched ignoring case, and the value is trimmed. A profile created without an id gets a generated UUID.
  • Phone numbers are stored in international form, + followed by digits. POST /profiles and POST /register accept a national number and convert it with your shop’s country code, so 0888000101 becomes +359888000101 on a Bulgarian shop. DELETE /profiles, POST /profiles/exports and the admin Phone Number filter accept only the international form.
  • An email address or phone number belongs to one profile per shop. The admin form refuses a save that would move it (Email already exists in another profile.). The API keeps the first owner: a later profile with a different email does not get the phone number.
  • Visitors Releva tracks without an email or phone number are anonymous profiles. When you first open Data Platform › Profiles, the list includes them although Include Anonymous Profiles is off; once you select Go, they appear only with Include Anonymous Profiles on. GET /api/v0/profiles answers 404 for them.
  • When two profiles turn out to be the same person, they are merged. An old profileId then resolves to the surviving profile for reads, writes, exports and deletes.
Method What it does Best for
Shop integration Your platform connector or front-end integration creates profiles when customers register, subscribe or order. Every shop. No manual work.
Add Profile form Creates one profile from Data Platform › Profiles › Add Profile. See Add a customer profile. One or two profiles.
Import Profiles (CSV) Uploads a CSV file from the same page. Options: Skip Existing Profiles (on by default), Overwrite ‘Registered At’ and ‘Subscribed At’ fields and Merge Tags for Existing Profiles. The file is processed in the background; you get an e-mail when it is done. Lists from a previous tool.
POST /api/v0/profiles Creates or updates many profiles in one call, including tags, subscriptions, consent and custom fields. Backfills, CRM syncs, your own integration.
POST /api/v0/register Records a sign-up: creates or updates the profile and stamps the registration time. Your shop’s registration form.
Subscriber Sync API (pull) Releva fetches your subscriber list from a URL you expose, when you select Sync Now in Settings › Messaging or call POST /api/v0/subscribers/sync. Shops that keep the subscriber list elsewhere.

The last three are described in the Profiles API overview. Whatever the way in, the result lands on the same profile, found by the identifiers above.

POST /api/v0/profiles is an upsert: it creates the profile when no identifier matches and otherwise updates it. Fields you leave out keep their value. The write is synchronous; GET /api/v0/profiles returns the new values on the next request. The admin list and profile page read from an analytics store that catches up a few seconds later, which is why a tag you just saved can be missing until you reload.

Some fields are deltas, some replace:

Field Behaviour
addTags, removeTags Add to or remove from the tag list.
addSubscriptions, removeSubscriptions Add to or remove from the subscription list.
addCustom Merges custom fields by key: keys you send replace their values, other keys stay.
subscriptions Replaces the whole list. Send [] to clear it; do not send null. Omit the field to keep it.
custom Replaces all custom fields. Omit the field to keep them.
registeredAt, birthday, names, location, unsubscribeLink Overwrite the stored value.

POST /register is different: its tags field replaces the tag list, and every call stamps registeredAt with the current time.

Section titled “Consent, subscriptions and tags are three different things”
  • Consent to marketing is the subscribedAt timestamp. A profile with a subscribedAt and no later unsubscribedAt is Subscribed; the profile page shows it under Subscription status › Marketing messages. To unsubscribe someone, call Unsubscribe a customer; it stamps unsubscribedAt with the current time and clears unsubscribeLink. A subscribedAt that is older than the last opt-out is ignored, so a stale import cannot re-subscribe someone who opted out. Web push and app push consent are separate and per browser or device.
  • Subscriptions are the topics the customer opted in to, for example marketing or weeklyNewsletter. They apply on every channel. Adding a user-visible subscription to a profile with no consent state can subscribe it, and removing the last one can unsubscribe it, so change consent with subscribedAt or the Consent API, not with the lists. When a write subscribes a profile without naming any subscriptions, the shop’s default subscriptions are added.
  • Tags are free-text labels for your own use: import batches, loyalty tiers, campaign sources. They have no effect on sending. Segments can filter on them.
  • Custom fields are typed values (string, numeric, date) under a key you choose. New keys are registered on the shop, so they appear as conditions in segments.
  • Consent level (consent) is the legal basis: legitimateInterest (default), privacyPolicy, or cookiesPolicy / mandatoryCookies. It is never lowered by a later write, and unknown values are ignored.

Profile writes also record events on the profile’s timeline: register and subscribe carry the timestamps you sent, unsubscribe and subscriptionsChanged carry the time of the call.

Delete on the profile page and DELETE /api/v0/profiles do the same thing: they remove the profile and every merged profile and anonymous id in its identity cluster, at once. There is no undo. The API answers 202 even when nothing matched, so check with GET /api/v0/profiles if you need confirmation. A customer who keeps browsing with the same cookies gets a new anonymous profile; ask them to clear the shop’s cookies if that matters.

For a copy of everything Releva holds about one person (a data subject access request), use POST /api/v0/profiles/exports. The export is e-mailed as a download link.