How To Use The SurveyToGo REST API

 

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 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: https://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 from the Lumivero Support Hub

 

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 by creating a ticket from the Lumivero Support Hub and we will make sure our SurveyToGo: REST API product team is notified of the request to be reviewed for adding to future versions.