# Create or update profiles

> POST /api/v0/profiles: create or update customer profiles in bulk from your server (backfill and custom integrations), with the Profile object field table and how to send subscription data.

`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](https://releva.ai/documentation/learn/profiles/how-profiles-work/).

## 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](https://releva.ai/documentation/integrations/custom-website/connect-your-custom-website/) 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](https://releva.ai/documentation/reference/profiles/record-a-registration/). To record that a shopper subscribed or unsubscribed through a form, use the [Consent API](https://releva.ai/documentation/reference/consent/overview/), which is made for consent decisions.

> **Profile writes can start triggered workflows**
>
> A write that subscribes or registers a profile records `subscribe` and `register` events on the profile. These events can start triggered workflows, such as a welcome flow. Check your active workflows before a large backfill.

You can attach tags and custom fields to profiles. Custom fields can be used to build segments and conditions in workflows.

> **Keep custom fields in sync with the Push API**
>
> If you add custom fields with `custom` in this API, pass the same custom fields when you push profile data with the front-end Push API, or you overwrite them. To change only some keys, send them in `addCustom`, which keeps the keys you do not name.

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](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/#update-some-fields-and-keep-the-rest).

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

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

Find the key in the admin under **Settings › Shop & Integration**; see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/). Authentication failures answer `400`, not `401` (see [Errors](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/#errors)).

## 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](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/#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](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/#update-some-fields-and-keep-the-rest).

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

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](https://releva.ai/documentation/integrations/custom-website/connect-your-custom-website/). 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](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/#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

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.

```plaintext
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](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/#profile).

### Subscription data

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

> **Subscription lists can change marketing consent**
>
> `subscriptions`, `addSubscriptions` and `removeSubscriptions` are for the subscription list only. When one of them names a **User Visible Subscription**, it can change the marketing status as well: adding one can subscribe a profile that never answered, and removing the last one can unsubscribe it. Do not use them to subscribe or unsubscribe. Use `subscribedAt` as above, or the [Consent API](https://releva.ai/documentation/reference/consent/overview/).

## Response

`202 Accepted` with an empty body `{}`. Changes are available according to our SLA; in practice, [Get a profile](https://releva.ai/documentation/reference/profiles/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

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

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

## Next steps

* [Get a profile](https://releva.ai/documentation/reference/profiles/get-a-profile/): Read the profile back to confirm what your write stored.
* [Unsubscribe a customer](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/): Unsubscribe a user from your marketing.
* [Consent API overview](https://releva.ai/documentation/reference/consent/overview/): Record a subscribe or unsubscribe that the shopper made, with the calls built for consent.
* [How customer profiles work](https://releva.ai/documentation/learn/profiles/how-profiles-work/): Learn how one person is matched across id, email and phone number.
* [Build the subscriber sync endpoint](https://releva.ai/documentation/reference/profiles/build-the-subscriber-sync-endpoint/): Let Releva pull your subscriber list instead of pushing it.