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.
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.
E.g. https://api.smartsurvey.io/v1/surveys?api_token=XXXXX&api_token_secret=XXXXX
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/v1/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/v1/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/v/1/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/v/1/surveys/{surveyId}/responses/?include_labels=true
Updated about 2 years ago