Skip to content

Area: Developers

Profiles API overview

Used byCustom website, Shopify, Partner platforms, Mobile SDKs, React Native

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.

Call Endpoint Purpose
Create or update profiles POST /profiles Create or update profiles in bulk. Has the Profile object field table.
Get a profile GET /profiles Read one profile.
Delete a profile DELETE /profiles Delete a profile and the profiles merged into it.
Export a profile’s data POST /profiles/exports E-mail a full data export for one person.
Record a registration POST /register Record a sign-up at the moment it happens.
Build the subscriber sync endpoint POST /subscribers/sync Let Releva pull your subscriber list from your shop.
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. The cookies the JavaScript SDK sets on your site are listed in the JavaScript SDK reference.

POST /api/v0/profiles creates or updates many profiles in one request, with subscribedAt for marketing consent. See Create or update profiles.

GET /api/v0/profiles reads one profile by profileId, email or phoneNumber. See Get a profile.

DELETE /api/v0/profiles deletes a profile, for example for a right-to-erasure request. See Delete a profile.

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.

POST /api/v0/register records a sign-up and stamps the registration time. See Record a registration.

POST /api/v0/subscribers/sync makes Releva pull your subscriber list from the endpoint your shop exposes. See Build the subscriber sync endpoint.

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.

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.

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