The OnSinch application provides a Public API that can be used to export and import data to and from OnSinch.
In order to use the Public API you need to be familiar with implementing APIs in general.
The Public API is not present in all of the OnSinch pricing plans by default.
Getting started
Generating an API key
- Generate an API key - go to the OnSinch application → Profile → API Keys
- Set the name of the API key you want to create - it is just for you to know where the API key will be used
- Set the expiration date - can be left blank if you don't want the API key to expire
- Click Create
- Once created, save the generated API key to a safe place. It will not be displayed again.
💡 You can always delete an API key and create a new
Authentication
Bearer authentication (also called token authentication) is used to authenticate requests. To set the authentication, set the Authentication header for every request as follows:
Authorization: apikey <API-KEY>
❕Note the prefix apikey goes before the actual <API-KEY> which you generated earlier.
Making the first requests to the OnSinch Public API
Once you have the API key, you can make requests against your OnSinch instance. To test it, the simplest way is to use cURL command.
An example cURL request to get your basic profile information can be seen below. Make sure you replace <YOUR-INSTANCE> with the URL of your OnSinch and <API-KEY> with generated API key.
curl --request GET \
--url 'https://<YOUR-INSTANCE>/api/v1/users/profile' \
--header 'Authorization: apikey <API-KEY>'
Using the Public API
A list of all of the API endpoints and concrete documentation for the available endpoints to your OnSinch is always at:
https://<your-onsinch-url>/public-api
Pagination
When calling API endpoints that return many items, the following structure is used:
Example:
{
"pagination": {
"page": 1,
"current": 5,
"count": 9,
"prevPage": false,
"nextPage": true,
"pageCount": 2,
"order": {
"Invoice.number": "DESC",
},
"limit": 5
},
data: [
{...}
]
}
The pagination definition is returned as the first key in the response is giving you the information about how many pages and how many items there are, so you can paginate through the API endpoints and achieve better performance.
Basic pagination can be achieved by using the limit and page parameters in the query string.
Example:
To list records 11-20 you can use page=2 and limit=10 in the query strings.
/api/v1/invoices?page=2&limit=10
Filtering
API endpoints that contain multiple results (list, index) can be filtered using query strings.
To filter out specific data from the API endpoint, the query string parameter can be used.
Format:
/api/v1/<endpoint>?<field>[<operator>]=<value>
Example:
To list workers who logged into the application after 1/1/2023
/api/v1/workers?last_logged_in[gt]=2023-01-01
Operators:
| Operator | description | example |
|---|---|---|
| (empty),eq | equals | ?name[eq]=John&surname=Doe |
| gt | greater than, > | ?last_logged_id[gt]=2023-01-01 |
| gte | greater than equal, >= | ?last_logged_id[gte]=2023-01-01 |
| lt | lower than, < | ?last_logged_id[lt]=2023-01-01 |
| lte | lower than equal, <= | ?last_logged_id[lt]=2023-01-01 |
| neq | not equal, != | ?status[neq]=1 |
| in | in list | ?id[in]=125,126 |
Nesting (associations):
Filtering based on associated models is also possible. In that case, the model needs to be prefixed to the field with __ (two underscores). Example:
Company__id
Supported nesting models are documented in the API endpoint documentation.
Example:
Example filtering invoices based on Company name and contains Order and Company.
/api/v1/invoices?with=Order,Company&Company__name=RedBeast%20Energy
Note that we escape " " (space) with %20 in the Company name field.
💡Tip: In order to use the API effectively and avoid rate limits (how to protect the server from overloading from the request) always try to filter out or paginate fetched data. It will speed up the processing of the data.