Public API¶

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.

Info

You can always delete an Api key and create a new one.

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

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 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

Any scalar field can be used as a filter parameter.

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 undersocres). 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.