# Build the subscriber sync endpoint

> The endpoint your shop exposes so Releva can pull your subscriber list: request, paging, the subscriber fields and subscribedAt semantics, plus POST /api/v0/subscribers/sync to start a pull.

With a subscriber sync, Releva pulls your subscriber list from an endpoint on your shop and updates its profiles from it. You build the endpoint; Releva calls it when you start a sync.

## When to use it

Build it when your shop collects marketing consent into a database you own and Releva should follow it, or when you do not have a single unsubscribe page for all users and each subscriber gets a unique unsubscribe link. That is the **External** way of managing subscriptions. In other cases, or for a one-off load, prepare a CSV file with your subscribers and import it instead (see [Import profiles from a CSV file](https://releva.ai/documentation/guides/profiles/import-profiles-from-a-csv-file/)). To push changes as they happen, use [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/).

## Before you start

1. In the admin, open **Settings › Messaging** and the **General** tab.
2. Under **Subscription Management**, select **External**.
3. Enter your endpoint’s URL in **Subscriber Sync API**.
4. Select **Save**.

The **Subscriber Sync API** field appears only in **External** mode.

## Start a sync

A sync runs only when you start it. There is no schedule. Start it either way:

* Select **Sync Now** next to **Subscriber Sync API** in the admin.
* Call `POST https://releva.ai/api/v0/subscribers/sync` from your server. No body.

```plaintext
curl -X POST 'https://releva.ai/api/v0/subscribers/sync' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json'
```

The call answers `202 Accepted` with the body `{}` and the pull runs in the background. A call while a sync is already queued adds nothing. If the shop has no **Subscriber Sync API** URL, the call still answers `202` and nothing is pulled. Only the authentication errors apply: `400` for a missing, malformed or unknown key and `402` for a disabled shop (the messages are in [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/#errors)).

## Request Releva sends

Releva calls your URL with `GET` and these headers. It may also add HTTP message signature headers (`Signature-Agent`, `Signature-Input`, `Signature`), which you can ignore.

| Header                | Value                                                       |
| --------------------- | ----------------------------------------------------------- |
| `content-type`        | `application/json`                                          |
| `authorization`       | `Bearer <your Secret Key>`                                  |
| `x-rlv-authorization` | The same value again, for servers that drop `authorization` |

Check the key before you answer: only Releva and you know it.

The first request is `GET <your URL>?page=1`. What comes next depends on your response:

* With `pageCount`, Releva asks for `page=2`, `page=3` and so on, and stops after `page` reaches `pageCount`.
* With `nextCursor`, Releva sends it back as `&cursor=<value>` and stops when `nextCursor` is `null` or empty.

Return `pageCount` or `nextCursor` in every response. Without either one, Releva does not stop paging.

## Response your endpoint returns

Status `200` with JSON:

```plaintext
{
  "subscribers": [
    {
      "email": "maria@example.com",
      "subscribedAt": "2026-01-15T10:05:00Z",
      "subscriptions": ["marketing"],
      "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-1001"
    },
    {
      "phoneNumber": "+15555550199",
      "subscribedAt": null
    }
  ],
  "pageCount": 3
}
```

| Field         | Type             | Notes                                                                      |
| ------------- | ---------------- | -------------------------------------------------------------------------- |
| `subscribers` | array            | Required in every response, empty when there are none.                     |
| `pageCount`   | number           | Page-based paging: the number of pages.                                    |
| `nextCursor`  | string or `null` | Cursor-based paging: the cursor of the next page, `null` on the last page. |

Each subscriber updates the profile with the same email or phone number, or creates one:

| Field                   | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                 | string           | Identifies the person. Send `email` or `phoneNumber`.                                                                                                                                                                                                                                                                                                                |
| `phoneNumber`           | string           | International form, `+` and digits. It is not converted.                                                                                                                                                                                                                                                                                                             |
| `firstName`, `lastName` | string           |                                                                                                                                                                                                                                                                                                                                                                      |
| `subscribedAt`          | string or `null` | See the next section. Use ISO-8601 with seconds and an offset, for example `2026-01-15T10:05:00Z`.                                                                                                                                                                                                                                                                   |
| `subscriptions`         | array of strings | **Replaces** the profile’s subscription list.                                                                                                                                                                                                                                                                                                                        |
| `unsubscribeLink`       | string           | Your unsubscribe page for this person. Send it only for a subscribed person. If you leave it out, Releva uses the **Email Unsubscribe URL** from **Settings › Messaging**. If that setting is empty, a subscriber without their own link receives no marketing emails (see [External mode](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/#external-mode)). |
| `consent`               | string           | `legitimateInterest`, `privacyPolicy`, `mandatoryCookies` or `cookiesPolicy`. A stored consent is never lowered.                                                                                                                                                                                                                                                     |

The values are not validated as strictly as in the profile API, so keep to these fields and types.

### subscribedAt

The date and time when this subscriber gave their consent, or `null` if they are not subscribed.

This applies to the sync response only. In [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/), do not send `null`; call [Unsubscribe a customer](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/).

## Limits

* Page size: return 20 to 50 subscribers per page. Releva does not enforce a limit, but small pages keep each request fast.
* Rate limits: none on `POST /api/v0/subscribers/sync`.

## Next steps

* [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/): Push single changes as they happen, between syncs.
* [Consent API overview](https://releva.ai/documentation/reference/consent/overview/): Record subscribes and unsubscribes the moment the shopper makes them.
* [Import profiles from a CSV file](https://releva.ai/documentation/guides/profiles/import-profiles-from-a-csv-file/): Load a list once without building an endpoint.