API Basics

The SmartSurvey API gives you access to secure survey data for use in your own app. It strives to be RESTful and is organised around the main resources you’re familiar with from the SmartSurvey web interface.

Before you do anything, you should make sure you have a SmartSurvey account that you can test the API against and register for an API key so that you can make API calls.

The SmartSurvey API is a RESTful API, which adheres to the guidelines defined by REST. You can read more information about REST on the following link:
https://en.wikipedia.org/wiki/Representational_state_transfer#RESTful_web_services

Getting Your API Key

In order to use SmartSurvey API, you will need to request an API key from within your account dashboard.

Follow the steps below to get your API key:

• Login to your account
• Click on My Account
• Click on API Keys
• Request API Access
• If you have not already requested one, click on request key.
• Click Add New API Key
• Once the key appears, use this to authenticate with the API

If you do not see this option within your account, please contact us for further assistance.

Example API Request

The token and token secret needs to be passed with each request inside the querystring.

E.g. https://api.smartsurvey.io/v1/surveys?api_token=XXXXX&api_token_secret=XXXXX

If using POST or PUT, you must use either application/json, text/xml or application/xml as the content-type for the request, with the body formatted accordingly otherwise you will receive a 415 error response.

Output Formats

The SmartSurvey API provides the output/response for an API request in the following
formats.

You can change the output format by providing an "Accept" request header with the above values.

Pagination

Some endpoints that return arrays support page and page_size as URL parameters. page defines the page index and page_size defines the number of records that will be returned on a page. The number of records is not guaranteed to be the number specified as visibility rules may filter out items.

Query Parameters:

• page – page of records to return (defaults to 1)
• page_size – number of records to return per page (defaults to 10, max is 100)
  If successful, you should receive the following custom headers in your response:

For example:
https://api.smartsurvey.io/v/1/surveys/{surveyId}/responses/?api_token=XXXXX&api_token_secret=XXXXX&page=1&page_size=100

Date Formats

NOTE: .

Date-time information is always returned in UTC and ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). You will need to adjust the timezone to suit your needs.

Dates sent to the API must be Unix epoch timestamp and should be formatted as shown in the example below:

Example: Fri, 01 Jan 2016 00:00:00 UTC = 1451606400 (UTC Timestamp)

Versioning

This REST API version v1 is our first API version. The API version is likely to change from v1 to vN {N = 1 …. n} if any structural changes are made to the existing version.

Security

All function calls included in SmartSurvey API are provided over SSL (Secure Socket Layer). This ensures that your data is transmitted through a secure channel.

Include Labels

When making requests to get survey responses, by default, the labels are not included. To include them, you just need to append "&include_labels=true" with your request.

For example:
https://api.smartsurvey.io/v/1/surveys/{surveyId}/responses/?api_token=XXXXX&api_token_secret=XXXXX&include_labels=true