The SmartSurvey API

Welcome to the SmartSurvey API documentation. You'll find comprehensive guides and documentation to help you start working with the SmartSurvey API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Getting Started

Welcome to the documentation for the SmartSurvey API. Here we will explain to you how to authenticate your API calls, what error codes we use, how we do versioning, and how you can use the API.

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

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:

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 SSL (Secure Socket Layer). This ensures that your data is transmitted through a secure channel.

Getting Started

Welcome to the documentation for the SmartSurvey API. Here we will explain to you how to authenticate your API calls, what error codes we use, how we do versioning, and how you can use the API.