# How customer profiles work

> What a profile is, how Releva identifies one person across id, email and phone number, the ways profiles get in, and what consent, subscriptions, tags and custom fields mean.

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

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.

## Five ways in

| 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](https://releva.ai/documentation/guides/profiles/add-a-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](https://releva.ai/documentation/reference/profiles/overview/). Whatever the way in, the result lands on the same profile, found by the identifiers above.

## Writes merge, and are immediate

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

## 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](https://releva.ai/documentation/reference/consent/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.

## Deleting a profile

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

## Next steps

* [Find a customer profile](https://releva.ai/documentation/guides/profiles/find-a-profile/): Search for a customer and see what Releva knows about them.
* [Add a customer profile](https://releva.ai/documentation/guides/profiles/add-a-profile/): Create a profile by hand with subscriptions and tags.
* [Edit a customer profile and add tags](https://releva.ai/documentation/guides/profiles/edit-a-profile/): Change a profile’s details, add tags or delete it.
* [Profiles API overview](https://releva.ai/documentation/reference/profiles/overview/): Create and update profiles from your own systems.