{"_id":"54a30515ad78941600ca2dc0","api":{"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"url":"","auth":"required"},"githubsync":"","order":0,"type":"basic","body":"The Survata API is a [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer \"REST\") API for creating surveys and questions, and for fetching the results from running or completed surveys.\n\nAll API endpoints return resources as [JSON](http://en.wikipedia.org/wiki/JSON \"JSON\"). We use standard HTTP error codes for error handling.  Security is handled by submitting your secret API token using Basic Auth.  HTTPS must be used.\n\nFor access to the Survata API, please contact us at contact@survata.com.","hidden":false,"title":"Introduction","updates":[],"__v":4,"category":"54a30514ad78941600ca2dbe","excerpt":"","project":"54a30513ad78941600ca2dba","version":"54a30514ad78941600ca2dbd","createdAt":"2014-12-30T20:03:33.303Z","link_external":false,"link_url":"","slug":"introduction","sync_unique":"","user":"54a304d0eda4690b00ac0fe4","childrenPages":[]}

Introduction


The Survata API is a [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer "REST") API for creating surveys and questions, and for fetching the results from running or completed surveys. All API endpoints return resources as [JSON](http://en.wikipedia.org/wiki/JSON "JSON"). We use standard HTTP error codes for error handling. Security is handled by submitting your secret API token using Basic Auth. HTTPS must be used. For access to the Survata API, please contact us at contact@survata.com.
The Survata API is a [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer "REST") API for creating surveys and questions, and for fetching the results from running or completed surveys. All API endpoints return resources as [JSON](http://en.wikipedia.org/wiki/JSON "JSON"). We use standard HTTP error codes for error handling. Security is handled by submitting your secret API token using Basic Auth. HTTPS must be used. For access to the Survata API, please contact us at contact@survata.com.
{"_id":"54a32014ad78941600ca2dd8","hidden":false,"link_external":false,"project":"54a30513ad78941600ca2dba","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"url":""},"category":"54a30514ad78941600ca2dbe","createdAt":"2014-12-30T21:58:44.036Z","excerpt":"","githubsync":"","sync_unique":"","title":"Authentication","updates":[],"link_url":"","order":1,"__v":1,"type":"basic","user":"54a304d0eda4690b00ac0fe4","version":"54a30514ad78941600ca2dbd","body":"Authentication to the Survata API is done by providing your API token in the request.  Your API token is a secret, as it can be used to create and even run surveys on your behalf, so please be sure to keep it secure.\n\nAPI authentication occurs using HTTP Basic Auth. You simply provide your API token as the basic auth username. You should not provide a password.\n\nHTTPS must be used for all API requests. Calls made over plain HTTP are invalid. The Basic Auth header with your API token must be passed with every request.\n\nYour API token is available from your account page at [https://surveys.survata.com/account](https://surveys.survata.com/account \"Account\").  If you do not have an API Token, please email us at contact@survata.com.","slug":"authentication","childrenPages":[]}

Authentication


Authentication to the Survata API is done by providing your API token in the request. Your API token is a secret, as it can be used to create and even run surveys on your behalf, so please be sure to keep it secure. API authentication occurs using HTTP Basic Auth. You simply provide your API token as the basic auth username. You should not provide a password. HTTPS must be used for all API requests. Calls made over plain HTTP are invalid. The Basic Auth header with your API token must be passed with every request. Your API token is available from your account page at [https://surveys.survata.com/account](https://surveys.survata.com/account "Account"). If you do not have an API Token, please email us at contact@survata.com.
Authentication to the Survata API is done by providing your API token in the request. Your API token is a secret, as it can be used to create and even run surveys on your behalf, so please be sure to keep it secure. API authentication occurs using HTTP Basic Auth. You simply provide your API token as the basic auth username. You should not provide a password. HTTPS must be used for all API requests. Calls made over plain HTTP are invalid. The Basic Auth header with your API token must be passed with every request. Your API token is available from your account page at [https://surveys.survata.com/account](https://surveys.survata.com/account "Account"). If you do not have an API Token, please email us at contact@survata.com.
{"_id":"54a6ebd721a4791d00b636e1","version":"54a30514ad78941600ca2dbd","__v":7,"api":{"url":"","auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]}},"body":"This section will walk you through all the steps required to create a new survey, define a target audience and add a question. Please refer the documentation for the API endpoints for additional details for each step.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 1: Create a new survey\"\n}\n[/block]\nThe first step will be to create a new base survey. We'll call this one \"My first survey\".\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post('https://rest.survata.com/v1/survey/', {\\n  name: 'My first survey'\\n}, function(surveyObj) {\\n  surveyUuid = surveyObj.uuid; \\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Survey Uuid\",\n  \"body\": \"The survey uuid is a 32 character unique identifier that will be used to reference your new survey in all additional REST calls so you'll need to keep track of this value.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 2: Define the target audience\"\n}\n[/block]\nNext, you'll define the target audience for your survey. For this example, we'll specify an audience of 250 female respondents,  between 18 and 44 years of age. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post(\\\"https://rest.survata.com/v1/survey/\\\" + surveyUuid + \\\"audience/\\\", {\\n\\tsampleSize: 250,\\n  targetingReqs: [\\n  \\t{ attribute: \\\"country\\\", details: {type: \\\"us\\\", countries: []} },\\n    { attribute: \\\"age\\\", details: [\\\"18_to_24\\\", \\\"25_to_34\\\", \\\"35_to_44\\\"] },\\n    { attribute: \\\"gender\\\", details: [\\\"female\\\"] }\\n  ]\\n}, function(audienceData) {\\n  \\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 3: Create a survey question\"\n}\n[/block]\nNow, you'll add a question to your survey.  Let's ask respondents what their favorite color is! We'll also specify \"shuffle\" as the ordering so type so that the answer choices will be presented to respondents in an random order. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/question/', {\\n\\ttype: 'singleSelect',\\n  statement: {\\n    text: 'What is your favorite color?'\\n  },\\n  details: {\\n  \\tchoices: [\\n      {text: 'Red'},\\n      {text: 'Blue'},\\n      {text: 'Green'}\\n    ],\\n    order: 'shuffle', \\n    displayType: 'normal',\\n    responseType: 'text'\\n  }\\n}, function(questionData) {\\n  // your code here\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Step 4: Submit or Approve your survey\"\n}\n[/block]\nWhen you've finished building your survey and are ready to proceed, you can either \"submit\" or \"approve\" your survey. Submitting a survey notifies our survey analyst team that you're finished building your survey and enters into the review process.  Approving a survey (for approved API partners) bypasses the review process and notifies Survata that your survey is ready to run immediately.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// or submit your survey to be reviewed by one of our analysts\\n$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/submit/', {}, function(surveyData) {\\n  // your code here\\n});\\n\\n// submit and approve your survey to run immediately on our network\\n$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/approve/', {}, function(surveyData) {\\n  // your code here\\n});\\n\\n\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","link_url":"","title":"Tutorial","type":"basic","sync_unique":"","user":"54a304d0eda4690b00ac0fe4","category":"54a30514ad78941600ca2dbe","createdAt":"2015-01-02T19:04:55.905Z","githubsync":"","hidden":false,"order":2,"project":"54a30513ad78941600ca2dba","excerpt":"A step-by-step guide to creating a basic survey","link_external":false,"slug":"tutorial","updates":[],"childrenPages":[]}

Tutorial

A step-by-step guide to creating a basic survey

This section will walk you through all the steps required to create a new survey, define a target audience and add a question. Please refer the documentation for the API endpoints for additional details for each step. [block:api-header] { "type": "basic", "title": "Step 1: Create a new survey" } [/block] The first step will be to create a new base survey. We'll call this one "My first survey". [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/', {\n name: 'My first survey'\n}, function(surveyObj) {\n surveyUuid = surveyObj.uuid; \n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:callout] { "type": "warning", "title": "Survey Uuid", "body": "The survey uuid is a 32 character unique identifier that will be used to reference your new survey in all additional REST calls so you'll need to keep track of this value." } [/block] [block:api-header] { "type": "basic", "title": "Step 2: Define the target audience" } [/block] Next, you'll define the target audience for your survey. For this example, we'll specify an audience of 250 female respondents, between 18 and 44 years of age. [block:code] { "codes": [ { "code": "$.post(\"https://rest.survata.com/v1/survey/\" + surveyUuid + \"audience/\", {\n\tsampleSize: 250,\n targetingReqs: [\n \t{ attribute: \"country\", details: {type: \"us\", countries: []} },\n { attribute: \"age\", details: [\"18_to_24\", \"25_to_34\", \"35_to_44\"] },\n { attribute: \"gender\", details: [\"female\"] }\n ]\n}, function(audienceData) {\n \n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:api-header] { "type": "basic", "title": "Step 3: Create a survey question" } [/block] Now, you'll add a question to your survey. Let's ask respondents what their favorite color is! We'll also specify "shuffle" as the ordering so type so that the answer choices will be presented to respondents in an random order. [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/question/', {\n\ttype: 'singleSelect',\n statement: {\n text: 'What is your favorite color?'\n },\n details: {\n \tchoices: [\n {text: 'Red'},\n {text: 'Blue'},\n {text: 'Green'}\n ],\n order: 'shuffle', \n displayType: 'normal',\n responseType: 'text'\n }\n}, function(questionData) {\n // your code here\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Step 4: Submit or Approve your survey" } [/block] When you've finished building your survey and are ready to proceed, you can either "submit" or "approve" your survey. Submitting a survey notifies our survey analyst team that you're finished building your survey and enters into the review process. Approving a survey (for approved API partners) bypasses the review process and notifies Survata that your survey is ready to run immediately. [block:code] { "codes": [ { "code": "// or submit your survey to be reviewed by one of our analysts\n$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/submit/', {}, function(surveyData) {\n // your code here\n});\n\n// submit and approve your survey to run immediately on our network\n$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/approve/', {}, function(surveyData) {\n // your code here\n});\n\n", "language": "javascript", "name": "jQuery" } ] } [/block] [block:code] { "codes": [ { "code": "", "language": "text" } ] } [/block]
This section will walk you through all the steps required to create a new survey, define a target audience and add a question. Please refer the documentation for the API endpoints for additional details for each step. [block:api-header] { "type": "basic", "title": "Step 1: Create a new survey" } [/block] The first step will be to create a new base survey. We'll call this one "My first survey". [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/', {\n name: 'My first survey'\n}, function(surveyObj) {\n surveyUuid = surveyObj.uuid; \n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:callout] { "type": "warning", "title": "Survey Uuid", "body": "The survey uuid is a 32 character unique identifier that will be used to reference your new survey in all additional REST calls so you'll need to keep track of this value." } [/block] [block:api-header] { "type": "basic", "title": "Step 2: Define the target audience" } [/block] Next, you'll define the target audience for your survey. For this example, we'll specify an audience of 250 female respondents, between 18 and 44 years of age. [block:code] { "codes": [ { "code": "$.post(\"https://rest.survata.com/v1/survey/\" + surveyUuid + \"audience/\", {\n\tsampleSize: 250,\n targetingReqs: [\n \t{ attribute: \"country\", details: {type: \"us\", countries: []} },\n { attribute: \"age\", details: [\"18_to_24\", \"25_to_34\", \"35_to_44\"] },\n { attribute: \"gender\", details: [\"female\"] }\n ]\n}, function(audienceData) {\n \n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:api-header] { "type": "basic", "title": "Step 3: Create a survey question" } [/block] Now, you'll add a question to your survey. Let's ask respondents what their favorite color is! We'll also specify "shuffle" as the ordering so type so that the answer choices will be presented to respondents in an random order. [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/question/', {\n\ttype: 'singleSelect',\n statement: {\n text: 'What is your favorite color?'\n },\n details: {\n \tchoices: [\n {text: 'Red'},\n {text: 'Blue'},\n {text: 'Green'}\n ],\n order: 'shuffle', \n displayType: 'normal',\n responseType: 'text'\n }\n}, function(questionData) {\n // your code here\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Step 4: Submit or Approve your survey" } [/block] When you've finished building your survey and are ready to proceed, you can either "submit" or "approve" your survey. Submitting a survey notifies our survey analyst team that you're finished building your survey and enters into the review process. Approving a survey (for approved API partners) bypasses the review process and notifies Survata that your survey is ready to run immediately. [block:code] { "codes": [ { "code": "// or submit your survey to be reviewed by one of our analysts\n$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/submit/', {}, function(surveyData) {\n // your code here\n});\n\n// submit and approve your survey to run immediately on our network\n$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/approve/', {}, function(surveyData) {\n // your code here\n});\n\n", "language": "javascript", "name": "jQuery" } ] } [/block] [block:code] { "codes": [ { "code": "", "language": "text" } ] } [/block]
{"_id":"54a32938ad78941600ca2ddd","category":"54a30514ad78941600ca2dbe","order":3,"user":"54a304d0eda4690b00ac0fe4","createdAt":"2014-12-30T22:37:44.591Z","githubsync":"","link_url":"","sync_unique":"","title":"Errors","type":"basic","updates":[],"api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"url":""},"excerpt":"","hidden":false,"project":"54a30513ad78941600ca2dba","version":"54a30514ad78941600ca2dbd","__v":3,"body":"The Survata API uses HTTP response codes to indicate success and failure.  In addition, in an error case, we return a JSON error document.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP response code summary\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Status\",\n    \"h-1\": \"Meaning\",\n    \"0-0\": \"200 OK\",\n    \"0-1\": \"The request has completed successfully.\",\n    \"1-0\": \"404 Not Found\",\n    \"1-1\": \"The resource requested does not exist.\",\n    \"3-0\": \"401 Not Authorized\",\n    \"3-1\": \"You do not have the required permissions for this API call.\",\n    \"4-0\": \"50x Server errors\",\n    \"4-1\": \"A problem has occurred in Survata's system.  Please notify us of the issue.\",\n    \"2-0\": \"400 Bad Request\",\n    \"2-1\": \"The user has an error in their request.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Survata Error JSON\"\n}\n[/block]\nError documents are passed along with the codes specified above.  They have the following form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"error\\\":true,\\\"code\\\":100,\\\"msg\\\":\\\"Resource does not exist\\\"}\",\n      \"language\": \"json\",\n      \"name\": \"Error document example\"\n    }\n  ]\n}\n[/block]\nThe list of possible codes and messages is as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Msg\",\n    \"0-0\": \"100\",\n    \"0-1\": \"Resource does not exist\",\n    \"1-0\": \"101\",\n    \"1-1\": \"Invalid input\",\n    \"2-0\": \"102\",\n    \"2-1\": \"Not authorized\",\n    \"3-0\": \"105\",\n    \"3-1\": \"Object already exists\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","link_external":false,"slug":"errors","childrenPages":[]}

Errors


The Survata API uses HTTP response codes to indicate success and failure. In addition, in an error case, we return a JSON error document. [block:api-header] { "type": "basic", "title": "HTTP response code summary" } [/block] [block:parameters] { "data": { "h-0": "Status", "h-1": "Meaning", "0-0": "200 OK", "0-1": "The request has completed successfully.", "1-0": "404 Not Found", "1-1": "The resource requested does not exist.", "3-0": "401 Not Authorized", "3-1": "You do not have the required permissions for this API call.", "4-0": "50x Server errors", "4-1": "A problem has occurred in Survata's system. Please notify us of the issue.", "2-0": "400 Bad Request", "2-1": "The user has an error in their request." }, "cols": 2, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "Survata Error JSON" } [/block] Error documents are passed along with the codes specified above. They have the following form: [block:code] { "codes": [ { "code": "{\"error\":true,\"code\":100,\"msg\":\"Resource does not exist\"}", "language": "json", "name": "Error document example" } ] } [/block] The list of possible codes and messages is as follows: [block:parameters] { "data": { "h-0": "Code", "h-1": "Msg", "0-0": "100", "0-1": "Resource does not exist", "1-0": "101", "1-1": "Invalid input", "2-0": "102", "2-1": "Not authorized", "3-0": "105", "3-1": "Object already exists" }, "cols": 2, "rows": 4 } [/block]
The Survata API uses HTTP response codes to indicate success and failure. In addition, in an error case, we return a JSON error document. [block:api-header] { "type": "basic", "title": "HTTP response code summary" } [/block] [block:parameters] { "data": { "h-0": "Status", "h-1": "Meaning", "0-0": "200 OK", "0-1": "The request has completed successfully.", "1-0": "404 Not Found", "1-1": "The resource requested does not exist.", "3-0": "401 Not Authorized", "3-1": "You do not have the required permissions for this API call.", "4-0": "50x Server errors", "4-1": "A problem has occurred in Survata's system. Please notify us of the issue.", "2-0": "400 Bad Request", "2-1": "The user has an error in their request." }, "cols": 2, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "Survata Error JSON" } [/block] Error documents are passed along with the codes specified above. They have the following form: [block:code] { "codes": [ { "code": "{\"error\":true,\"code\":100,\"msg\":\"Resource does not exist\"}", "language": "json", "name": "Error document example" } ] } [/block] The list of possible codes and messages is as follows: [block:parameters] { "data": { "h-0": "Code", "h-1": "Msg", "0-0": "100", "0-1": "Resource does not exist", "1-0": "101", "1-1": "Invalid input", "2-0": "102", "2-1": "Not authorized", "3-0": "105", "3-1": "Object already exists" }, "cols": 2, "rows": 4 } [/block]
{"_id":"54a3064ceda4690b00ac0fe6","editedParams2":true,"githubsync":"","order":0,"category":"54a30568ad78941600ca2dc1","createdAt":"2014-12-30T20:08:44.541Z","sync_unique":"","title":"/survey","type":"post","excerpt":"Create a new survey","link_url":"","editedParams":true,"project":"54a30513ad78941600ca2dba","slug":"survey","updates":[],"body":"Post to /survey to create a new survey. You may give a descriptive name to the survey by optionally passing a 'name' param along with the POST call.  You'll need to store the survey uuid from the response data for use in any additional API calls referencing this survey, such as specifying the targeting audience and creating questions.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post('https://rest.survata.com/v1/survey/', {\\n  name: 'My survey'\\n}, function(surveyObj) {\\n  // need to store the uuid for additional API calls for this survey\\n  surveyUuid = surveyObj.uuid; \\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","hidden":false,"link_external":false,"user":"54a304d0eda4690b00ac0fe4","version":"54a30514ad78941600ca2dbd","__v":4,"api":{"url":"/survey","auth":"required","method":"post","params":[{"_id":"54a339e2ad78941600ca2de9","required":false,"desc":"A descriptive name for the survey (optional)","default":"","type":"string","name":"name","in":"body"}],"results":{"codes":[{"name":"","code":"{\n  \"id\":1,\n  \"uuid\":\"8015173eb20046fb9063c1cd4e2ec852\",\n  \"name\":\"My survey!\"\n}","language":"json","status":200},{"language":"json","status":400,"name":"","code":"{\n\t\"error\": true,\n  \"code\": 100,\n  \"msg\": \"Invalid request\"\n}"}]}},"childrenPages":[]}

post/survey

Create a new survey

Body Params

name:
string
A descriptive name for the survey (optional)
Post to /survey to create a new survey. You may give a descriptive name to the survey by optionally passing a 'name' param along with the POST call. You'll need to store the survey uuid from the response data for use in any additional API calls referencing this survey, such as specifying the targeting audience and creating questions. [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/', {\n name: 'My survey'\n}, function(surveyObj) {\n // need to store the uuid for additional API calls for this survey\n surveyUuid = surveyObj.uuid; \n});", "language": "javascript" } ] } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



Post to /survey to create a new survey. You may give a descriptive name to the survey by optionally passing a 'name' param along with the POST call. You'll need to store the survey uuid from the response data for use in any additional API calls referencing this survey, such as specifying the targeting audience and creating questions. [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/', {\n name: 'My survey'\n}, function(surveyObj) {\n // need to store the uuid for additional API calls for this survey\n surveyUuid = surveyObj.uuid; \n});", "language": "javascript" } ] } [/block]
{"_id":"54a32091eda4690b00ac0ff6","hidden":false,"user":"54a304d0eda4690b00ac0fe4","version":"54a30514ad78941600ca2dbd","__v":0,"sync_unique":"","type":"post","updates":[],"category":"54a30568ad78941600ca2dc1","excerpt":"Define the target audience of the survey","githubsync":"","link_url":"","project":"54a30513ad78941600ca2dba","slug":"surveysurvey_idaudience","order":1,"title":"/survey/[survey_uuid]/audience","api":{"auth":"required","method":"post","params":[{"in":"body","_id":"54a32091eda4690b00ac0ff8","default":"","desc":"Number of respondents desired","name":"sampleSize","required":true,"type":"int"},{"name":"targetingReqs","required":true,"type":"object","in":"body","_id":"54a32091eda4690b00ac0ff7","default":"","desc":"Array of target audience attributes (JSON)"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"id\": 1,\n  \"uuid\": \"2e517fe5-0def-4097-ae56-694fcb647c53\",\n  \"sampleSize\": 400,\n  \"targetingReqs\": [\n    { \n      attribute: \"country\",\n      details: {type: \"us\", countries: []}\n    },\n    {\n      attribute: \"age\",\n     \tdetails: [\"18_to_24\", \"25_to_34\", \"35_to_44\"]\n    },\n    { \n      attribute: \"gender\",\n      details: [\"male\"]\n    },\n    { \n      attribute: \"region\",\n      details: [\"CA\", \"CO\"]\n    },\n    { \n      attribute: \"metro\",\n      details: [\"den\", \"la\", \"sfo\", \"sd\"]\n    },\n    { \n      attribute: \"operatingSystem\",\n      details: [\"macos\", \"windows\"]\n    },\n    { \n      attribute: \"device\",\n      details: [\"desktop\", \"tablet\"]\n    },\n    { \n      attribute: \"webBrowser\",\n      details: [\"chrome\", \"firefox\", \"safari\"]\n    }\n  ],\n  \"screeningQuestions\":[]\n}","name":""},{"status":400,"language":"json","code":"{\n}","name":""}]},"url":"/survey/[survey_uuid]/audience"},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"In the example above, please replace *[survey_uuid]* with the 32 character unique identifier string for your survey.\"\n}\n[/block]\nYou can define the target audience for the survey by providing the desired sample size and optional age and gender targeting. (Please note that the default geographic targeting JSON must be passed and is not configurable via the Survata API at this time. See the code block below)\n\nThe example below defines a target audience of 100 male US respondents between the ages of 18 and 44, living in California or Colorado and more specifically in the Denver, Los Angeles, San Francisco and San Diego DMAs. Additional targeting has been specified for operating system, device type and web browser. Please see the info blocks below for more information about our targeting attributes. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post(\\\"https://rest.survata.com/v1/survey/\\\" + surveyUuid + \\\"/audience/\\\", {\\n\\tsampleSize: 100,\\n  targetingReqs: [\\n    // this default geographic targeting attribute is required\\n  \\t{ attribute: \\\"country\\\", details: {type: \\\"us\\\", countries: []} },\\n    \\n    // these additional targeting attributes are optional\\n    { attribute: \\\"age\\\", details: [\\\"18_to_24\\\", \\\"25_to_34\\\", \\\"35_to_44\\\"] },\\n    { attribute: \\\"gender\\\", details: [\\\"male\\\"] },\\n    { attribute: \\\"region\\\", details: [\\\"CA\\\", \\\"CO\\\"] },\\n    { attribute: \\\"metro\\\", details: [\\\"den\\\", \\\"la\\\", \\\"sfo\\\", \\\"sd\\\"] },\\n    { attribute: \\\"operatingSystem\\\",details: [\\\"macos\\\",\\\"windows\\\"] },\\n    { attribute: \\\"device\\\", details: [\\\"desktop\\\", \\\"tablet\\\"] },\\n    { attribute: \\\"webBrowser\\\", details: [\\\"chrome\\\", \\\"firefox\\\", \\\"safari\\\"] }\\n  ]\\n}, function(data) {\\n  alert(data);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Gender targeting\",\n  \"body\": \"To specify an all male or all female audience, include one of the following:\\n{ attribute: \\\"gender\\\", details: [\\\"male\\\"] } or { attribute: \\\"gender\\\", details: [\\\"female\\\"] }\\n\\nFor both genders, simple exclude this targeting criteria.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Age targeting\",\n  \"body\": \"Survata support age targeting for the following ranges and is configurable by providing an array of the desired age ranges.  Our supported age ranges are:\\n\\n'13_to_17', '18_to_24', '25_to_34', '35-44', '45_to_54', '55_to_64', '65_and_over'\\n\\nPlease note that we cannot survey respondents under 13 years of age.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Region (state) targeting\",\n  \"body\": \"Survata supports state targeting and is configurable by providing an array of the desired state codes.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Metro (DMA) targeting\",\n  \"body\": \"Survata supports DMA targeting and is configurable by providing an array of the desired DMA codes. Please contact us for a list of supported DMAs.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Technographic  (OS, Device, Browser) targeting\",\n  \"body\": \"Survata supports technographic targeting for operating systems, browsers and devices. \\n\\nOperating system codes: \\\"macos\\\", \\\"windows\\\", \\\"ios\\\", \\\"android\\\"\\nBrowser codes: \\\"chrome\\\", \\\"firefox\\\", \\\"ie\\\", \\\"safari\\\", \\\"other\\\"\\nDevice codes: \\\"desktop\\\", \\\"mobile_phone\\\", \\\"tablet\\\"\\n\\nPlease note that we don't differentiate between a desktop and a laptop so both are categorized under \\\"desktop\\\".\"\n}\n[/block]","createdAt":"2014-12-30T22:00:49.793Z","editedParams":true,"editedParams2":true,"link_external":false,"childrenPages":[]}

post/survey/[survey_uuid]/audience

Define the target audience of the survey

Body Params

sampleSize:
required
integer
Number of respondents desired
targetingReqs:
required
object
Array of target audience attributes (JSON)
[block:callout] { "type": "info", "title": "", "body": "In the example above, please replace *[survey_uuid]* with the 32 character unique identifier string for your survey." } [/block] You can define the target audience for the survey by providing the desired sample size and optional age and gender targeting. (Please note that the default geographic targeting JSON must be passed and is not configurable via the Survata API at this time. See the code block below) The example below defines a target audience of 100 male US respondents between the ages of 18 and 44, living in California or Colorado and more specifically in the Denver, Los Angeles, San Francisco and San Diego DMAs. Additional targeting has been specified for operating system, device type and web browser. Please see the info blocks below for more information about our targeting attributes. [block:code] { "codes": [ { "code": "$.post(\"https://rest.survata.com/v1/survey/\" + surveyUuid + \"/audience/\", {\n\tsampleSize: 100,\n targetingReqs: [\n // this default geographic targeting attribute is required\n \t{ attribute: \"country\", details: {type: \"us\", countries: []} },\n \n // these additional targeting attributes are optional\n { attribute: \"age\", details: [\"18_to_24\", \"25_to_34\", \"35_to_44\"] },\n { attribute: \"gender\", details: [\"male\"] },\n { attribute: \"region\", details: [\"CA\", \"CO\"] },\n { attribute: \"metro\", details: [\"den\", \"la\", \"sfo\", \"sd\"] },\n { attribute: \"operatingSystem\",details: [\"macos\",\"windows\"] },\n { attribute: \"device\", details: [\"desktop\", \"tablet\"] },\n { attribute: \"webBrowser\", details: [\"chrome\", \"firefox\", \"safari\"] }\n ]\n}, function(data) {\n alert(data);\n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:callout] { "type": "info", "title": "Gender targeting", "body": "To specify an all male or all female audience, include one of the following:\n{ attribute: \"gender\", details: [\"male\"] } or { attribute: \"gender\", details: [\"female\"] }\n\nFor both genders, simple exclude this targeting criteria." } [/block] [block:callout] { "type": "info", "title": "Age targeting", "body": "Survata support age targeting for the following ranges and is configurable by providing an array of the desired age ranges. Our supported age ranges are:\n\n'13_to_17', '18_to_24', '25_to_34', '35-44', '45_to_54', '55_to_64', '65_and_over'\n\nPlease note that we cannot survey respondents under 13 years of age." } [/block] [block:callout] { "type": "info", "title": "Region (state) targeting", "body": "Survata supports state targeting and is configurable by providing an array of the desired state codes." } [/block] [block:callout] { "type": "info", "title": "Metro (DMA) targeting", "body": "Survata supports DMA targeting and is configurable by providing an array of the desired DMA codes. Please contact us for a list of supported DMAs." } [/block] [block:callout] { "type": "info", "title": "Technographic (OS, Device, Browser) targeting", "body": "Survata supports technographic targeting for operating systems, browsers and devices. \n\nOperating system codes: \"macos\", \"windows\", \"ios\", \"android\"\nBrowser codes: \"chrome\", \"firefox\", \"ie\", \"safari\", \"other\"\nDevice codes: \"desktop\", \"mobile_phone\", \"tablet\"\n\nPlease note that we don't differentiate between a desktop and a laptop so both are categorized under \"desktop\"." } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:callout] { "type": "info", "title": "", "body": "In the example above, please replace *[survey_uuid]* with the 32 character unique identifier string for your survey." } [/block] You can define the target audience for the survey by providing the desired sample size and optional age and gender targeting. (Please note that the default geographic targeting JSON must be passed and is not configurable via the Survata API at this time. See the code block below) The example below defines a target audience of 100 male US respondents between the ages of 18 and 44, living in California or Colorado and more specifically in the Denver, Los Angeles, San Francisco and San Diego DMAs. Additional targeting has been specified for operating system, device type and web browser. Please see the info blocks below for more information about our targeting attributes. [block:code] { "codes": [ { "code": "$.post(\"https://rest.survata.com/v1/survey/\" + surveyUuid + \"/audience/\", {\n\tsampleSize: 100,\n targetingReqs: [\n // this default geographic targeting attribute is required\n \t{ attribute: \"country\", details: {type: \"us\", countries: []} },\n \n // these additional targeting attributes are optional\n { attribute: \"age\", details: [\"18_to_24\", \"25_to_34\", \"35_to_44\"] },\n { attribute: \"gender\", details: [\"male\"] },\n { attribute: \"region\", details: [\"CA\", \"CO\"] },\n { attribute: \"metro\", details: [\"den\", \"la\", \"sfo\", \"sd\"] },\n { attribute: \"operatingSystem\",details: [\"macos\",\"windows\"] },\n { attribute: \"device\", details: [\"desktop\", \"tablet\"] },\n { attribute: \"webBrowser\", details: [\"chrome\", \"firefox\", \"safari\"] }\n ]\n}, function(data) {\n alert(data);\n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:callout] { "type": "info", "title": "Gender targeting", "body": "To specify an all male or all female audience, include one of the following:\n{ attribute: \"gender\", details: [\"male\"] } or { attribute: \"gender\", details: [\"female\"] }\n\nFor both genders, simple exclude this targeting criteria." } [/block] [block:callout] { "type": "info", "title": "Age targeting", "body": "Survata support age targeting for the following ranges and is configurable by providing an array of the desired age ranges. Our supported age ranges are:\n\n'13_to_17', '18_to_24', '25_to_34', '35-44', '45_to_54', '55_to_64', '65_and_over'\n\nPlease note that we cannot survey respondents under 13 years of age." } [/block] [block:callout] { "type": "info", "title": "Region (state) targeting", "body": "Survata supports state targeting and is configurable by providing an array of the desired state codes." } [/block] [block:callout] { "type": "info", "title": "Metro (DMA) targeting", "body": "Survata supports DMA targeting and is configurable by providing an array of the desired DMA codes. Please contact us for a list of supported DMAs." } [/block] [block:callout] { "type": "info", "title": "Technographic (OS, Device, Browser) targeting", "body": "Survata supports technographic targeting for operating systems, browsers and devices. \n\nOperating system codes: \"macos\", \"windows\", \"ios\", \"android\"\nBrowser codes: \"chrome\", \"firefox\", \"ie\", \"safari\", \"other\"\nDevice codes: \"desktop\", \"mobile_phone\", \"tablet\"\n\nPlease note that we don't differentiate between a desktop and a laptop so both are categorized under \"desktop\"." } [/block]
{"_id":"54c683592b94bb19003d3474","link_external":false,"slug":"audienceaudience_uuidquestion","updates":[],"user":"54a304d0eda4690b00ac0fe4","category":"54a30568ad78941600ca2dc1","editedParams2":true,"excerpt":"Create a screening question","link_url":"","order":2,"version":"54a30514ad78941600ca2dbd","createdAt":"2015-01-26T18:11:37.441Z","editedParams":true,"hidden":false,"githubsync":"","sync_unique":"","api":{"auth":"required","method":"post","params":[{"desc":"Question type (\"singleSelect\", \"multiSelect\", etc..)","default":"","type":"string","name":"type","in":"body","_id":"54c683592b94bb19003d3475","required":false},{"type":"string","name":"statement[text]","in":"body","_id":"54c69e96f0320f0d00ac9c22","required":false,"desc":"The question statement (i.e. \"How often do you drink coffee?\")","default":""},{"_id":"54c69e96f0320f0d00ac9c21","required":false,"desc":"Details JSON","default":"","type":"object","name":"details","in":"body"}],"results":{"codes":[{"language":"json","code":"{\n    \"id\":1,\n    \"uuid\":\"9434c440-9248-4beb-ac22-715ac48f7fba\",\n    \"type\":\"singleSelect\",\n    \"statement\": {\n        \"text\":\"How often do you drink coffee?\"\n    },\n    \"details\": {\n        \"specifyOptionEnabled\":false,\n        \"hasNoneOfTheAbove\":false,\n        \"order\":\"fixed\",\n        \"minSelected\":null,\n        \"displayType\":\"normal\",\n        \"choices\":[\n            {text: 'Every day'},\n      \t\t\t{text: 'A few times a week'},\n      \t\t\t{text: 'A few times a month'},\n      \t\t\t{text: 'Rarely', disqualifier: true},\n      \t\t\t{text: 'Never', disqualifier: true}\n        ],\n        \"responseType\":\"text\",\n        \"choicesToDisplay\":null,\n        \"maxSelected\":null\n    },\n  \t\"screener\":true\n}","name":"","status":200},{"status":400,"language":"json","code":"{}","name":""}]},"url":"/audience/[audience_uuid]/question"},"body":"You can create a new screening question by posting to /audience/[audience_uuid]/question with the question type, question statement, and details JSON. Please note that we currently support only 'singleSelect' question types via the Survata API. We will roll out additional question types as we expand the capabilities of our API. See the code block below for an example of a new single select question with five answer choices. Note that the last two choices have the additional parameter \"disqualifer\": true.  This denotes that respondents choosing these answer choices will be screened out of the survey.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please replace *[audience_uuid]* with the actual 32 character unique identifier string for your audience.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post('https://rest.survata.com/v1/audience/' + audienceUuid + '/question/', {\\n\\ttype: 'singleSelect',\\n  statement: {\\n    text: 'How often do you drink coffee??'\\n  },\\n  details: {\\n  \\tchoices: [\\n      {text: 'Every day'},\\n      {text: 'A few times a week'},\\n      {text: 'A few times a month'},\\n      {text: 'Rarely', disqualifier: true},\\n      {text: 'Never', disqualifier: true}\\n    ],\\n    order: 'fixed', // configurable (see below)\\n    displayType: 'normal', // required and non-configurable\\n    responseType: 'text' // required and non-configurable\\n  }\\n}, function(questionData) {\\n  // your code here\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]","type":"post","__v":1,"project":"54a30513ad78941600ca2dba","title":"/audience/[audience_uuid]/question","childrenPages":[]}

post/audience/[audience_uuid]/question

Create a screening question

Body Params

type:
string
Question type ("singleSelect", "multiSelect", etc..)
statement[text]:
string
The question statement (i.e. "How often do you drink coffee?")
details:
object
Details JSON
You can create a new screening question by posting to /audience/[audience_uuid]/question with the question type, question statement, and details JSON. Please note that we currently support only 'singleSelect' question types via the Survata API. We will roll out additional question types as we expand the capabilities of our API. See the code block below for an example of a new single select question with five answer choices. Note that the last two choices have the additional parameter "disqualifer": true. This denotes that respondents choosing these answer choices will be screened out of the survey. [block:callout] { "type": "info", "body": "Please replace *[audience_uuid]* with the actual 32 character unique identifier string for your audience." } [/block] [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/audience/' + audienceUuid + '/question/', {\n\ttype: 'singleSelect',\n statement: {\n text: 'How often do you drink coffee??'\n },\n details: {\n \tchoices: [\n {text: 'Every day'},\n {text: 'A few times a week'},\n {text: 'A few times a month'},\n {text: 'Rarely', disqualifier: true},\n {text: 'Never', disqualifier: true}\n ],\n order: 'fixed', // configurable (see below)\n displayType: 'normal', // required and non-configurable\n responseType: 'text' // required and non-configurable\n }\n}, function(questionData) {\n // your code here\n});", "language": "javascript", "name": "jQuery" } ] } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



You can create a new screening question by posting to /audience/[audience_uuid]/question with the question type, question statement, and details JSON. Please note that we currently support only 'singleSelect' question types via the Survata API. We will roll out additional question types as we expand the capabilities of our API. See the code block below for an example of a new single select question with five answer choices. Note that the last two choices have the additional parameter "disqualifer": true. This denotes that respondents choosing these answer choices will be screened out of the survey. [block:callout] { "type": "info", "body": "Please replace *[audience_uuid]* with the actual 32 character unique identifier string for your audience." } [/block] [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/audience/' + audienceUuid + '/question/', {\n\ttype: 'singleSelect',\n statement: {\n text: 'How often do you drink coffee??'\n },\n details: {\n \tchoices: [\n {text: 'Every day'},\n {text: 'A few times a week'},\n {text: 'A few times a month'},\n {text: 'Rarely', disqualifier: true},\n {text: 'Never', disqualifier: true}\n ],\n order: 'fixed', // configurable (see below)\n displayType: 'normal', // required and non-configurable\n responseType: 'text' // required and non-configurable\n }\n}, function(questionData) {\n // your code here\n});", "language": "javascript", "name": "jQuery" } ] } [/block]
{"_id":"54a31f4feda4690b00ac0ff2","link_url":"","project":"54a30513ad78941600ca2dba","type":"post","api":{"auth":"required","method":"post","params":[{"required":false,"desc":"Question type (\"singleSelect\", \"multiSelect\", etc..)","default":"","type":"string","name":"type","in":"body","_id":"54a31f4feda4690b00ac0ff5"},{"desc":"The question statement (i.e. \"What is your favorite color?\")","default":"","type":"string","name":"statement[text]","in":"body","_id":"54a31f4feda4690b00ac0ff4","required":false},{"default":"","type":"object","name":"details","in":"body","_id":"54a31f4feda4690b00ac0ff3","required":false,"desc":"Details JSON"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"id\":1,\n    \"uuid\":\"9434c440-9248-4beb-ac22-715ac48f7fba\",\n    \"type\":\"singleSelect\",\n    \"statement\": {\n        \"text\":\"What is your favorite color?\",\n      \t\"image\": {\n          \"url\": \"http://imgur.com/xxx\",\n          \"position\": \"bottom\"\n        }\n    },\n    \"details\": {\n        \"specifyOptionEnabled\":false,\n        \"hasNoneOfTheAbove\":false,\n        \"order\":\"fixed\",\n        \"minSelected\":null,\n        \"displayType\":\"normal\",\n        \"choices\":[\n            {\"text\":\"Red\"},\n            {\"text\":\"Blue\"},\n            {\"text\":\"Green\"}],\n        \"responseType\":\"text\",\n        \"choicesToDisplay\":null,\n        \"maxSelected\":null\n    },\n  \t\"screener\":false\n}","name":""},{"code":"{}","name":"","status":400,"language":"json"}]},"url":"/survey/[survey_uuid]/question"},"body":"You can create a new survey question by posting to /survey/[survey_uuid]/question with the question type, question statement, and details JSON. Please note that we currently support only 'singleSelect' question types via the Survata API. We will roll out additional question types as we expand the capabilities of our API. See the code block below for an example of a new single select question with three answer choices and an (optional) image below the question statement. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/question/', {\\n\\ttype: 'singleSelect',\\n  statement: {\\n    text: 'What is your favorite color?',\\n    image: {\\n      url: 'http://imgur.com/xxx',\\n      position: 'bottom',\\n    }\\n  },\\n  details: {\\n  \\tchoices: [\\n      {text: 'Red'},\\n      {text: 'Blue'},\\n      {text: 'Green'}\\n    ],\\n    order: 'fixed', // configurable (see below)\\n    displayType: 'normal', // required and non-configurable\\n    responseType: 'text' // required and non-configurable\\n  }\\n}, function(questionData) {\\n  // your code here\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Optional question configuration\",\n  \"body\": \"Survata provides three options for displaying answer choices:\\n\\n'fixed': Answer choices will be displayed in the order in which they are specified\\n'shuffle': Answer choices will be randomly shuffled\\n'random-v': Answer choices will be randomly be displayed in reverse order\"\n}\n[/block]","category":"54a30568ad78941600ca2dc1","title":"/survey/[survey_uuid]/question","updates":[],"user":"54a304d0eda4690b00ac0fe4","hidden":false,"slug":"question","sync_unique":"","version":"54a30514ad78941600ca2dbd","__v":0,"link_external":false,"order":3,"excerpt":"Add a question to a survey","githubsync":"","createdAt":"2014-12-30T21:55:27.754Z","editedParams":true,"editedParams2":true,"childrenPages":[]}

post/survey/[survey_uuid]/question

Add a question to a survey

Body Params

type:
string
Question type ("singleSelect", "multiSelect", etc..)
statement[text]:
string
The question statement (i.e. "What is your favorite color?")
details:
object
Details JSON
You can create a new survey question by posting to /survey/[survey_uuid]/question with the question type, question statement, and details JSON. Please note that we currently support only 'singleSelect' question types via the Survata API. We will roll out additional question types as we expand the capabilities of our API. See the code block below for an example of a new single select question with three answer choices and an (optional) image below the question statement. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block] [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/question/', {\n\ttype: 'singleSelect',\n statement: {\n text: 'What is your favorite color?',\n image: {\n url: 'http://imgur.com/xxx',\n position: 'bottom',\n }\n },\n details: {\n \tchoices: [\n {text: 'Red'},\n {text: 'Blue'},\n {text: 'Green'}\n ],\n order: 'fixed', // configurable (see below)\n displayType: 'normal', // required and non-configurable\n responseType: 'text' // required and non-configurable\n }\n}, function(questionData) {\n // your code here\n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:callout] { "type": "info", "title": "Optional question configuration", "body": "Survata provides three options for displaying answer choices:\n\n'fixed': Answer choices will be displayed in the order in which they are specified\n'shuffle': Answer choices will be randomly shuffled\n'random-v': Answer choices will be randomly be displayed in reverse order" } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



You can create a new survey question by posting to /survey/[survey_uuid]/question with the question type, question statement, and details JSON. Please note that we currently support only 'singleSelect' question types via the Survata API. We will roll out additional question types as we expand the capabilities of our API. See the code block below for an example of a new single select question with three answer choices and an (optional) image below the question statement. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block] [block:code] { "codes": [ { "code": "$.post('https://rest.survata.com/v1/survey/' + surveyUuid + '/question/', {\n\ttype: 'singleSelect',\n statement: {\n text: 'What is your favorite color?',\n image: {\n url: 'http://imgur.com/xxx',\n position: 'bottom',\n }\n },\n details: {\n \tchoices: [\n {text: 'Red'},\n {text: 'Blue'},\n {text: 'Green'}\n ],\n order: 'fixed', // configurable (see below)\n displayType: 'normal', // required and non-configurable\n responseType: 'text' // required and non-configurable\n }\n}, function(questionData) {\n // your code here\n});", "language": "javascript", "name": "jQuery" } ] } [/block] [block:callout] { "type": "info", "title": "Optional question configuration", "body": "Survata provides three options for displaying answer choices:\n\n'fixed': Answer choices will be displayed in the order in which they are specified\n'shuffle': Answer choices will be randomly shuffled\n'random-v': Answer choices will be randomly be displayed in reverse order" } [/block]
{"_id":"54cac258f4c2b70d00859993","createdAt":"2015-01-29T23:29:28.374Z","project":"54a30513ad78941600ca2dba","githubsync":"","link_external":false,"link_url":"","sync_unique":"","user":"54a304d0eda4690b00ac0fe4","api":{"auth":"required","method":"post","params":[],"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"name":"","status":400,"language":"json","code":"{}"}]},"url":"/survey/[survey_uuid]/submit"},"body":"This will submit your survey","excerpt":"Submit a survey for Survata analyst to review","type":"post","updates":[],"version":"54a30514ad78941600ca2dbd","__v":0,"category":"54a30568ad78941600ca2dc1","hidden":false,"order":4,"slug":"surveysurvey_uuidsubmit","title":"/survey/[survey_uuid]/submit","childrenPages":[]}

post/survey/[survey_uuid]/submit

Submit a survey for Survata analyst to review

This will submit your survey

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



This will submit your survey
{"_id":"54ac22e3ec3be11400c8afb0","slug":"surveysurvey_uuidapprove","__v":3,"body":"When you are finished building your survey and are ready to proceed, post to the \"approve\" endpoint.  This will notify your survey analyst that your survey is ready to be run.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey.\"\n}\n[/block]","category":"54a30568ad78941600ca2dc1","createdAt":"2015-01-06T18:01:07.243Z","link_external":false,"link_url":"","excerpt":"Approve a survey when complete","githubsync":"","title":"/survey/[survey_uuid]/approve","user":"54a304d0eda4690b00ac0fe4","api":{"auth":"required","method":"post","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"id\":670,\n  \"uuid\":\"4c3e58da75f24b04bc77f0e8f67516cd\",\n  \"name\":\"Test exclusive\",\n  \"created\":\"2015-01-03T03:41:37Z\",\n  \"approved\":\"2015-01-06T17:40:44Z\",\n}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"url":"/survey/[survey_uuid]/approve"},"hidden":false,"order":5,"updates":[],"project":"54a30513ad78941600ca2dba","sync_unique":"","type":"post","version":"54a30514ad78941600ca2dbd","childrenPages":[]}

post/survey/[survey_uuid]/approve

Approve a survey when complete

When you are finished building your survey and are ready to proceed, post to the "approve" endpoint. This will notify your survey analyst that your survey is ready to be run. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



When you are finished building your survey and are ready to proceed, post to the "approve" endpoint. This will notify your survey analyst that your survey is ready to be run. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block]
{"_id":"54ab0658efb39016009e4d8e","hidden":false,"project":"54a30513ad78941600ca2dba","title":"/survey/[survey_uuid]/survey-result","__v":9,"category":"54a30568ad78941600ca2dc1","type":"get","version":"54a30514ad78941600ca2dbd","user":"54a304d0eda4690b00ac0fe4","excerpt":"Get links to survey results data","githubsync":"","link_url":"","order":6,"slug":"surveysurvey_uuidsurvey-result","sync_unique":"","updates":[],"api":{"auth":"required","method":"get","params":[],"results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n  \"id\":165,\n  \"created\":\"2015-06T06:52:27Z\",\n  \"imageUrl\": \"https://imageUrl.com\",\n  \"rawUrl\":\"https://rawDataUrl.com\",\n  \"statwingUrl\": \"https://statwingUrl.com\",\n  \"statwingShareUrl\": \"https://statwingShareUrl.com\",\n  \"surveys\": [\n    {\"id\":670}\n  ]\n}"},{"status":400,"language":"json","code":"{}","name":""}]},"url":"/survey/[survey_uuid]/survey-result"},"body":"When your survey is complete and results have been delivered, you can make an API call to retrieve the survey result object which will contain links to your results data.  Note that some parameters may not be populated, such as the image url and Statwing share url.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"\",\n  \"body\": \"Note that if you make this request before survey results have been delivered it will not return an error but the result data will be an empty JSON object.\"\n}\n[/block]","createdAt":"2015-01-05T21:47:04.141Z","link_external":false,"childrenPages":[]}

get/survey/[survey_uuid]/survey-result

Get links to survey results data

When your survey is complete and results have been delivered, you can make an API call to retrieve the survey result object which will contain links to your results data. Note that some parameters may not be populated, such as the image url and Statwing share url. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block] [block:callout] { "type": "warning", "title": "", "body": "Note that if you make this request before survey results have been delivered it will not return an error but the result data will be an empty JSON object." } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



When your survey is complete and results have been delivered, you can make an API call to retrieve the survey result object which will contain links to your results data. Note that some parameters may not be populated, such as the image url and Statwing share url. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block] [block:callout] { "type": "warning", "title": "", "body": "Note that if you make this request before survey results have been delivered it will not return an error but the result data will be an empty JSON object." } [/block]
{"_id":"54ab067e99f6581600167cb7","body":"The tally request returns information regarding the progress of your survey - how many responses have submitted out of the total of respondents requested, as well as the estimated completion date - and a tally of how many times each answer choice has been selected.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey.\"\n}\n[/block]","createdAt":"2015-01-05T21:47:42.752Z","excerpt":"Get tally of survey responses","link_url":"","hidden":false,"sync_unique":"","updates":[],"version":"54a30514ad78941600ca2dbd","category":"54a30568ad78941600ca2dc1","githubsync":"","link_external":false,"title":"/survey/[survey_uuid]/tally","type":"get","user":"54a304d0eda4690b00ac0fe4","__v":5,"api":{"method":"get","params":[],"results":{"codes":[{"code":"{\n  \"responses\":100,\n  \"responsesNeeded\":400,\n  \"finishDate\":\"2016-04-03T13:38:13Z\",\n  \"tally\": [\n    {\n    \t\"question\": {\n      \t\"id\":1805,\n      \t\"uuid\":\"4f158125-8959-49b3-ac0f-ce45c157d997\",\n      \t\"type\":\"singleSelect\",\n      \t\"statement\":{\"text\":\"What is your favorite color?\"},\n      \t\"details\": {\n      \t\t\"order\":\"fixed\",\n      \t\t\"choices\": [\n      \t\t\t{\"text\":\"Red\"},\n          \t{\"text\":\"Green\"},\n          \t{\"text\":\"Blue\"}\n        \t],\n        \t\"responseType\":\"text\",\n       \t}\n    \t},\n    \t\"results\": {\n      \t\"Red\": 55,\n      \t\"Green\": 35,\n      \t\"Blue\": 10\n    \t}\n    }\n\t]\n}","name":"","status":200,"language":"json"},{"name":"","status":400,"language":"json","code":"{}"}]},"url":"/survey/[survey_uuid]/tally","auth":"required"},"order":7,"project":"54a30513ad78941600ca2dba","slug":"surveysurvey_uuidtally","childrenPages":[]}

get/survey/[survey_uuid]/tally

Get tally of survey responses

The tally request returns information regarding the progress of your survey - how many responses have submitted out of the total of respondents requested, as well as the estimated completion date - and a tally of how many times each answer choice has been selected. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



The tally request returns information regarding the progress of your survey - how many responses have submitted out of the total of respondents requested, as well as the estimated completion date - and a tally of how many times each answer choice has been selected. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block]
{"_id":"54ab05d299f6581600167cb0","api":{"auth":"required","method":"get","params":[],"results":{"codes":[{"name":"","code":"[\n\t{\n\t\t\"uuid\":\"8364c097-0056-416a-bd4b-78383c5c7ca3\",\n    \"surveyUuid\":\"4c3e58da75f24b04bc77f0e8f67516cd\",\n    \"respondent\": {\n   \t\t\"uuid\": \"01f3c093-2eee-48a5-9084-247322a17dfb\",\n     \t\"countryCode\":\"US\",\n      \"region\":\"CA\",\n      \"postalCode\":\"94105\",\n      \"dma_code\":\"807\",\n      \"metro_code\":\"807\",\n      \"operatingSystem\":\"macos\",\n      \"webBrowser\":\"chrome\",\n      \"deviceType\":\"desktop\",\n      \"gender\":\"male\",\n      \"age\":\"25_to_34\",\n      \"panelistId\":null\n\t\t},\n    \"responseStatus\":\"accepted\",\n    \"rejectionReason\":\"null\",\n    \"answers\": [\n      {\n    \t\t\"uuid\":\"a2001fe0-6b61-48bc-8f4d-9ea5e8ded360\",\n        \"question\": {\n       \t\t\"id\":1805,\n          \"uuid\":\"4f158125-8959-49b3-ac0f-ce45c157d997\",\n          \"type\":\"singleSelect\",\n          \"statement\": {\"text\":\"What is your favorite color?\"},\n          \"details\": {\n            \"order\":\"fixed\",\n            \"choices\": [\n            \t{\"text\":\"Red\"},\n              {\"text\":\"Green\"},\n              {\"text\":\"Blue\"}               \n            ],\n            \"responseType\":\"text\"\n          }\n      \t},          \n     \t\t\"response\": {\n       \t\t\"selected\": \"a\",\n       \t\t\"choices\": [\n          \t{\"text\": \"Red\",\"value\":\"a\"},\n          \t{\"text\": \"Green\",\"value\":\"b\"},\n        \t\t{\"text\": \"Blue\",\"value\":\"c\"}\n      \t\t]\n      \t},\n      \t\"speedMs\":7008,\n    \t\t\"skipped\":false\n\t\t\t}\n  \t]\n\t}      \n]","language":"json","status":200},{"language":"json","status":400,"name":"","code":"{}"}]},"url":"/survey/[survey_uuid]/survey-response"},"link_url":"","project":"54a30513ad78941600ca2dba","user":"54a304d0eda4690b00ac0fe4","__v":6,"category":"54a30568ad78941600ca2dc1","hidden":false,"link_external":false,"slug":"surveysurvey_uuidsurvey-response","type":"get","body":"This API call returns an array of survey responses.  Each response contains information on the respondent and a list of answers given by the respondent.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey.\"\n}\n[/block]","createdAt":"2015-01-05T21:44:50.189Z","excerpt":"Get list of survey responses","githubsync":"","order":8,"sync_unique":"","title":"/survey/[survey_uuid]/survey-response","updates":[],"version":"54a30514ad78941600ca2dbd","childrenPages":[]}

get/survey/[survey_uuid]/survey-response

Get list of survey responses

This API call returns an array of survey responses. Each response contains information on the respondent and a list of answers given by the respondent. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



This API call returns an array of survey responses. Each response contains information on the respondent and a list of answers given by the respondent. [block:callout] { "type": "info", "body": "Please replace *[survey_uuid]* with the actual 32 character unique identifier string for your survey." } [/block]