View Categories

Get Profile Data

2 min read

0:00 3:30
Table of Contents

The Get Profile API returns a user’s profile synchronously, given their email, phone number or profileId.

Do I need to call it? #

Use it when your system needs to read what Releva currently holds about a user — for example their subscription status, tags or custom fields — in order to keep it in sync. If you need a complete copy of everything we hold about a user (devices, events, attribution) for a GDPR access request, use Export Profile Data instead.

Request Parameters #

You may perform requests to the API using the following curl equivalent:

curl -XGET -H 'Authorization: Bearer <secretKey>' 'https://releva.ai/api/v0/profiles?email=<email>'
curl -XGET -H 'Authorization: Bearer <secretKey>' 'https://releva.ai/api/v0/profiles?profileId=<profileId>'
curl -XGET -H 'Authorization: Bearer <secretKey>' 'https://releva.ai/api/v0/profiles?phoneNumber=%2B359888123456'

Request URL Parameters #

FieldTypeDescription
emailString (Optional)User’s email address. Matching is case-insensitive.
profileIdString (Optional)User’s profile id.
phoneNumberString (Optional)User’s phone number, in the same form you sent it when creating the profile (international or national). URL-encode the leading + as %2B.

Note that email, profileId and phoneNumber are optional but we need exactly one of them. Any other parameter is rejected with HTTP status 400.

Response Format #

A successful response will return HTTP Status 200 with the following structure:

{
  "profile": {
    "id": "5f0c3a7e-2b1d-4c8e-9a6f-1d2e3f4a5b6c",
    "email": "jane.doe@example.com",
    "phoneNumber": "+359888123456",
    "firstName": "Jane",
    "lastName": "Doe",
    "registeredAt": "2025-11-02T10:15:00.000Z",
    "subscribedAt": "2025-11-02T10:15:00.000Z",
    "unsubscribedAt": null,
    "birthday": "1990-05-17",
    "tags": ["vip"],
    "subscriptions": ["marketing"],
    "custom": {
      "string": [{ "key": "loyaltyTier", "values": ["gold"] }]
    },
    "location": { "lat": 42.6977, "lon": 23.3219 },
    "consent": null,
    "unsubscribeLink": null
  }
}

The Profile Object #

FieldTypeDescription
idStringThe profile id. Use it as profileId in other profile APIs.
emailString or nullUser’s email address.
phoneNumberString or nullUser’s phone number in international format.
firstNameString or nullUser’s first name.
lastNameString or nullUser’s last name.
registeredAtString or nullISO-8601 date and time the user registered.
subscribedAtString or nullISO-8601 date and time the user subscribed to marketing communication; null if not subscribed.
unsubscribedAtString or nullISO-8601 date and time the user last unsubscribed.
birthdayString or nullUser’s birthday as an ISO-8601 date (YYYY-MM-DD).
tagsArray of StringTags assigned to the user. Empty array if none.
subscriptionsArray of StringSubscriptions the user holds. Empty array if none.
customObject or nullCustom fields, in the same structure as in Create/Update Profile.
locationObject or nullUser’s location as { "lat": Number, "lon": Number }.
consentString or nullConsent value last set for the user.
unsubscribeLinkString or nullYour own unsubscribe link for this user, if you provided one.

Every field is always present; a value the profile does not have is returned as null (or an empty array for tags and subscriptions).

If the profile you ask for by profileId has since been merged into another profile, the surviving profile is returned, so the id in the response can differ from the one you requested.

If no profile matches, the response is HTTP status 404. Only identified profiles — those with an email or phone number — can be looked up; an anonymous visitor’s profile returns 404.

An error response will return a HTTP 4xx or 5xx status code and have the following structure:

{
  "message": "A description of the error and how to fix it, if it's a client error."
}
What are your Feelings