dark_mode

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

To maintain reliable API performance and ensure fair access for all customers, Sandwai applies a rate limit to API requests. This limit helps protect system performance and prevent excessive usage from affecting other customers.

By default, API usage is limited to 100 requests per minute per company.

Increasing Your Rate Limit

We understand that some customers may require a higher volume of API requests to support their integrations or business operations.

Customers can request an increase to their default rate limit by contacting Sandwai Support. Requests will be assessed based on individual requirements and expected API usage.

How The Rate Limit Is Applied

Rate limits are applied at the company level rather than to individual API keys. All applications and integrations associated with a company share the same request allowance.

Handling Rate Limit Responses

When the rate limit is exceeded, the API returns an HTTP 429 - Too Many Requests response.

Customers should handle this response by waiting before submitting additional requests.

Recommended Practices

When developing integrations that make frequent API requests, we recommend monitoring request volumes and allowing sufficient capacity within the rate limit for other applications and integrations used by your company.

Sandwai will return a header that describes the rate limit and how many requests remain in the rate limit window.

Where appropriate, implement retry mechanisms to manage rate limit responses and avoid unnecessary repeated requests.


Pagination

The new Sandwai API has removed restrictions on a number of previous endpoints. Results will now be paginated with a limit of:

Pagination links will be provided in each response in the case that the request returns more than 1000 results.


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

POST create

GET single

PUT update

DEL archive

URL

The URL to access Sandwai's APIs is https://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.
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.