Welcome to the Sandwai API, this documentation contains instructions on how you can interact with the Sandwai system in order to read, create, update or delete resources. The Sandwai API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Destructive*
As the endpoints are connected directly to your database, Update and Archive endpoints have the possibility to be destructive.
Ensure when testing endpoints that the data you have entered is correct and confirm you are editing the correct object before selecting try functionality
Internal IDs vs Custom IDs*
The Sandwai API now supports the use of internal Sandwai IDs when Getting, Updating and Archiving objects. The default behaviour is to use custom ids.
When making a request to a relevant endpoint, you can include the following header below:
useinternalid: true
When the header is not included or set to false, requests will be resolved by matching objects with their customids. When set to true, objects will be matched using their internal Sandwai IDs.
Rate Limits
The Sandwai API uses a number of safeguards against bursts of incoming traffic to help maximise its stability. Users who send many requests in quick succession might see error responses that show up as status code 429. Sandwai's current rate limiting default is:
- 100 requests per minute
Pagination
The new Sandwai API has removed restrictions on a number of previous endpoints. Results will now be paginated with a limit of:
- 1000 objects per request
HTTP Response Codes
Each request method can return several different response codes which can be used to determine the success of the call:
GET index
- 200 OK
- 404 Not Found
POST create
- 201 Created
- 422 Validation Error
GET single
- 200 OK
- 404 Not Found
PUT update
- 204 Updated
- 422 Validation Error
- 404 Not Found
DEL archive
- 200 Archived
- 422 Validation Error
- 404 Not Found
URL
The URL to access Sandwai's APIs ishttps://api.sandwai.com/v1/
How to Authenticate
Sandwai uses API tokens to authenticate requests, which is known as Bearer Authentication. You can view and manage your API tokens within the System Settings screen in Sandwai.- API requests must send an API token in the Authorization header when making requests to any API endpoint:
Authorization: Bearer YOUR_TOKEN - API requests must include the Accept header with the value of "application/json":
Accept: application/json - API requests must include the Content-Type header with the value of "application/json":
Content-Type: application/json - API requests must be made over HTTPS. Calls made over plain HTTP will fail
You can try the Sandwai API to see how requests and responses are structured. To do so, enter your assigned API key above and click "set". This will give you authorisation to test our APIs within this document.
Company Identification
In addition to providing an API token on every request to the API, you must also provide your assigned Company ID.
This is used to verify the organisation sending the request.
The Company ID can be sent as Header:
companyid: YOUR_COMPANY_ID
Note that the Company ID parameter must be all lowercase with no spaces.
