# General Guide

# Authentication

To authenticate with the Pollable API you first need to obtain an access token from our authentication provider Auth0. The following command will instantiate a request to Auth0 and generate an access token as a response.

Command:

curl --request POST \
  --url https://login0.local.dev.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":$CLIENT_ID,"client_secret":$CLIENT_SECRET,"audience":"https://api.pollable.io","grant_type":"client_credentials"}'

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlJUVkRSRFF3TVVVeU0wVXdSamxFT1VGR056UXpOamd4TlVGR05UZENNekpFUVVORFFUSXdSZyJ9.eyJpc3MiOiJodHRwczovL3BvbGxhYmxlLmF1dGgwLmNvbS8iLCJzdWIiOiJUbjhvWXRBcDYwbDZBYUMyN2kzbjMyNWt1N1RNSmRZR0BjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkucG9sbGFibGUuaW8iLCJpYXQiOjE1NTE2ODA1MjcsImV4cCI6MTU1MTc2NjkyNywiYXpwIjoiVG44b1l0QXA2MGw2QWFDMjdpM24zMjVrdTdUTUpkWUciLCJzY29wZSI6InJlYWQ6YXVkaWVuY2UgZGVsZXRlOmF1ZGllbmNlIHVwZGF0ZTphdWRpZW5jZSBjcmVhdGU6YXVkaWVuY2UiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.rmELKMToSofaDmMb3WiNRz6E-JeRrRhPZz6zDqf6i9HRwkb0WtnDimYjRC37kpbTKNdif33IMyVdRjq7HV9xMBZUoBU-Auq2vS9Gor-ayPyuFa8DCdFp3Exd4qti3hghhhcQiKuGWtOWt4fLtYB1tYDVLdo35lih-4zRsUK-d1bfMpra-Nh51fnxlbada1XZBJQNB9UgJ9BC4HJeMY4XMbMUTuia1fwW688uMLB29_B2HVfxxVfhZMWCzXhBLkRMwZis4XylIUtFSrW5fYJ7B7YISvnco7f0ejL70Rdj4xpewxHpDjCR4Z38eUJnR_-_AdFJ3-7aJt9_Bc9LiGFEIQ",
  "token_type": "Bearer"
}

# Pagination

Certain requests with the Pollable API have pagination enabled.

# Representations

By default all endpoints return json content. There are alternate csv representations with the /projects/<id> and /projects/<id>/responses endpoints. For example, to return csv content add the following header:

Accept: text/csv

# Returned Fields

The fields returned by an api request can be specified with the fields parameter of the query string. For example in the following request:

POST /projects/1?fields=name,active HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer "eyCJhYCQ...

The body will be returned with only the name and active fields.

{
  "name": "test",
  "active": true
}

# Status Codes

The following status codes are viable returns for api requests.

# Success

• 200 OK – Successful request.
• 201 Created – Resource successfully created.
• 204 No Content – Successful request with no response body.

# Failure

• 401 Unauthorized – Authorization error.
• 404 Not Found – Requested resource not found.
• 409 Conflict – Request caused conflict with existing resources.
• 422 Unprocessable Entity – Arguments cannot be processed.
• 429 Too Many Requests – Api request rate limit exceeded.
• 500 Internal Server Error – Error occurred in request response.