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.
Create or update profiles
Section titled “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.
Get a profile
Section titled “Get a profile”GET /api/v0/profiles reads one profile by profileId, email or phoneNumber. See Get a profile.
Delete a profile
Section titled “Delete a profile”DELETE /api/v0/profiles deletes a profile, for example for a right-to-erasure request. See Delete a profile.
Export a profile’s data
Section titled “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.
Record a registration
Section titled “Record a registration”POST /api/v0/register records a sign-up and stamps the registration time. See Record a registration.
Start a subscriber sync
Section titled “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.
Get a loyalty link
Section titled “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.
Identifiers and phone numbers
Section titled “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
Section titled “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. - Authentication failures answer
400, not401. A disabled shop answers402. - 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 (
413above that). There are no rate limits on these calls. - Unknown keys are rejected inside each profile entry of
POST /profilesand onGET /profiles,DELETE /profiles,POST /profiles/exportsandGET /loyalty-link.POST /registerignores unknown keys, and so does the top level of thePOST /profilesbody.POST /subscribers/syncreads no body. - All calls are under
/api/v0. Changes are listed in the API changelog.