# Get a loyalty link

> GET /api/v0/loyalty-link: get the personal loyalty page link of a profile by email or phone number, from your server, to show a My points link on your own site.

`GET https://releva.ai/api/v0/loyalty-link` returns the personal link to a profile’s loyalty page. The page shows the person’s points and the rewards they can buy with them.

## When to use it

Call it from your server when you want a “My points” link on your own site, for example in the shopper’s account area. You do not need it for messages: Releva’s emails, SMS, Viber and WhatsApp messages insert the same link with the `{{loyaltyLink}}` merge tag. Points are not granted through the API; they come from your loyalty rules under **Data Platform › Loyalty** (see [How loyalty points work](https://releva.ai/documentation/learn/loyalty/how-loyalty-points-work/)).

Treat the link like a password: anyone who has it can see the person’s balance and spend their points. Show it only to the logged-in shopper it belongs to, and never put it in a page other people can see.

## Authentication

Send your shop’s Secret Key as a bearer token, from your server only. Never call this endpoint from a browser or an app.

```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-loyalty-link/#errors)).

## Request

`GET /api/v0/loyalty-link` with exactly one of these query parameters:

| Parameter     | Notes                                                                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`       | Email of an existing profile. Matched ignoring case.                                                                                                                        |
| `phoneNumber` | Phone number of an existing profile, in the international form: `+` and digits, 2 to 32 characters. Send `+` as `%2B`. National numbers are not converted on this endpoint. |

```plaintext
curl -G 'https://releva.ai/api/v0/loyalty-link' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  --data-urlencode 'email=maria@example.com'
```

By phone number:

```plaintext
curl -G 'https://releva.ai/api/v0/loyalty-link' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  --data-urlencode 'phoneNumber=+15555550199'
```

`curl -G` with `--data-urlencode` puts the parameter in the query string and encodes the `+` for you.

## Response

`201 Created` with the link:

```plaintext
{ "link": "https://<loyalty-page-host>/loyalty?token=00000000-0000-4000-8000-000000000000&i=0f1e2d3c4b5a69788796a5b4c3d2e1f0&p=rlv1.EXAMPLE&l=en" }
```

Use the link as it is: never build or change its parameters. Every call returns a new link, and earlier links keep working. Links do not expire.

## 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`  | Neither `email` nor `phoneNumber`         | `At least one of email or phoneNumber is required.`                                                                     |
| `400`  | Both `email` and `phoneNumber`            | `Please provide either an email or phoneNumber, not both.`                                                              |
| `400`  | Bad email                                 | `The 'email' field must be a valid e-mail.`                                                                             |
| `400`  | National phone number                     | `phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got 0888000101 instead.` |
| `400`  | Unknown parameter, for example `id`       | `The object '' contains forbidden keys: 'id'.`                                                                          |
| `402`  | The shop is disabled                      | `Domain is disabled. Please reach out to support@releva.ai to enable it.`                                               |
| `404`  | No profile has this email or phone number | `Profile not found for this email or phone number.`                                                                     |
| `500`  | Unexpected error                          | `An internal error occurred.` Retry later.                                                                              |

## Limits

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

## Next steps

* [Set up your loyalty program](https://releva.ai/documentation/guides/loyalty/set-up-your-loyalty-program/): Create the earn and redeem rules the loyalty page shows.
* [Customize your loyalty page](https://releva.ai/documentation/guides/loyalty/customize-your-loyalty-page/): Change the look and texts of the page the link opens.
* [How loyalty points work](https://releva.ai/documentation/learn/loyalty/how-loyalty-points-work/): Learn how points are earned, expire and are spent.