Skip to content

Area: Developers

GET

Open a survey

Path
/surveys/{token}
Auth
None · a public or signed link
GET
/surveys/{token}
curl --request GET \
--url 'https://releva.ai/api/v0/surveys/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?anonymousId=%3Cuuid%3E.%3Chmac-sha256%20hex%3E'

Returns the survey definition (SurveyJS JSON) and whether this respondent already submitted it. Called by the Releva survey app when someone opens a survey link; call it only if you render surveys in your own front end. Every call records a surveyOpen event.

No API key: the survey token in the path is the credential. The respondent is identified by the personal link (iv + encryptedProfileId, from the {{surveyLink}} merge tag). A survey without Public link (QR code) answers 403 without one. A survey with a public link ignores personal links and identifies the respondent by anonymousId, minting a new one (returned in identity) when none or an invalid one is sent.

token
required
string format: uuid

Survey token (UUID; in the survey link as token=). A value that is not a UUID answers 500.

iv
string

Initialisation vector of the personal link (iv=). Required whenever encryptedProfileId is sent.

encryptedProfileId
string

The personal link’s profileId= value (encrypted profile id). Required whenever iv is sent.

anonymousId
string

Identity returned by an earlier open of a public survey. Used only on surveys with a public link.

linkToken
string

Per-message id added by the merge tag. Accepted and not used.

The survey.

Media typeapplication/json
object
survey
required
object
config
required

SurveyJS survey JSON as saved in the admin designer (title, pages[].elements[], …). cookieName: rlv_survey_submitted means Allowed Submissions is “Once per link”.

object
key
additional properties
any
theme
required

SurveyJS theme JSON.

object
key
additional properties
any
submitted
required

This respondent already submitted the survey. Always false when a new identity was minted.

boolean
identity

Present only when a new anonymous identity was minted (public surveys). Send it back on submit.

object
anonymousId
required

<uuid>.<hmac-sha256 hex>

string

Example

{
"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": "5b0c7a52-3f7e-4d0a-9b8e-2c1f6a7d9e10.6f1d2c3b4a59687766554433221100ffeeddccbbaa99887766554433221100ff"
}
}

Broken personal link or unknown survey.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Invalid profileId!"
}

The domain is switched off, or value delivery is paused because usage exceeded the plan limit.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Shop is disabled. Please reach out to support@releva.ai to enable it."
}

The survey has no public link and the request carries no personal link.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "This survey can only be opened through a personal link."
}

Unexpected server error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}