Get a profile
GET https://releva.ai/api/v0/profiles returns what Releva holds about one person: identifiers, names, consent, tags, subscriptions and custom fields.
When to use it
Section titled “When to use it”Call it from your server when your system needs to read what Releva currently holds about a user, for example their subscription status, tags or custom fields, to keep it in sync. You can also use it to confirm a write. For a full copy of everything about a person, including their events, use Export a profile’s data.
Authentication
Section titled “Authentication”Send your shop’s Secret Key as a bearer token, from your server only:
authorization: Bearer $RELEVA_SECRET_KEYFind the key under Settings › Shop & Integration; see Find your Access Token and Secret Key. Authentication failures answer 400, not 401 (see Errors).
Request
Section titled “Request”GET /api/v0/profiles with exactly one of these query parameters:
| Parameter | Notes |
|---|---|
profileId |
Your customer id (the id you sent). A profile that was merged into another one answers with the profile it was merged into. |
email |
Matched ignoring case. |
phoneNumber |
In the form you sent it. A national number is converted with your shop’s country code. Send + as %2B. |
# By emailcurl 'https://releva.ai/api/v0/profiles?email=maria@example.com' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json'
# By your customer idcurl 'https://releva.ai/api/v0/profiles?profileId=DEMO-1001' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json'
# By phone number: send + as %2Bcurl 'https://releva.ai/api/v0/profiles?phoneNumber=%2B15555550199' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json'Response
Section titled “Response”200 with the profile:
{ "profile": { "id": "DEMO-1001", "email": "maria@example.com", "phoneNumber": "+15555550199", "firstName": "Maria", "lastName": "Example", "registeredAt": "2026-01-15T10:00:00.000Z", "subscribedAt": "2026-01-15T10:05:00.000Z", "unsubscribedAt": null, "birthday": "1990-05-12", "tags": ["vip"], "subscriptions": ["marketing"], "custom": { "string": [{ "key": "loyaltyTier", "values": ["gold"] }], "numeric": [{ "key": "ordersCount", "values": [3] }] }, "location": null, "consent": "privacyPolicy", "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-1001" }}Every key is always present. A value the profile does not have is null; tags and subscriptions are always arrays, empty when there are none. Dates come back in UTC with milliseconds.
| Field | Type | Notes |
|---|---|---|
id |
string | The profile id. Use it as profileId in the other profile calls. |
email, phoneNumber |
string or null |
phoneNumber is in the international form, + and digits. |
firstName, lastName |
string or null |
|
registeredAt |
string or null |
When the person registered. |
subscribedAt |
string or null |
When the person subscribed to marketing; null when not subscribed. |
unsubscribedAt |
string or null |
When the person last unsubscribed; null while subscribed. |
birthday |
string or null |
YYYY-MM-DD. |
tags |
array of strings | |
subscriptions |
array of strings | |
custom |
object or null |
Custom fields in the shape you send them: string, numeric and date lists of { key, values }. |
location |
object or null |
{ "lat": <number>, "lon": <number> }. |
consent |
string or null |
The highest consent recorded for the person. |
unsubscribeLink |
string or null |
Your own unsubscribe link for the person, if you sent one. |
Errors
Section titled “Errors”Errors have one shape, { "message": "..." }.
| 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 |
No identifier, or more than one | Exactly one of (profileId, phoneNumber, email) is required. |
400 |
Unknown parameter, for example foo |
The object '' contains forbidden keys: 'foo'. |
400 |
Bad email | The 'email' field must be a valid e-mail. |
400 |
sendToEmail in the query (the old export form) |
sendToEmail is not supported on GET /api/v0/profiles. To request a data export, POST /api/v0/profiles/exports with a JSON body. |
402 |
The shop is disabled | Domain is disabled. Please reach out to support@releva.ai to enable it. |
404 |
No profile matches, or the match is an anonymous profile (no email and no phone number) | Profile not found. |
500 |
Unexpected error | An internal error occurred. Retry later. |
Limits
Section titled “Limits”- One profile per request.
- Rate limits: none on this endpoint.