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.

Authentication

Your API requests must use Basic Auth for authentication. All API tooling should support this mechanism which should encode your api token and secret into a specific format, which is then passed in an HTTP header like this:

Authorization: Basic <token>

You should not need to create this header manually, which is slightly complicated and which can cause various errors if not done correctly.

Failed authentication will return an HTTP 401 Unauthorized response.

Previously, we supported querystring parameters but these are now deprecated and all requests should switch to using Basic auth.

Note that if you are migrating to using Basic Auth, as soon as you provide an Authorization http header, the querystring parameters will be ignored even if they are correct. For this reason, a malformed Authorization header will cause a 401 even if you are still passing the querystring parameters.

🚧
Basic Auth, Usernames and Passwords
Some Basic Auth examples and documentation, and the test function on the API refrerence pages, will refer to a "Username" and "Password". In the context of SmartSurvey API requests, "Username" is the API Token. "Password" is the Token Secret.
Do not try and use your SmartSurvey login credentials. This will not work, and will generate a 401 error.

Example API Request

GET https://api.smartsurvey.io/v2/surveys

In this example, the returned content will be inferred from the authenticated account i.e. you will get a list of all surveys linked to the authenticated account.

GET https://api.smartsurvey.io/v2/surveys/12345

In this example, when requesting a specific object (e.g. survey 12345), then if you are not permitted to access it with the authenticated account, you will receive am HTTP 403 Forbidden response.

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.

Format	Accept Header
`JSON` default	application/json
`XML`	application/xml

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/v2/surveys/{surveyId}/responses/?page=1&page_size=100


`X-SS-Pagination-Page`	The page number requested.
`X-SS-Pagination-PageSize`	Number of rows requested.
`X-SS-Pagination-Total`	The total number of rows found in database.
`X-SS-Pagination-Returned`	The total number of rows returned.

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 https (Transport Layer Security). This ensures that your data is transmitted through a secure channel between our server and your client.

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/v2/surveys/{surveyId}/responses/?include_labels=true