Getting started

The requests documented in the following chapters are also available as a Postman collection.

Authentication

To start communicating with the gateway of NeoDay you must first obtain an access token. You can request one by using your client ID and secret:

POST /api/1/oauth2/access_token HTTP/1.1
Host: gateway.acme.neo.day
Content-Type: application/json

{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": 15638400,
    "access_token": "eyJ0eXAiOiJKV1QiL......"
}

Locale

Most requests require a locale parameter to be a set in the query parameters. The available locales depend on what is configured for a specific site. If a locale is not set for an endpoint that requires it a 401 Missing Locale error will be returned.

Idempotency

The API supports the Idempotency-Key header for POST requests. This allows you to safely retry requests while making sure the operation is only executed once.

POST /api/1/terminal/r8d0h8nfx09w23o64g63rvk7q/events/my_event?locale=en_GB HTTP/1.1
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........
Idempotency-Key: 605a4ac2-f9e5-4a34-9114-a1a610a44e2b
Content-Type: application/json

{
    "some_value": "abcd",
    "another_value": 100
}

HTTP/1.1 202 Accepted
Content-Type: application/json

The Idempotency-Key header must contain a unique key. This key can be up to 255 characters long. When a POST request is made that includes this header the resulting status code and body is stored and will be returned to subsequent request using the same key.

The results of requests made with an Idempotency-Key header are stored for 24 hours.