You can access your organization data using the SurveyToGo REST API. The REST API allows you to create a tight integration between the SurveyToGo system and any 3rd party system. Using the API requires prior knowledge of the REST protocol and experience in programming. You can use the REST API from any operating system and any programming language. The SurveyToGo REST API consists of a set of operations which are listed below. Please note we are adding to the list of operations so check back often or subscribe to this topic to stay on top of any new REST operation that is supported.
Downloading the Testbed App and Full Source code
Dooblo provides you with a free SurveyToGo REST API Testbed app that allows you to test all the available operations and see the output you will get to assist with the development process. In addition we provide the full C# source code of the Testbed app so that you can see the actual implementation of the code. Please note you can call the REST API from any language, not just C#:
- SurveyToGo REST API Testbed:http://api.dooblo.net/newapi/tb/RESTAPITestBed.zip
- SurveyToGo REST API Testbed App source: http://api.dooblo.net/newapi/tb/RESTAPITestBed-Sources.zip
SurveyToGo REST API Operations Available
The following operations are available:
General Account management:
- GetCreditBalance – returns the current interview balance
- GetStorageStatus – returns the current storage space usage
- GetStorageUsageSummary - returns the details of the storage usage over a given time period
User Administration & Assignment
- AddSurveyorUser – adds a new interviewer user to the organization
- AssignSurveyorUserToProject – assigns the interviewer user to the project
- DeleteSurveyorUser – deletes the interviewer user from the organization
- UnassignSurveyorUserFromProject – unassign the interviewer user from the project
- GetGroupUsers – returns the list of users in a group
- GetProjectSurveyorGroups – returns the list of interviewer groups assigned to aproject
- GetProjectSurveyorUsers – returns the list of interviewers users assigned to a project
- GetStudioGroups - returns the list of all groups of Studio users
- GetStudioUsers - returns the list of all Studio users in the organization
- GetSurveyorGroups - returns the list of all groups of surveyors
- GetSurveyorUsers - returns the list of all surveyor users in the organization
- GetUserDetails - returns the user details of a given user
- UnassignSurveyorUserFromProject - unassign the surveyor/user from a project
Projects & Customers
- CustomerProjects – returns the list of projects of a certain customer
- Customers – returns the list of customers in the organization
- ProjectSurveys – returns the list of surveys within a project
- CreateCustomer – creates a new customer
- CreateProject – creates a new project within a customer
- Surveys – returns the details of a specific survey
- GetActiveSurveys - Returns the list of surveys that have Uploaded/LastDateModified in the daysBack entered.
- GetSurveyXML – returns the full survey XML structure of a specific survey. We recommend using SimpleSurveyExport instead of this function.
- SimpleSurveyExport – returns a simple JSON/XML survey structure of a specific survey. This is a more recommended function to use than GetSurveyXML.
- SimpleExport – Generates an "Excel" like export of the survey data but in JSON or XML format.
- OperationData – returns the interview operational data in a form similar to the operations console
- SurveyInterviewData – returns the actual XML data of the interviews based on ID’s. The call will return the data of a maximum of 99 interviews per call. If you need to call this for more than 99 interviews please split your call to multiple calls each one would consist of up to 99 interview IDs.
- SurveyInterviewIDs – returns the list of interview ID’s of a survey based on filters
- SurveyInterviewIDsByLastModified – returns the list of interview ID’s of a survey based on the last modified time of the interviews.
- HandlingExamples - returns the quotas total in a table
- GetSurveyQuotasStatus - returns the status of each quota
- QuotaStructure - returns the quota sheet structure
- GetSurveyorsRoute - Returns the GPS route for the surveyors (Please note: you must choose either a Surveyor Name or Group).
- ChangeStatus – changes the status of an interview
Additional Data Lists
- AddRow – adds a new row to an existing additional data list
- DeleteRow – deletes a row from an existing additional data list
- Batches - Create and update Batches
- Task - Create and update Tasks
- TaskBatchData - returns the information data of a batch
- TaskBatchIDs - returns the batch ID numbers for a project
- TaskData - returns the information data of a task
- TaskIDs - returns the task ID numbers for a project
URL For Calling the REST API
The SurveyToGo REST API is hosted at this URL: http://api.dooblo.net/newapi
Calling the actual operations involves referencing the correct URL and passing the relevant user/password details.
User ID for Accessing the REST API
To call the various operations you need to specify a valid user ID. The user ID is in the form of XXXX-XXXX-XXXX/YYYY where the first part is your organization REST API Key and the second part is the relevant user name you wish to use for the operations. Please note the user accessing the REST API needs to have the relevant permissions for the operations that user is calling. For example, if the user does not belong to a certain project that user will get an authorization error if that user attempts to call operations for that project.
For example, if the user you wish to use when calling the REST API is named “mark” and the organization REST API Key is: f150fc49-3a14-4ecb-9214-ca04698a9578 the user ID that you need to use when calling the REST API: f150fc49-3a14-4ecb-9214-ca04698a9578/mark
Contact firstname.lastname@example.org to receive your organization REST API Key to use with the REST API.
The SurveyToGo REST API has a built-in rate limit of up to 2 calls per second. Once the limit has been reached an HTTP 429 response code will be returned (Rate limit). You can either write code in your application to deal with the rate limit response code or build around this limit by adding rate limit code to your REST API calling code.
JSON vs XML Output of requests
In some calls you can request to receive the output of the data in either JSON or XML format. This is intended to cater to each programmer preference. However, please keep in mind that for some operations that return either interview data or survey data in them, only XML will be supported as an output format. If you try to call these with JSON as format you will receive an error: “Error: This method supports only xml” from the API.
Sample code for retrieving survey interview data
You can click here to see a sample code for retrieving interview data using the REST API.
Sharing of your SurveyToGo REST API Integration Success Stories
If you developed a cool integration using the SurveyToGo REST API, we would love to hear about it and possibly share the project highlights with the rest of our community along with your name and details (if you wish) to promote your expertise and broaden the horizon of our community! Let us know by emailing us to email@example.com .
Missing an API that will assist you in your integration? Let us know!
If during the development of your integration you are missing an API please let us know at firstname.lastname@example.org and we will make sure our SurveyToGo REST API product team is notified of the request to be reviewed for adding to future versions.
Visit us at: http://www.dooblo.net