Requests

Our API is a collection of 'RESTful' web services. You interact with our resources by sending an HTTP message to a URL. The URL determines the resource and the HTTP method defines the type of action.

Authentication

All requests must include an Authorization header with a valid access_token. See Security for more details on access_tokens.

HTTP Methods

These are the methods our apis support. Not all methods are implemented for all resources.

Note: We prefer the use of PATCH over PUT, so the PUT is rarely used in our endpoints.

Method	Description
GET	Get a resource
PUT	Replace a resource
POST	Add a resource
DELETE	Delete a resource
PATCH	Update properties on a resource

Request structure

Requests to our APIs have the following structure:

https://<host>/<api-version>/<domain>/(<resource/\{id\})*>?(query-parameters)

Example (Post Request)

POST  https://<host>/v1/surveys/p1231234/respondents HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>
Content-Type: application/json
{
"email": "[e-mail]",
"city": "oslo",
"country": "norway"
}

Request Headers

Name	Syntax	Description	Example
Accept	Accept: <MIME-type>/*Accept: <MIME-type>/<MIME-subtype>Accept: */*	Indicates which MIME types the client is capable of understanding. During content negotiation, the server should select which of the MIME types for the response. That choice is communicated back to the client using the Content-Type response header.	Accept: application/json
Authorization	Authorization: <type> <credentials>	Specifies the credentials of the client to authenticate with a service. All services must support the Authorization header.	Authorization: Bearer c1das334aff
If-Match	If-Match: <etag_value>If-Match: <etag_value>, <etag_value>, …​	Specifies a conditional request to only return the resource when it does match one of the included ETag values. All services must support the If-Match header provided they support the ETag response header.	If-Match: ID-123123
If-None-Match	If-None-Match: <etag_value>If-None-Match: <etag_value>, <etag_value>, …​	Specifies a conditional request to only return the resource when it doesn’t match one of the included ETag values. All services must support the If-None-Match header provided they support the ETag response header.	If-None-Match: ID-123123

Paging

You can control the number of items returned when requesting a resource collection by using the query parameters below. We call the collection of items returned a "page".

Parameter	Type	Description	Example
pageSize	Integer	The number of items per "page". If not specified, 100 items will be returned.	GET https://...?pageSize=50
page	Integer	The index of the "page" to return. If not specifed, the first "page" will be returned.	GET https://...?page=2 Returns the second page of 100 items, numbered 101-200. GET https://...?pageSize=30&page=1 Returns the first page of 30 items, numbered 1-30. GET https://...?pageSize=30&page=4 Returns the fourth page of 30 items, numbered 91-120.