Skip to content

Area: Developers

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.

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.

Send your shop’s Secret Key as a bearer token, from your server only:

authorization: Bearer $RELEVA_SECRET_KEY

Find the key under Settings › Shop & Integration; see Find your Access Token and Secret Key. Authentication failures answer 400, not 401 (see Errors).

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 email
curl 'https://releva.ai/api/v0/profiles?email=maria@example.com' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json'
# By your customer id
curl '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 %2B
curl 'https://releva.ai/api/v0/profiles?phoneNumber=%2B15555550199' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json'

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 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.
  • One profile per request.
  • Rate limits: none on this endpoint.