REST API

SurveyLab allows you to access your data with the REST API interface. Access to API is available with a secure connection (SSL / HTTPS) and requires a token. Data are available in JSON format. User authentication is done with JWT. For more information check our new API developer documentation.

NOTE. In order to use the API, you will need clientId and clientSecret. This information is provided on request. To get it please contact us.

List of available requests :

Get token
Get survey list
Get survey
Get survey questions
Get reports list
Get report
Get metric (Report)
Get survey responses (100)
Get survey response
Get survey metadata
Get metric (Single response)

Status codes

The statuses are returned using the standard HTTP error code syntax.

Code	Description
200	OK. The request was successful.
400	Bad request. The request was incorrect. Invalid API token.
401	Unauthorized. You attempt to authenticate with an invalid username or API key.
404	Not Found. The resource doesn’t exist.
429	Too many requests.
500	Internal Server Error. Please try again or contact our support.

Get token

Obtaining an access token for communication. The token is valid for 30 days.

POST https://api.surveylab.com/oauth/token/

cURL
cᴜrⅼ -i -X POST https://api.surveylab.com/oauth/token/ -d “clientSecret=YOUR_CLIENT_SECRET&clientId=YOUR_CLIENT_ID“

Result example

Your JWT Token

Get survey list

Obtaining the list of surveys. You will get a list of all surveys on your account.

GET https://api.surveylab.com/api/v3/surveys/

cURL
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/

Example
https://api.surveylab.com/api/v3/surveys/

Result example

[{
“surveyId”: 22789,
“userId”: 127,
“surveyThemeId”: 90,
“name”: “eNPS”,
“questionNumbering”: “survey”,
“headerPageTitleShow”: null,
“headerPageNumberShow”: null,
“pageRotation”: 0,
“logoPlacement”: null,
“layoutHideProgressBar”: null,
“created”: 1540556695,
“modified”: “2019-01-03 15:14:45”,
“footerVisible”: null,
“headerShowTitle”: null,
“answerOneClick”: null,
“logoVisibility”: null,
“logoVisibilityEmbedded”: null,
“logoURL”: null,
“blockRotation”: 0,
“defaultName”: “eNPS”,
“languageId”: 2,
“impressions”: 2,
“responses”: 1,
“correct”: 1,
“unpaidResponses”: 0,
“opened”: 1,
“campaignCount”: 1
}]

Get survey

Obtaining a single survey with the id {survey-id}. You will get the whole survey, including information about pages, blocks, etc. To send this request you will need to know {survey-id}. You can find it on the survey preview URL, on the survey design URL, or with the Get survey list request.

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/

cURL
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/

Example
GET https://api.surveylab.com/api/v3/surveys/21045/

Result example

[{
“surveyId”: 21045,
“userId”: 127,
“modified”: “2019-01-08 16:44:12”,
“surveyThemeId”: 90,
“languageId”: null,
“name”: “Was this article helpful”,
“title”: “Was this article helpful”,
“questionNumbering”: “survey”,
“textDirection”: “ltr”,
“pageRotation”: 0,
“blockRotation”: 0,
“answerOneClick”: false,
“blocksById”: {
“25480”: {
“blockId”: 25480,
“surveyId”: 21045,
“blockIsRotated”: 0,
“blockNumber”: 1,
“blockIdBySurvey”: 1,
“blockName”: “Block name”,
“pagesOrder”: {
“1”: 85533
}
}
},
“pagesById”: {
“85533”: {
“surveyId”: 21045,
“pageId”: 85533,
“number”: 1,
“pageIdBySurvey”: 1,
“welcomePage”: 0,
“title”: “Untitled Page”,
“description”: null,
“titleVisible”: 1,
“blockId”: 25480,
“questionOffset”: 0,
“questionsOrder”: [
194238
],
“pageIsRotated”: 0,
“questionsRotation”: 0,
“randomQuestion”: null
}
},
“questionsById”: {
“194238”: {
“questionId”: 194238,
“pageId”: 85533,
“type”: “simple”,
“params”: {
“question”: “Was this article helpful?”,
“description”: “”,
“required”: 0,
“comments”: 0,
“exclusionQuestion”: false,
“questionImgURL”: “”,
“maxNumberOfAnswers”: 0,
“minNumberOfAnswers”: 0,
“answers”: [
“Yes”,
“No”
],
“imageAnswer”: [],
“open”: “”,
“multiple”: 0,
“noneAbove”: “”,
“hideLableText”: 0,
“points”: 0,
“columnElements”: 0,
“scoreArray”: {
“0”: “1”,
“1”: “-1”,
“max”: “1”
},
“presentationTiled”: 1,
“presentation”: “tiles-horizontal”,
“random”: 0,
“randomizeOptions”: true
},
“questionIsRotated”: 0,
“isRandomQuestion”: 1,
“numbering”: true,
“number”: 1,
“questionIdBySurvey”: 1,
“addedToBank”: false,
“templateFile”: “questions/simple.tpl”,
“points”: 0,
“opentext”: “”,
“open”: 0
}
},
“public”: 1,
“defaultTranslation”: 1,
“blocksOrder”: {
“1”: 25480
}
}]

Get survey questions

Obtaining survey questions for a selected survey id {survey-id}. You will get survey questions only.

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/questions/

cᴜrⅼ
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/questions/

Result example

[{
“questionId”: 194238,
“number”: 1,
“questionIdBySurvey”: 1,
“type”: “simple”,
“questionParams”: {
“question”: “Was this article helpful?”,
“description”: “”,
“translatable”: {
“question”: “Was this article helpful?”,
“description”: “”,
“open”: “”,
“noneAbove”: “”,
“answers”: [
“Yes”,
“No”
]
},
“required”: 0,
“comments”: 0,
“exclusionQuestion”: 0,
“questionImgURL”: “”,
“maxNumberOfAnswers”: 0,
“minNumberOfAnswers”: 0,
“answers”: [
“Tak”,
“Nie”
],
“imageAnswer”: [],
“open”: “”,
“multiple”: 0,
“noneAbove”: “”,
“hideLableText”: 0,
“points”: 0,
“columnElements”: 0,
“scoreArray”: {
“0”: “1”,
“1”: “-1”,
“max”: “1”
},
“presentationTiled”: 1,
“presentation”: “tiles-horizontal”,
“random”: 0,
“randomizeOptions”: true
}]

Get reports list

Obtaining a list of reports for a selected {survey-id}. To send this request you will need to know survey-id.

cURL
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/reports/

Example
GET https://api.surveylab.com/api/v3/surveys/27162/resports/

Results example

…

Get survey responses

Obtaining single survey responses for a selected survey id {survey-id}, first 100 records.

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/

cURL
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/

Example
GET https://api.surveylab.com/api/v3/surveys/21045/responses/

Result example

[{
“responseId”: 6923205,
“surveyId”: 21045,
“iso3166”: “PL”,
“crk”: null,
“promoCode”: null,
“completed”: 1,
“dateStart”: “2019-01-03 13:26:34”,
“dateCompleted”: “2019-01-03 13:26:39”,
“questionId”: 194238,
“answer”: [
0
],
“comment”: “”,
“score”: null,
“matrixScore”: null
},
{
“responseId”: 6923207,
“surveyId”: 21045,
“iso3166”: “PL”,
“crk”: null,
“promoCode”: null,
“completed”: 1,
“dateStart”: “2019-01-03 13:27:05”,
“dateCompleted”: “2019-01-03 13:27:08”,
“questionId”: 194238,
“answer”: [
1
],
“comment”: “”,
“score”: null,
“matrixScore”: null
}]

Get survey responses (100)

Obtaining survey responses for a selected survey id {survey-id}, second 100 records. Change page number (eg. /page/3/) to get the next 100 respondents. You can also set responses sorting: asc (ascending) or desc (descending).

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/page/2/
GET https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/page/2/order/asc/

cᴜrⅼ
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/page/2/

cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/page/1/order/asc/

Example
GET https://api.surveylab.com/api/v3/surveys/21045/responses/page/2/
GET https://api.surveylab.com/api/v3/surveys/21045/responses/page/2/order/asc/

Result example

[{
“responseId”: 6923209,
“surveyId”: 21045,
“iso3166”: “PL”,
“crk”: null,
“promoCode”: null,
“completed”: 1,
“dateStart”: “2019-01-03 13:27:11”,
“dateCompleted”: “2019-01-03 13:27:13”,
“questionId”: 194238,
“answer”: [
0
],
“comment”: “”,
“score”: null,
“matrixScore”: null
},
{
“responseId”: 6923229,
“surveyId”: 21045,
“iso3166”: “PL”,
“crk”: null,
“promoCode”: null,
“completed”: 1,
“dateStart”: “2019-01-03 13:32:29”,
“dateCompleted”: “2019-01-03 13:32:31”,
“questionId”: 194238,
“answer”: [
0
],
“comment”: “”,
“score”: 1,
“matrixScore”: null
}]

Get survey response

Obtaining a single survey response for a selected survey id {survey-id}. You can use {response-id} or {crk}.

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/{response-id}/
GET https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/crk/{crk}/

cᴜrⅼ
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/{response-id}/

cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/crk/{crk}/

Example
GET https://api.surveylab.com/api/v3/surveys/27162/responses/7423534/
GET https://api.surveylab.com/api/v3/surveys/27162/responses/crk/AGVID43/

Get metric (Single response)

Obtaining metric value for a single response.

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/{response-id}/metrics/

cURL
cᴜrⅼ -i -X GET -H “Authorization:bearer YOUR_ACCESS_TOKEN” -H “Content-Type”: “application/json” https://api.surveylab.com/api/v3/surveys/{survey-id}/responses/{response-id}/metrics/

Example
GET https://api.surveylab.com/api/v3/surveys/52549/responses/18287824/metrics/

Result example

[{
“12935”: {
“metricId”: 1267,
“surveyId”: 52549,
“metricName”: “CSAT”,
“presentation”: “points”,
“maxValueIncludingEmptyAnswer”: 0,
“testMode”: 1,
“firstLevelThreshold”: 12,
“secondLevelThreshold”: null,
“created”: “2022-10-26 12:30:00”,
“score”: {
“pointsSum”: 24,
“maxPointsSum”: 27,
“minPointsSum”: 0,
“nps”: false
}
}]

Get metric (Report)

Obtaining metric value for a report.

GET https://api.surveylab.com/api/v3/surveys/{survey-id}/reports/{report-id}/metrics/

Example
GET https://api.surveylab.com/api/v3/surveys/52549/reports/177055/metrics/

Result example

[{
“1267”: {
“metricId”: 1267,
“surveyId”: 52549,
“metricName”: “CSAT”,
“presentation”: “points”,
“maxValueIncludingEmptyAnswer”: 0,
“testMode”: 0,
“firstLevelThreshold”: null,
“secondLevelThreshold”: null,
“created”: “2022-10-26 12:30:00”,
“score”: “5.80”,
“condition”: “”,
“maxPointsSum”: 16,
“minPointSum”: 0,
“responseSum”: “15”
}]

Get survey metadata

Obtaining survey metadata for a selected survey id {survey-id}, eg.: os, web browser, language or device type. To send this request you will need to know survey-id.

Example
GET https://api.surveylab.com/api/v3/surveys/27162/responses/7423534/metadata/

Results example

[{
“responseId”:8610691,
“ip”:”127.0.0.1″,
“referrer”:null,
“iso3166″:”PL”,
“languageId”:null,
“languageName”:null,
“languageSymbol”:null,
“deviceType”:”desktop”,
“deviceTypeName”:”Desktop”,
“os”:”Ubuntu”,
“browser”:”Firefox 77.0″
}]