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.
Authentication
Section titled “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
ivandprofileIdquery values (the survey page sendsprofileIdasencryptedProfileId) decrypt to the recipient’s profile. A survey without Public link (QR code) requires them. - Survey, public link: no identity is needed. The first
GETreturnsidentity.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(therlv_ucookie) or, when it is blank,deviceId.
Request format
Section titled “Request format”- Send JSON with
content-type: application/json. The NPS endpoint also acceptsapplication/x-www-form-urlencodedwith one field,formPayload, holdingbase64(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 insidedata, 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
Section titled “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
Section titled “Endpoints”Open a survey
Section titled “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.
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. |
Submit survey answers
Section titled “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.
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
Section titled “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. |
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
Section titled “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. 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).
JavaScript SDK
Section titled “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:
<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
Section titled “Known limitations”- A token that is not a UUID answers
500instead of400on all three endpoints. - An unknown NPS token answers
400and a draft or inactive one404, both withSurvey not found. linkTokenfrom 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.