# Surveys and NPS API

> The three public endpoints behind Releva's hosted survey page and the NPS widget, the nps object in the page push, the SDK functions, limits and every error message, with a working request for each.

Surveys and NPS surveys are configured in the admin ([Create a survey](https://releva.ai/documentation/guides/surveys/create-a-survey/), [Create an NPS survey](https://releva.ai/documentation/guides/surveys/create-an-nps-survey/)). Three public endpoints under `https://releva.ai/api/v0` serve the respondent side. Releva’s own survey page and the JavaScript SDK call them for you; you need them only if you render surveys or the NPS widget in your own front end or mobile app.

| Endpoint                            | Called by                       | Purpose                                                                 |
| ----------------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
| `GET /surveys/{token}`              | the hosted survey page          | Load a survey’s definition and whether this respondent already answered |
| `POST /surveys/{token}/submissions` | the hosted survey page          | Submit the answers                                                      |
| `POST /nps/{token}/submissions`     | the SDK NPS widget, mobile SDKs | Submit an NPS score and comment                                         |

The NPS survey itself reaches the page inside the normal personalization push (`POST /push/{accessToken}`, key `nps`), and the widget reports impressions, skips and dismissals through `POST /push/events/{accessToken}`. Both calls are documented in the [Events API overview](https://releva.ai/documentation/reference/events/overview/); this page covers only their NPS parts. For the behaviour behind all of this, read [How surveys and NPS work](https://releva.ai/documentation/learn/surveys/how-surveys-and-nps-work/).

## Authentication

None of the three endpoints takes the secret key or the access token. The **survey token** or **NPS token** in the path is the only credential: a UUID that identifies one survey of one shop. It is in every survey link (`token=`), in the merge tag `{{surveyLink '<token>'}}`, and, for NPS, in `nps.token` of the push response.

Who answered is decided per request:

* **Survey, personal link**: the link’s `iv` and `profileId` query values (the survey page sends `profileId` as `encryptedProfileId`) decrypt to the recipient’s profile. A survey without **Public link (QR code)** requires them.
* **Survey, public link**: no identity is needed. The first `GET` returns `identity.anonymousId`; send it back on the submission and on later opens so they land on one profile. A survey with the public link on ignores personal-link values.
* **NPS**: `profileId` (the `rlv_u` cookie) or, when it is blank, `deviceId`.

## Request format

* Send JSON with `content-type: application/json`. The NPS endpoint also accepts `application/x-www-form-urlencoded` with one field, `formPayload`, holding `base64(encodeURIComponent(JSON.stringify(body)))`; that is what the SDK sends. The survey endpoints read JSON only.
* Bodies are limited to **800 KB** for JSON. Larger bodies answer `413 {"message":"request entity too large"}`. File-upload and signature answers are base64 strings inside `data`, so keep uploads small.
* CORS is open: the endpoints can be called from any origin in the browser.
* There are no rate limits.

## Responses and errors

Successful submissions answer **`202 Accepted`** with `{}`. The survey `GET` answers `200` with the survey.

Errors have one shape, `{"message": "..."}`. When several fields fail validation, the messages are joined with a space.

| Status | When                                                                                                                               |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Validation failed, the personal link is broken, or the token is unknown                                                            |
| `402`  | The shop is switched off, or (survey `GET` only) value delivery is paused because usage exceeded the plan                          |
| `403`  | The survey has no public link and the request carries no personal link                                                             |
| `404`  | The NPS survey exists but is a **Draft** or **Inactive**                                                                           |
| `413`  | Body larger than 800 KB                                                                                                            |
| `500`  | Unexpected error, `{"message":"An internal error occurred."}`. A token that is not a UUID currently answers this instead of `400`. |

## Endpoints

### Open a survey

`GET /api/v0/surveys/{token}`

Query parameters: `iv` and `encryptedProfileId` (together, from a personal link), `anonymousId` (from an earlier open of a public survey), `linkToken` (accepted, not used). Every call records a `surveyOpen` event, which the admin counts as an **Open**.

```plaintext
curl 'https://releva.ai/api/v0/surveys/7c3e1f20-6a4b-4c8d-9e0f-1a2b3c4d5e6f' \
  -H 'content-type: application/json'
```

Response `200` for a survey with a public link, first open:

```plaintext
{
  "survey": {
    "config": {
      "title": "Tell us about your visit",
      "pages": [
        {
          "name": "page1",
          "elements": [
            { "name": "satisfaction", "type": "rating", "title": "How satisfied are you?", "rateMin": 1, "rateMax": 5, "isRequired": true },
            { "name": "reason", "type": "radiogroup", "title": "What mattered most?", "choices": ["Price", "Delivery", "Product quality"] },
            { "name": "improve", "type": "comment", "title": "What could we do better?" },
            { "name": "email", "type": "text", "title": "Your e-mail", "inputType": "email" }
          ]
        }
      ]
    },
    "theme": {}
  },
  "submitted": false,
  "identity": { "anonymousId": "<uuid>.<signature>" }
}
```

| Field                  | Meaning                                                                                                                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `survey.config`        | The SurveyJS JSON saved in the admin designer. `cookieName: "rlv_survey_submitted"` is present when **Allowed Submissions** is **Once per link**; the survey page sets that cookie to `true` when `submitted` is `true`, so SurveyJS shows the survey as completed. |
| `survey.theme`         | The SurveyJS theme JSON, `{}` when none.                                                                                                                                                                                                                            |
| `submitted`            | `true` when this profile already submitted this survey (state per survey and profile, not per link). Always `false` on the call that mints an identity.                                                                                                             |
| `identity.anonymousId` | Only on public surveys, and only when a new identity was minted. Send it back as `anonymousId`.                                                                                                                                                                     |

| Cause                                                               | Status | Message                                                                                                                                                |
| ------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Survey without public link, no personal link                        | `403`  | `This survey can only be opened through a personal link.`                                                                                              |
| `encryptedProfileId` without `iv`, or a value that does not decrypt | `400`  | `Invalid profileId!`                                                                                                                                   |
| Unknown token                                                       | `400`  | `Survey with token 00000000-0000-4000-8000-000000000000 cannot be found.`                                                                              |
| Shop switched off                                                   | `402`  | `Shop is disabled. Please reach out to support@releva.ai to enable it.`                                                                                |
| Value delivery paused                                               | `402`  | `Value delivery is paused for this domain because usage exceeded the plan limit. Please raise your limit or reach out to support@releva.ai to resume.` |

### Submit survey answers

`POST /api/v0/surveys/{token}/submissions`

Body: `data` (object, required): the answers keyed by question name, as SurveyJS produces them. Plus the identity: `iv` and `encryptedProfileId` for a personal link, or `anonymousId` for a public survey.

```plaintext
curl -X POST 'https://releva.ai/api/v0/surveys/7c3e1f20-6a4b-4c8d-9e0f-1a2b3c4d5e6f/submissions' \
  -H 'content-type: application/json' \
  -d '{
    "anonymousId": "<uuid>.<signature>",
    "data": { "satisfaction": 4, "reason": "Price", "email": "walkin@example.com" }
  }'
```

Response: `202` `{}`.

What happens: a `surveySubmission` event is written with `data` and the answers flattened into typed custom fields; the survey is marked submitted for this profile, so the next `GET` answers `submitted: true`; when the survey merges e-mail or phone numbers, the first answer of a `text` question with `inputType` `email` or `tel` is merged into the profile a moment later (or, on a public survey, the submission is attributed to the profile that already owns it). There is no server-side duplicate check: a second `POST` is also `202` and writes another event. Submissions keep working while value delivery is paused.

| Cause                                        | Status | Message                                                                   |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------- |
| `data` missing                               | `400`  | `The 'data' field is required.`                                           |
| `data` is not an object                      | `400`  | `The 'data' must be an Object.`                                           |
| No JSON body, or form-encoded body           | `400`  | `The '' field is required.` / `The 'data' field is required.`             |
| Survey without public link, no personal link | `403`  | `This survey can only be opened through a personal link.`                 |
| Broken personal link                         | `400`  | `Invalid profileId!`                                                      |
| Unknown token                                | `400`  | `Survey with token 00000000-0000-4000-8000-000000000000 cannot be found.` |
| Body over 800 KB                             | `413`  | `request entity too large`                                                |

### Submit an NPS answer

`POST /api/v0/nps/{token}/submissions`

| Field       | Type           | Required | Meaning                                                                                |
| ----------- | -------------- | -------- | -------------------------------------------------------------------------------------- |
| `profileId` | string or null | no       | Releva profile id (`rlv_u` cookie). Blank counts as absent.                            |
| `deviceId`  | string         | yes      | Device id; the respondent when `profileId` is blank. One of the two must be non-blank. |
| `sessionId` | string         | yes      | Session id (`rlv_s` cookie).                                                           |
| `score`     | integer 0-10   | yes      | 9-10 promoter, 7-8 passive, 0-6 detractor.                                             |
| `comment`   | string         | no       | The follow-up answer.                                                                  |

```plaintext
curl -X POST 'https://releva.ai/api/v0/nps/7c3e1f20-6a4b-4c8d-9e0f-1a2b3c4d5e6f/submissions' \
  -H 'content-type: application/json' \
  -d '{
    "profileId": null,
    "deviceId": "demo-device-1",
    "sessionId": "demo-session-1",
    "score": 9,
    "comment": "Fast delivery and friendly support."
  }'
```

Response: `202` `{}`.

What happens: an `npsSubmission` event is written (score, category, comment); the respondent’s cooldown for this survey starts (**Cooldown days**, default 90); the profile gets `nps_score`, `nps_category`, `nps_survey_id` and `nps_last_answered`. The survey must be **Active**. There is no duplicate check and no value-delivery gate.

| Cause                                 | Status | Message                                                                                               |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| Empty body `{}`                       | `400`  | `The 'deviceId' field is required. The 'sessionId' field is required. The 'score' field is required.` |
| `score: 11`                           | `400`  | `The 'score' field must be less than or equal to 10.`                                                 |
| `score: -1`                           | `400`  | `The 'score' field must be greater than or equal to 0.`                                               |
| `score: 7.5`                          | `400`  | `The 'score' field must be an integer.`                                                               |
| `score: "8"`                          | `400`  | `The 'score' field must be a number.`                                                                 |
| `profileId` and `deviceId` both blank | `400`  | `One of profileId or deviceId is required.`                                                           |
| No body                               | `400`  | `The '' field is required.`                                                                           |
| Unknown token                         | `400`  | `Survey not found.`                                                                                   |
| Survey is a draft or inactive         | `404`  | `Survey not found.`                                                                                   |
| Shop switched off                     | `402`  | `Shop is disabled. Please reach out to support@releva.ai to enable it.`                               |

## The NPS survey in the page push

`POST /api/v0/push/{accessToken}` (what `Releva.push` calls) returns an `nps` key when the visitor is eligible for an active NPS survey; otherwise the key is absent. Eligibility follows the order in [How an NPS survey reaches a visitor](https://releva.ai/documentation/learn/surveys/how-surveys-and-nps-work/#how-an-nps-survey-reaches-a-visitor). The server evaluates status, dates, platform (`context.device.platform`), app version (`context.device.version`), days since first contact (`context.device.firstSeenAt`), segments, the **Screen / Page View** and **Session Count** (`context.device.sessions`) triggers and the frequency rules; **Custom Event** triggers and **Cancel on events** are passed to the client. `"mode": "debug"` in the push body skips status, dates and frequency.

```plaintext
{
  "nps": {
    "token": "7c3e1f20-6a4b-4c8d-9e0f-1a2b3c4d5e6f",
    "question": "How likely are you to recommend Demo Store to a friend?",
    "scaleLowLabel": "Not at all likely",
    "scaleHighLabel": "Extremely likely",
    "followUp": { "promoter": "What do you like most?", "passive": "What would make it a 10?", "detractor": "What should we improve?" },
    "followUpRequired": false,
    "submitLabel": "Submit",
    "skipLabel": "Not now",
    "thankYou": { "promoter": "Thank you for your feedback!", "passive": "Thank you for your feedback!", "detractor": "Thank you for your feedback!" },
    "appearance": {},
    "triggers": [],
    "triggerDelaySeconds": 2,
    "cancelOnEvents": []
  }
}
```

| Field                                                        | Meaning                                                                                                                                                                                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `token`                                                      | Send it in the path of `POST /nps/{token}/submissions` and as `attributions.npsToken` on widget events.                                                                                                                  |
| `question`, `scaleLowLabel`, `scaleHighLabel`, `submitLabel` | Texts from the **Content** tab.                                                                                                                                                                                          |
| `followUp.{promoter,passive,detractor}`                      | Follow-up question per group; `null` means none, so submit the score on click.                                                                                                                                           |
| `followUpRequired`                                           | Keep **Submit** disabled until a comment is typed.                                                                                                                                                                       |
| `skipLabel`                                                  | `null` means no skip button.                                                                                                                                                                                             |
| `thankYou.{promoter,passive,detractor}`                      | Message to show for two seconds after submitting.                                                                                                                                                                        |
| `appearance`                                                 | `position` (`modal`, otherwise bottom sheet), `primaryColor`, `backgroundColor`, `textColor`, `buttonStyle` (`pill`, `rounded`, `square`), `logoUrl`, `dark` with the dark-mode colours. Empty when nothing was changed. |
| `triggers`                                                   | Only `customEvent` triggers, as `{ "type": "customEvent", "eventName": "..." }`. Empty means show after the delay.                                                                                                       |
| `triggerDelaySeconds`                                        | Wait before showing.                                                                                                                                                                                                     |
| `cancelOnEvents`                                             | Event names that cancel a pending survey for this session.                                                                                                                                                               |

A client that renders this object should report what the visitor did through `POST /api/v0/push/events/{accessToken}` with `attributions: { "npsToken": "<token>" }` and one of these `action` values: `npsImpression` (drawn), `npsScoreSelected`, `npsSubmitted`, `npsSkipped`, `npsDismissed` (closed without answering; no submission is recorded, so the survey can show again next session).

## JavaScript SDK

The NPS widget is part of the standard Releva snippet; the push response wires it up. Two functions are exposed for sites that use custom triggers:

```plaintext
<script>
  // Fire a Custom Event trigger, or cancel the pending survey if the name is in "Cancel on events".
  Releva.trackEvent('orderTracked');


  // Hand over an nps object obtained another way (for example your own push call). Idempotent.
  Releva.showNps(response.nps);
</script>
```

The SDK shows at most one NPS survey per session, skips the widget on Releva preview and layout-edit pages, posts the submission as `{ profileId, deviceId, sessionId, score, comment }` with one retry after 2 seconds, and sends the score together with the comment when a follow-up question exists.

## Known limitations

* A token that is not a UUID answers `500` instead of `400` on all three endpoints.
* An unknown NPS token answers `400` and a draft or inactive one `404`, both with `Survey not found.`
* `linkToken` from the personal link is accepted but not used; “once per link” is tracked per survey and profile, so a second personal link for the same profile opens as already submitted.

## Next steps

* [How surveys and NPS work](https://releva.ai/documentation/learn/surveys/how-surveys-and-nps-work/): Learn how respondents reach a survey, how an NPS survey is picked for a visitor and where the answers go.
* [Events API overview](https://releva.ai/documentation/reference/events/overview/): See the page push and push-event calls these objects travel in.
* [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/): Copy the Access Token for the page push that carries the NPS widget; the survey endpoints themselves need no key.