# Profiles API overview

> The profile calls of the Releva API, one page each (create or update, get, delete, export, register, the subscriber sync and the loyalty link), plus how profiles are identified.

The profiles API creates, reads, updates, deletes and exports the customer profiles of one shop. Every call is under `https://releva.ai/api/v0` and is made from your server with your shop’s Secret Key. For what the fields mean, read [How customer profiles work](https://releva.ai/documentation/learn/profiles/how-profiles-work/).

| Call                                                                                                        | Endpoint                 | Purpose                                                                |
| ----------------------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------- |
| [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/)                   | `POST /profiles`         | Create or update profiles in bulk. Has the Profile object field table. |
| [Get a profile](https://releva.ai/documentation/reference/profiles/get-a-profile/)                                           | `GET /profiles`          | Read one profile.                                                      |
| [Delete a profile](https://releva.ai/documentation/reference/profiles/delete-a-profile/)                                     | `DELETE /profiles`       | Delete a profile and the profiles merged into it.                      |
| [Export a profile’s data](https://releva.ai/documentation/reference/profiles/export-a-profiles-data/)                        | `POST /profiles/exports` | E-mail a full data export for one person.                              |
| [Record a registration](https://releva.ai/documentation/reference/profiles/record-a-registration/)                           | `POST /register`         | Record a sign-up at the moment it happens.                             |
| [Build the subscriber sync endpoint](https://releva.ai/documentation/reference/profiles/build-the-subscriber-sync-endpoint/) | `POST /subscribers/sync` | Let Releva pull your subscriber list from your shop.                   |
| [Get a loyalty link](https://releva.ai/documentation/reference/profiles/get-a-loyalty-link/)                                 | `GET /loyalty-link`      | Get the personal loyalty page link of a profile.                       |

To record a subscribe or an unsubscribe that a shopper made, use the [Consent API](https://releva.ai/documentation/reference/consent/overview/). The cookies the JavaScript SDK sets on your site are listed in the [JavaScript SDK reference](https://releva.ai/documentation/integrations/custom-website/javascript-sdk-reference/#cookies).

## Calls

### Create or update profiles

`POST /api/v0/profiles` creates or updates many profiles in one request, with `subscribedAt` for marketing consent. See [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/).

### Get a profile

`GET /api/v0/profiles` reads one profile by `profileId`, `email` or `phoneNumber`. See [Get a profile](https://releva.ai/documentation/reference/profiles/get-a-profile/).

### Delete a profile

`DELETE /api/v0/profiles` deletes a profile, for example for a right-to-erasure request. See [Delete a profile](https://releva.ai/documentation/reference/profiles/delete-a-profile/).

### Export a profile’s data

`POST /api/v0/profiles/exports` e-mails a download link with the profile, devices, events and attribution of one person. See [Export a profile’s data](https://releva.ai/documentation/reference/profiles/export-a-profiles-data/).

### Record a registration

`POST /api/v0/register` records a sign-up and stamps the registration time. See [Record a registration](https://releva.ai/documentation/reference/profiles/record-a-registration/).

### Start a subscriber sync

`POST /api/v0/subscribers/sync` makes Releva pull your subscriber list from the endpoint your shop exposes. See [Build the subscriber sync endpoint](https://releva.ai/documentation/reference/profiles/build-the-subscriber-sync-endpoint/).

### Get a loyalty link

`GET /api/v0/loyalty-link` returns the personal loyalty page link of a profile, for a “My points” link on your site. See [Get a loyalty link](https://releva.ai/documentation/reference/profiles/get-a-loyalty-link/).

## Identifiers and phone numbers

A profile is found by `id` (your customer id; `profileId` in query strings), `email` (matched ignoring case) or `phoneNumber`. Every write needs at least one; `GET /profiles` and `POST /profiles/exports` need exactly one.

Phone numbers are stored as `+` followed by digits. `POST /profiles`, `GET /profiles` and `POST /register` convert a national number with the shop’s country code (`0888000101` on a Bulgarian shop becomes `+359888000101`). `DELETE /profiles`, `POST /profiles/exports` and `GET /loyalty-link` accept only the international form. In a query string, send `+` as `%2B`.

## Authentication, errors and limits

* Send your shop’s Secret Key as `authorization: Bearer $RELEVA_SECRET_KEY`. Find it 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`. A disabled shop answers `402`.
* HTTPS only. Send JSON with `content-type: application/json`.
* Errors have one shape, `{ "message": "..." }`. Several validation messages are joined with a space.
* Bodies are limited to 800 KB (`413` above that). There are no rate limits on these calls.
* Unknown keys are rejected inside each profile entry of `POST /profiles` and on `GET /profiles`, `DELETE /profiles`, `POST /profiles/exports` and `GET /loyalty-link`. `POST /register` ignores unknown keys, and so does the top level of the `POST /profiles` body. `POST /subscribers/sync` reads no body.
* All calls are under `/api/v0`. Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/).

## Next steps

* [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/): Start with the main write call and its Profile object table.
* [How customer profiles work](https://releva.ai/documentation/learn/profiles/how-profiles-work/): Learn how Releva identifies one person across id, email and phone number.
* [Consent API overview](https://releva.ai/documentation/reference/consent/overview/): Record subscribes and unsubscribes with the calls built for consent.
* [Find a customer profile](https://releva.ai/documentation/guides/profiles/find-a-profile/): Open a profile in the admin to check what your calls stored.