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 Basic Authentication to prove that you are allowed access to the surveys and responses. The username is your email address/site login. The password is the API key that can be found in your account page.

For example, using curl might look like this:

curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/surveys/get_survey_details?survey_id=5278
					

API Limits

Currently, only our Premium 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:

  • textbox_single
  • textbox_multiple
  • text_area
  • number
  • multiple_choice
  • matrix
  • 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
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": "2016-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.
Example Request
						curl -u test@myemail.com:apikey https://api.surveyrock.com/sv1/distributors/get_distributor_list?survey_id=8548
					
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 '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/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_created' returns oldest first. 'sort=-date_created' 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.
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": []
}
]
}
]
}
}