API Reference

The SurveyPlanet API is based on REST. It is designed to be predictable, resource-oriented, and uses standard HTTP response codes to indicate errors. All responses, including errors, are formatted in JSON.

Status codes

SurveyPlanet uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (for example, a required parameter was missing or an invalid client ID), and codes in the 5xx range indicate an error with the server.

HTTP status code summary

Authentication

You authenticate to the SurveyPlanet API by providing your API client key and client secret in the request. You can obtain the key and secret from Account Settings. Once these credentials are submitted, an access token will be returned which you can use to make further requests. Access tokens are valid for 1 hour.

Examples

AUTH=$( printf "%s" "${CLIENT_ID}:${CLIENT_SECRET}" | base64 )

curl https://api.surveyplanet.com/oauth/token 
  --request POST 
  --header "Content-Type: application/x-www-form-urlencoded" 
  --header "Accept: application/json" 
  --header "Authorization: Basic $AUTH" 
  --data "grant_type=client_credentials"

const client = Buffer.from(`${auth.client}:${auth.secret}`).toString('base64');

fetch('https://api.surveyplanet.com/oauth/token', {
	method: 'POST',
	headers: { Authorization: `Basic ${client}` },
	body: JSON.stringify({ grant_type: 'client_credentials' }),
})
	.then((response) => response.json())
	.then((res) => console.log(res.data))
	.catch((err) => console.error(err));

import requests
import base64

client = base64.b64encode(f"{auth['client']}:{auth['secret']}".encode()).decode()

try:
    response = requests.post(
        'https://api.surveyplanet.com/oauth/token',
        headers={
            'Authorization': f'BASIC {client}',
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data={'grant_type': 'client_credentials'}
    )
    print(response.json()['data'])
except Exception as e:
    print(f"Error: {e}")

Response

{
	"token_type": "Bearer",
	"access_token": "ab64128f87d5c5e3342c5feca87f53497f42249c31d9c0165f5b2f65a80d0999",
	"expires_in": 1799
}

Authentication errors

Authentication errors are derived from the OAuth 2.0 specification Error Response and always return the following:

• status — The status code of the error returned.
• type — The type of error returned.
• message — (Optional) A human-readable message giving more details about the error.

Possible error types include:

Querying lists

All pluralized API resources support bulk fetches. For instance, you can list surveys, questions, participants, and so on. These API methods share a common structure, taking the parameters: before, after, and select.

Pagination

SurveyPlanet utilizes cursor-based pagination via the after and before parameters. Both take an existing resource ID and return objects in reverse chronological order. The before parameter returns objects created before the named object. The after parameter returns objects created after the named object. If both parameters are provided, only before is used.

https://api.surveyplanet.com/v1/participants?after=58d45d9dc500291d11dc6ef8

Selecting specific fields

You can include or exclude specific fields using the select parameter. Prefixing a field with - flags that field as excluded. When a field does not have the - prefix, it is included. _id fields are always returned unless explicitly excluded.

https://api.surveyplanet.com/v1/survey/54a32850aafed2ae1010189c?select=title%20active%20-_id