Skip to content

Area: Developers

Surveys and NPS API

Used byJavaScript SDK, Mobile SDKs, iOS (Swift), Flutter, React Native

Surveys and NPS surveys are configured in the admin (Create a survey, 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; this page covers only their NPS parts. For the behaviour behind all of this, read How surveys and NPS work.

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.
  • 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.

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.

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.

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:

{
"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.

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.

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

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

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

{
"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).

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:

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

  • 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.