How To Use The SurveyToGo REST API

Customer Support Manager

November 26, 2024 09:09

Overview

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 3^rd 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 a project
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.

Data

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.

Quotas

HandlingExamples - returns the quotas total in a table
GetSurveyQuotasStatus - returns the status of each quota
QuotaStructure - returns the quota sheet structure

GPS

GetSurveyorsRoute - Returns the GPS route for the surveyors (Please note: you must choose either a Surveyor Name or Group).

Interviews

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

Tasks

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

You can access any user's complete API key through your User Details window in the Studio:

Please contact support here if you are not able to locate it

Rate Limits

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 support@dooblo.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 support@dooblo.com 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