# Get a profile

> GET /api/v0/profiles: read one customer profile by id, email or phone number from your server, with every field of the response.

`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

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](https://releva.ai/documentation/reference/profiles/export-a-profiles-data/).

## Authentication

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

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

Find the key under **Settings › Shop & Integration**; see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/). Authentication failures answer `400`, not `401` (see [Errors](https://releva.ai/documentation/reference/profiles/get-a-profile/#errors)).

## 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`.                     |

```plaintext
# 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'
```

## Response

`200` with the profile:

```plaintext
{
  "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

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

* One profile per request.
* Rate limits: none on this endpoint.

## Next steps

* [Create or update profiles](https://releva.ai/documentation/reference/profiles/create-or-update-profiles/): Change the fields you read, with the full Profile object table.
* [Export a profile’s data](https://releva.ai/documentation/reference/profiles/export-a-profiles-data/): Get everything about one person, including events, for a data access request.
* [Find a customer profile](https://releva.ai/documentation/guides/profiles/find-a-profile/): Open the same profile in the admin.