Welcome to v1 of the SurveyRock API documentation
Overview
Authentication
All requests to our API servers must be done over HTTPS. Any non-HTTPS requests will be ignored.
Requests are required to use Oauth 2.0 Bearer Tokens to prove that you are allowed access to the surveys and responses. The token can be found in your API Access page. Please note that tokens are valid for 1 year.
For example, using curl might look like this:
curl --location --request GET --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIyIiwianRpIjoiNWI2OWE0ZDFmMjY4MmIxNTZmZWJhMTNhYzE1NjdmMjgxMWI3NDJiNmI0YTMxOWNjNDkzZGZhNzQxYmE2NDA4ZmQ1YzQxNzdiM2E2M2U0ZGUiLCJpYXQiOjE2NTA3MjYyNDAuMjk5OTQ3LCJuYmYiOjE2NTA3MjYyNDAuMjk5OTUzLCJleHAiOjE2ODIyNjIyNDAsInN1YiI6IjIiLCJzY29wZXMiOltdfQ.LcjTYUGbKf_UGD8Pm6EHbbmIq0ftoGG-BRBuaKOr_4w7NjHRNeLbi3ssJTVUC_Cr1NHc65oe7XUm7CNcpydrtZhG8H1RhE0XXCX0GvgwkCcXrdM2qG34MN_7m-sPjivB5rNJG_bmIUtxGLY3Rp6nFY-jql30TsXhfyhmKTl0r2LavMs7lPgJD8z2X2WLB7TBKs5pWMjqzPS8UuTLE70pSC-Zdp-z93SvEOPi8_7oG6mpfAQ0V31u2wNxQe_tCK9kBl3KaI6XyXvwv3MSgVy2gr2_Hg5_cYYPerb4tl8WMboH2LLcJJ3YH_3wmIPqBA09n21_wRk_h1FIXKWIS0pkYr" https://api.surveyrock.com/sv1/surveys/get_survey_details?survey_id=852725
API Limits
Currently, only our Enterprise, Premium and Business account users can access the API and have a rate limit of 1 request per second. If too many requests are received within the time period, a response with status code 429 (Too Many Requests) is returned.
Question Types
When you access the structure of a specific survey (/surveys/get_survey_details), you are given the type of each question. The options currently available are:
- text_single_line
- text_multiple_lines
- comment_box
- number
- date
- multiple_choice
- matrix
- rating_scale
- image_multiple_choice
- net_promoter_score
- star_rating
Responses
All request responses are returned with a content type of 'application/json' and use the 'UTF-8' character set. Standard HTTP response codes are returned with each result. Responses done correctly will look similar to this:
{
"status": 200,
"status_text": "OK",
"data": {
"completed": 30,
"started": 26
}
}
Updates
| Date | Changes |
|---|---|
| April 23, 2022 | Replaced the Basic Authentication with OAuth 2.0. |
| October 20, 2020 | Added new question types. |
| June 5, 2019 | Added new question types and updated the names to reflect the new v2 naming conventions. |
| March 30, 2016 | Initial publication of the API documentation. |
API Methods
Create a Distributor
POST /sv1/distributors/create_distributor
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/distributors/create_distributor?survey_id=9341&type=web_link
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| survey_id | integer | Survey ID | required |
| type | string | Type of distributor. Only 'web_link' is currently supported. | required |
| title | string | Name of distributor. Defaults to 'New Web Link'. | optional |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| distributor | object | required | |
| distributor_id | integer | Distributor ID | required |
| date_created | string | Date the distributor was created | required |
| title | string | Title of the distributor | required |
| active | boolean | Whether the distributor is active, i.e. open to collect responses. | required |
| type | string | Type of distributor. Currently 'web_link' is the only option. | required |
| url | string | If this is a Web Link distributor (type 'web_link'), then this is the url for the distributor. | required |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"distributor": {
"distributor_id": 2694,
"date_created": "2022-03-14 18:32:10",
"title": "New Web Link",
"active": true,
"type": "web_link",
"url": "https://www.surveyrock.com/ts/PZJ86F"
}
}
}
List all Distributors for a given Survey
GET /sv1/distributors/get_distributor_list
Date-time strings must be in the format YYYY-MM-DD HH:MM:SS but the time portion is optional. All date-time strings are in UTC.
All 'created_after' dates are greater than or equal to the date submitted.
All 'created_before' dates are less than date submitted.
All 'created_after' dates are greater than or equal to the date submitted.
All 'created_before' dates are less than date submitted.
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/distributors/get_distributor_list?survey_id=8548&created_after=2019-06-01
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| survey_id | integer | Survey ID | required |
| page | integer | Page number. Defaults to 1. | optional |
| page_size | integer | Number of distributors to display per page. Defaults to 100. | optional |
| sort | string | The sort order of the returned distributors. 'sort=date_created' returns oldest first. 'sort=-date_created' returns newest first. | optional |
| created_after | string | Distributors must have been created after this date & time. | optional |
| created_before | string | Distributors must have been created before this date & time. | optional |
| fields | string | Describe which fields should be returned. One or more of: distributor_id, date_created, title, active, type, url, date_active, date_disabled. Multiple field names separated by comma. Default: All | optional |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| distributors | object | optional | |
| distributor_id | integer | Distributor ID | optional |
| date_created | string | Date the distributor was created. | optional |
| title | string | Title of the distributor. | optional |
| active | boolean | Whether the distributor is active, i.e. open to collect responses. | optional |
| type | string | Type of distributor. Currently 'web_link' is the only option. | optional |
| url | string | If this is a Web Link distributor (type 'web_link') then this is the url for the distributor. | optional |
| date_active | null or string | Date & time when the distributor will first be active, i.e. open to collect responses. Null if blank. | optional |
| date_disabled | null or string | Last date & time when the distributor will be active, i.e. open to collect responses. Null if blank. | optional |
| total_count | integer | Total count of distributors to be returned by this query. | required |
| page_count | integer | Number of pages of results to be returned. | required |
| current_page | integer | Current page number | required |
| per_page | integer | Maximum number of results shown per page. | required |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"distributors": [
{
"distributor_id": 2148,
"date_created": "2014-06-24 14:44:37",
"title": "Exit Survey",
"active": true,
"type": "web_link",
"url": "https://www.surveyrock.com/ts/8",
"date_active": null,
"date_disabled": null
}
],
"total_count": 1,
"page_count": 1,
"current_page": 1,
"per_page": 100
}
}
List Respondents for a given Survey
GET /sv1/respondents/get_respondent_list
Date-time strings must be in the format YYYY-MM-DD HH:MM:SS but the time portion is optional. All date-time strings are in UTC.
All 'started_after' dates are after or equal to the date started.
All 'started_before' dates are before the date started.
All 'started_after' dates are after or equal to the date started.
All 'started_before' dates are before the date started.
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/respondents/get_respondent_list?survey_id=8658
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| survey_id | integer | Survey ID | required |
| page | integer | Page number. Defaults to 1. | optional |
| page_size | integer | Number of respondents to display per page. Defaults to 100. | optional |
| sort | string | The sort order of the returned respondents. 'sort=date_started' returns oldest first. 'sort=-date_started' returns newest first. | optional |
| started_after | string | Respondents must have starting taking the survey after this date & time. | optional |
| started_before | string | Respondents must have started taking the survey before this date. | optional |
| fields | string | Describe which fields should be returned. One or more of: respondent_id, date_started, date_finished, distributor_id, ip_address, device_type. Multiple field names separated by comma. Default: All | optional |
| distributor_id | integer | Distributor ID | optional |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| respondents | object | optional | |
| respondent_id | integer | Respondent ID | optional |
| date_started | string | Date & time the respondent started taking the survey. | optional |
| date_finished | string or null | Date & time the respondent finished taking the survey. | optional |
| distributor_id | integer | Distributor ID | optional |
| IP address | string | IP address of the respondent. | optional |
| device_type | string | The type of device the respondent used to take the survey. Can be one of: Desktop, Mobile, Tablet, Unknown. | optional |
| total_count | integer | Total count of respondents to be returned by this query. | required |
| page_count | integer | Number of pages of results to be returned. | required |
| current_page | integer | Current page number | required |
| per_page | integer | Maximum number of results shown per page. | required |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"respondents": [
{
"respondent_id": 1230211,
"date_started": "2015-12-17 13:03:58",
"date_finished": "2015-12-17 13:04:45",
"distributor_id": 4218,
"ip_address": "184.175.74.157",
"device_type": "Desktop"
},
{
"respondent_id": 1230213,
"date_started": "2015-12-17 13:03:58",
"date_finished": "2015-12-17 13:40:21",
"distributor_id": 4218,
"ip_address": "184.175.74.157",
"device_type": "Desktop"
},
{
"respondent_id": 1230724,
"date_started": "2016-03-08 16:25:51",
"date_finished": "2016-03-08 16:25:58",
"distributor_id": 4218,
"ip_address": "192.168.10.150",
"device_type": "Desktop"
}
],
"total_count": 3,
"page_count": 1,
"current_page": 1,
"per_page": 100
}
}
Number of Responses
GET /sv1/respondents/get_response_counts
Displays the number of respondents who have started and/or completed the survey for the given distributor.
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/respondents/get_response_counts?distributor_id=3997
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| distributor_id | integer | Distributor ID | required |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| completed | integer | Number of completed responses | required |
| started | integer | Number of responses that were started but not completed | required |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"completed": 3,
"started": 2
}
}
Response Details
GET /sv1/respondents/get_responses
Best used together with the '/surveys/get_survey_details' method.
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/respondents/get_responses?&survey_id=5595&respondent_ids[]=2640&respondent_ids[]=2645
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| survey_id | integer | Survey ID | required |
| respondent_ids | array[integer] | Respondents to retrieve. Format can either be 'respondent_ids[]=2000&respondent_ids[]=2002' or 'respondent_ids=[2000,2002]' | required |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| respondents | object | required | |
| respondent_id | integer | Respondent ID | optional |
| questions | object | optional | |
| question_id | integer | Question ID | optional |
| answers | object | optional | |
| text | string | Answer from a text type question | optional |
| choice_id | integer | ID of a multiple choice type question | optional |
| col | string | Column number of a column type question. Count starts at 0. | optional |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"respondents": [
{
"respondent_id": 2000,
"questions": [
{
"question_id": 97,
"answers": [
{
"text": "Not sure"
}
]
},
{
"question_id": 57,
"answers": [
{
"choice_id": 208
}
]
},
{
"question_id": 66,
"answers": [
{
"choice_id": 425,
"col": "1"
},
{
"choice_id": 426,
"col": "2"
},
{
"choice_id": 427,
"col": "2"
}
]
},
{
"question_id": 69,
"answers": [
{
"choice_id": 437,
"text": "jkj"
},
{
"choice_id": 441,
"text": "kjk"
}
]
}
]
}
]
}
}
List of all Surveys
GET /sv1/surveys/get_survey_list
Date-time strings must be in the format YYYY-MM-DD HH:MM:SS but the time portion is optional. All date-time strings are in UTC.
All 'created_after' / 'modified_after' dates are greater than or equal to the date submitted.
All 'created_before' / 'modified_before' dates are less than date submitted.
All 'created_after' / 'modified_after' dates are greater than or equal to the date submitted.
All 'created_before' / 'modified_before' dates are less than date submitted.
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/surveys/get_survey_list
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| page | integer | Page number. Defaults to 1. | optional |
| page_size | integer | Number of surveys to display per page. Defaults to 100. | optional |
| sort | string | The sort order of the returned surveys. 'sort=date_created' returns oldest first. 'sort=-date_created' returns newest first. | optional |
| created_after | string | Surveys must have been created after this date & time. | optional |
| created_before | string | Surveys must have been created before this date & time. | optional |
| fields | string | Describe which fields should be returned. One or more of: survey_id, date_created, date_modified, title, description, active, num_responses. Multiple field names separated by comma. Default: all | optional |
| modified_after | string | Surveys must have been modified after this date & time. | optional |
| modified_before | string | Surveys must have been modified before this date & time. | optional |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| surveys | object | optional | |
| survey_id | integer | Survey ID | optional |
| date_created | string | Date the survey was created. | optional |
| date_modified | string | Date the survey was last modified. | optional |
| title | string | Title of the survey | optional |
| description | string | Description of the survey | optional |
| num_responses | integer | Count of survey responses, started and completed. | optional |
| total_count | integer | Total count of surveys to be returned by this query | required |
| page_count | integer | Number of pages of results to be returned | required |
| current_page | integer | Current page number | required |
| per_page | integer | Maximum number of results shown per page | required |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"surveys": [
{
"survey_id": 30145,
"date_created": "2016-03-09 11:44:13",
"date_modified": "2016-03-09 17:51:38",
"title": "Game Prediction",
"description": "test",
"num_responses": 1545
},
{
"survey_id": 32564,
"date_created": "2015-09-23 18:14:51",
"date_modified": "2016-03-03 15:03:24",
"title": "test2",
"description": "test2",
"num_responses": 224
}
],
"total_count": 2,
"page_count": 1,
"current_page": 1,
"per_page": 100
}
}
Survey Details
GET /sv1/surveys/get_survey_details
Example Request
curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/surveys/get_survey_details?survey_id=5680
Query String
| Name | Type | Description | Required |
|---|---|---|---|
| survey_id | integer | Survey ID | required |
Response Schema
| Name | Type | Description | Required |
|---|---|---|---|
| Object | |||
| status | integer | Standard HTTP status code | required |
| status_text | string | Brief status code description | required |
| data | object | required | |
| survey_id | integer | Survey ID | optional |
| date_created | string | Date and time the survey was created | optional |
| date_modified | string | Date and time the survey was last modified | optional |
| num_responses | integer | Count of survey responses, both started and completed. | optional |
| num_questions | integer | The number of questions contained within the survey. | optional |
| title | object | optional | |
| enabled | boolean | Whether or not the survey title will be displayed. | optional |
| text | string | Survey title | optional |
| description | string | Description of the survey | optional |
| pages | object | optional | |
| page_id | integer | Page ID | optional |
| position | integer | Page number, starting at 1. | optional |
| title | string | Page title | optional |
| questions | object | optional | |
| question_id | integer | Question ID | optional |
| position | integer | Order number of the question. Numbering starts at 1. | optional |
| title | string | Question title | optional |
| type | string | Type of question. Can be one of: multiple_choice, textbox_single, textbox_multiple, text_area, number, rating, matrix. | optional |
| choices | object | optional | |
| choice_id | integer | Choice ID | optional |
| position | integer | Order of the choice. Numbering starts with 1. | optional |
| title | string | Choice title | optional |
| type | string | Choice type. Can be either row, col or other. | optional |
Response Example
{
"status": 200,
"status_text": "OK",
"data": {
"survey_id": 5268,
"date_created": "2015-02-11 18:59:50",
"date_modified": "2015-04-23 21:20:32",
"num_responses": 2575,
"num_questions": 13,
"title": {
"enabled": true,
"text": "Test Example Survey"
},
"description": "This is my first survey",
"pages": [
{
"page_id": 111,
"position": 1,
"title": "Introduction Page",
"questions": [
{
"question_id": 97,
"position": 2,
"title": "How did you hear about our service?",
"type": "text_area",
"choices": []
},
{
"question_id": 1,
"position": 3,
"title": "What is your age please?",
"type": "number",
"choices": []
},
{
"question_id": 3,
"position": 5,
"title": "What kind of taco do you like?",
"type": "multiple_choice",
"choices": [
{
"choice_id": 450,
"position": 1,
"title": "Beef",
"type": "row"
},
{
"choice_id": 451,
"position": 2,
"title": "Chicken",
"type": "row"
},
{
"choice_id": 452,
"position": 3,
"title": "Fish",
"type": "row"
},
{
"choice_id": 453,
"position": 4,
"title": "Vegan",
"type": "row"
},
{
"choice_id": 475,
"position": 5,
"title": "Other (please specify)",
"type": "other"
}
]
}
]
},
{
"page_id": 117,
"position": 2,
"title": "A test title that is very very long and informative and says a lot and lot and lot",
"questions": [
{
"question_id": 868,
"position": 1,
"title": "Which benefits are important to you? Please rate from 1-5:",
"type": "rating",
"choices": [
{
"choice_id": 455,
"position": 1,
"title": "Vision Care",
"type": "row"
},
{
"choice_id": 456,
"position": 2,
"title": "Dental Care",
"type": "row"
},
{
"choice_id": 457,
"position": 3,
"title": "Medical Care",
"type": "row"
},
{
"choice_id": 458,
"position": 4,
"title": "Vacation Time",
"type": "row"
},
{
"position": 0,
"title": "1<br>Not at All Important",
"type": "col"
},
{
"position": 1,
"title": "2<br>Slightly Important",
"type": "col"
},
{
"position": 2,
"title": "3<br>Somewhat Important",
"type": "col"
},
{
"position": 3,
"title": "4<br>Very Important",
"type": "col"
},
{
"position": 4,
"title": "5<br>Super Duper Important",
"type": "col"
}
]
},
{
"question_id": 69,
"position": 2,
"title": "What schools did you attend?",
"type": "textbox_multiple",
"choices": [
{
"choice_id": 437,
"position": 1,
"title": "Grade School:",
"type": "row"
},
{
"choice_id": 438,
"position": 2,
"title": "High School:",
"type": "row"
},
{
"choice_id": 439,
"position": 3,
"title": "**blank**",
"type": "row"
},
{
"choice_id": 440,
"position": 4,
"title": "Trade School:",
"type": "row"
},
{
"choice_id": 441,
"position": 5,
"title": "University:",
"type": "row"
}
]
},
{
"question_id": 57,
"position": 3,
"title": "What is your favorite kind of ice cream?",
"type": "multiple_choice",
"choices": [
{
"choice_id": 207,
"position": 1,
"title": "Gelato",
"type": "row"
},
{
"choice_id": 208,
"position": 2,
"title": "Strawberry",
"type": "row"
},
{
"choice_id": 209,
"position": 3,
"title": "Bananas",
"type": "row"
},
{
"choice_id": 210,
"position": 4,
"title": "Cookies & Cream",
"type": "row"
}
]
},
{
"question_id": 53,
"position": 4,
"title": "What do you do in the summer time?",
"type": "text_area",
"choices": []
},
{
"question_id": 55,
"position": 5,
"title": "What is your name?",
"type": "textbox_single",
"choices": []
},
{
"question_id": 66,
"position": 6,
"title": "The following qualities are important in my: (select all that apply)",
"type": "matrix",
"choices": [
{
"choice_id": 426,
"position": 2,
"title": "Supervisor",
"type": "row"
},
{
"choice_id": 427,
"position": 3,
"title": "Peers",
"type": "row"
},
{
"position": 0,
"title": "Approachable",
"type": "col"
},
{
"position": 1,
"title": "Qualified",
"type": "col"
},
{
"position": 2,
"title": "Honest",
"type": "col"
}
]
}
]
},
{
"page_id": 1116,
"position": 3,
"title": "Burger Page",
"questions": [
{
"question_id": 477,
"position": 1,
"title": "How would you make your favorite burger?",
"type": "text_area",
"choices": []
},
{
"question_id": 984,
"position": 2,
"title": "What is your age?",
"type": "number",
"choices": []
},
{
"question_id": 676,
"position": 3,
"title": "The following items are important to me in a hamburger",
"type": "matrix",
"choices": [
{
"choice_id": 393,
"position": 1,
"title": "Bun",
"type": "row"
},
{
"choice_id": 394,
"position": 2,
"title": "Pickle",
"type": "row"
},
{
"choice_id": 395,
"position": 3,
"title": "Meat",
"type": "row"
},
{
"choice_id": 396,
"position": 4,
"title": "Ketchup",
"type": "row"
},
{
"choice_id": 397,
"position": 5,
"title": "Mustard",
"type": "row"
},
{
"position": 0,
"title": "Very important",
"type": "col"
},
{
"position": 1,
"title": "Important",
"type": "col"
},
{
"position": 2,
"title": "Not important",
"type": "col"
}
]
},
{
"question_id": 970,
"position": 4,
"title": "Is there anything else you forgot to add?",
"type": "text_area",
"choices": []
}
]
}
]
}
}
