Search search
Help sections
FAQ

REST API

V3

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.

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 :


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.
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
curl -i -X POST https://api.surveylab.com/oauth/token/ -d "clientSecret=YOUR_CLIENT_SECRET&clientId=YOUR_CLIENT_ID"

Result example

Access 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
curl -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
curl -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/

cURL
curl -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 survey responses

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

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

cURL
curl -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/

cURL
curl -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/

curl -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}/

cURL
curl -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}/

curl -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 http://api.surveylab.com/api/v3/surveys/27162/responses/7423534/
GET http://api.surveylab.com/api/v3/surveys/27162/responses/crk/AGVID43/

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.

cURL
curl -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}/metadata/

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"
}]


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

[{
"reportId": 4836,
"surveyId": 161,
"campaignId": null,
"reportType": "default",
"compareReportIdArray": null,
"publicName": null,
"dataPeriod": "week",
"mainReport": 1,
"campaignReport": 0,
"responseDateFirst": "2007-08-07 18:01:41",
"responseDateLast": "2020-06-09 12:13:02",
"created": "2011-04-15 07:44:34",
"checked": "2022-05-11 02:12:06",
"modified": "2022-05-11 02:12:17",
"responses": 32,
"currentlyProcessing": 0,
"currentlyExporting": 0
},
{
"reportId": 8039,
"surveyId": 161,
"campaignId": 114,
"reportType": "default",
"compareReportIdArray": null,
"publicName": null,
"dataPeriod": "week",
"mainReport": 0,
"campaignReport": 1,
"responseDateFirst": "2007-08-07 18:01:41",
"responseDateLast": "2009-03-11 20:42:09",
"created": "2011-04-15 07:44:50",
"checked": "2022-05-11 02:12:11",
"modified": "2022-05-11 02:12:27",
"responses": 30,
"currentlyProcessing": 0,
"currentlyExporting": 0
}]


Get report

Obtaining selected report. To send this request you will need to know {survey-id} and {report-id}. You can find it on the report page URL.

cURL
curl -i -X GET -H "Authorization:bearer YOUR_ACCESS_TOKEN" -H "Content-Type": "application/json" https://api.surveylab.com/api/v3/surveys/{survey-id}/reports/{report-id}/

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

Results example

[{
    "surveyId": 53192,
    "modified": "2022-12-15 14:47:56",
    "title": "CSAT",
    "name": "CSAT",
    "displayBlocks": false,
    "blocksOrder": [
        59894
    ],
    "blocksById": {
        "59894": {
            "blockId": 59894,
            "blockIdBySurvey": 1,
            "blockName": "Nazwa bloku",
            "blockIsRandomizable": false,
            "pagesOrder": [
                240644
            ],
            "surveyId": 53192,
            "pagesRandomizationType": "none",
            "pagesRandomizationSelections": []
        }
    },
    "pagesById": {
        "240644": {
            "surveyId": 53192,
            "blockId": 59894,
            "description": null,
            "pageId": 240644,
            "pageIdBySurvey": 1,
            "params": {
                "title": "CSAT",
                "questionsOrder": [
                    561138
                ]
            },
            "type": "default",
            "hidedPage": false,
            "started": null,
            "finished": null
        }
    },
    "questionsById": {
        "561138": {
            "hidedQuestion": false,
            "comment": null,
            "multimedia": null,
            "imageAlt": null,
            "pageId": 240644,
            "params": {
                "comments": false,
                "description": "",
                "descriptionType": "default",
                "question": "Was this article helpful?",
                "required": false,
                "answer": [],
                "columns": 0,
                "multiple": false,
                "multipleLimits": null,
                "multipleLimitsEqual": null,
                "multipleLimitsFrom": null,
                "multipleLimitsTo": null,
                "presentation": "vertical",
                "hidedLabels": false,
                "answers": [
                    {
                        "id": 0,
                        "label": "Yes",
                        "image": null,
                        "points": null,
                        "pointsNa": false,
                        "open": null,
                        "noneAbove": false
                    },
                    {
                        "id": 1,
                        "label": "No",
                        "image": null,
                        "points": null,
                        "pointsNa": false,
                        "open": null,
                        "noneAbove": false
                    }
                ],
                "reportSettings": {
                    "showQuestionInPublic": true,
                    "showCommentInPublic": false,
                    "comment": ""
                },
                "reportData": {
                    "comments": {
                        "list": [],
                        "cloud": []
                    },
                    "results": {
                        "bar": {
                            "chart": [
                                "data",
                                1,
                                0
                            ],
                            "chartXAxis": [
                                "x",
                                0,
                                1
                            ],
                            "chartPercenages": [
                                "percentages",
                                100,
                                0
                            ]
                        },
                        "otherData": []
                    }
                }
            },
            "questionId": 561138,
            "questionIdBySurvey": 1,
            "type": "simple",
            "responseCount": 1,
            "questionScore": null,
            "maxScore": null,
            "reportSummary": {
                "responses": 1,
                "filtered": 0,
                "score": null,
                "scoreNumberOfItems": null,
                "omitted": 0
            },
            "reportData": {
                "closed": [
                    1,
                    0
                ],
                "percentages": [
                    100,
                    0
                ],
                "openCount": 0,
                "noneAboveCount": 0
            },
            "score": null
        }
    },
    "blocksIdByCode": {
        "B1": 59894
    },
    "pagesIdByCode": {
        "P1": 240644
    },
    "questionsIdByCode": {
        "Q1": 561138
    },
    "responseCount": 1,
    "reportId": 179334,
    "mainReport": 1,
    "responseDateLast": "2022-12-15 14:43:31",
    "showPoints": true,
    "showTrends": true,
    "showCloudCharts": true,
    "showMetrics": true,
    "showBenchmarkMetrics": false,
    "showQuestionTrends": false,
    "showComments": true,
    "showQuestionAnswerTags": false,
    "showResponseStatuses": false,
    "showResponseComments": false,
    "dataPeriod": "day",
    "reportName": "survr_MainReport",
    "reportPublicName": null,
    "campaignReport": false,
    "reportType": "default"
}]


Contact us

We are constantly improving our survey software and API. If you have any questions or needs regarding the API please contact us.

NOTE. REST is an acronym for REpresentational State Transfer. API is an acronym for Application Programming Interface. JSON is an acronym for JavaScript Object Notation. JWT is an acronym for JSON Web Token.


* Functionality is available in the Enterprise plan.

Related pages