If you succesfully configure your software you can start calling our API. Couple things to remember:

This is REST API. All you have to do is point your system in resource URL you want to communicate with and call one of available action (HTTP verbs)

GET calls can be divided in two types - calling one resource and collection of resources. When calling one resource you don't need to do much more that just call GET /RESOURCE_URL, but in case of calling for collectons of resources you have some additional options: you can filter results base on some particular search fields, you can sort results, request specific page and demand specific results per page. All of that is done by adding query string parameters (every resource have detailed description of what types of quesry parameters can be pass to it)

If you want to add new resource or modify existing one you will have to do POST request. (If you are curious why we don't use PUT here(link to come) is explanation). Remember that your request body should be encoded in UTF-8 JSON. Every resource has detailed explanation on what fields can be changed, just go to the corresponding documentation page.

DELETE requests are simplest we offer. If you just want to remove resource just call DELETE request with id of a resource in the URL and we will remove it if this is possible. You will receive 204 response if the operation was successful.

Response codes

200 - Everything went ok! You should look for your data in the response body.

201 - We just create new resource as you requested. In the response body you will find this newly created resource resource.

204 - We accepted your request. We cannot tell the exact result because there is some queue involved and we still waiting to process it. Response body is empty.

400 - We cannot understand your request, something is wrong with query parameters or request body. Look in response body for more details. You should find information what exactly went wrong and how to fix this.

401 - We cannot find authentication information in your request, and if we cannot determine who you are we cannot fulfill your request. Please add authentication header!

403 - What you want to do is normally possible, but because some other reason we cannot do that. Please check detailed description in response body what is the problem

404 - You looking for resource that do not exist. Please check resource identifier.

409 - There is some possible conflict that your request could do. Maybe you tried add resource with the same unique field? Please look in response body for more information.

50x - Sorry, something went wrong on our side, we will fix that as soon as possible. Check our twitter or blog for more information.

How response looks like

There are 4 different response types (in terms of what you will see in the body of the response)

One resource

If you requested from us one resource, by calling GET request with resource identifier in the url we will return simple JSON object structure {} with all infomration inside this object. This is basically resource respresentation.

Collection of resources

If you request from us an list of resources based on some filters we will return an JSON array [] that will contain an list of resources {}. Each entry will be an resource representation.

Empty response

If you request an DELETE request then we will return 204 response code with no content in the response body. The same is when you will request some asynchronous action - then your request will land in some queue system and will be processed later. In that case we also return 204 with empty body.

Error response

In case of error occuring we will return special error response  message in the body. The content of the body is pretty self-explanatory. We will tell you what went wrong and add special 'context' field with detailed description what exactly was not ok and how you can fix that. There will be also link to the apidocs portal error page where will be even more information on how to fix that type of error.

 

Additional headers

If you requested collection of resources you will recieve paged results, that means that there could be more results on next pages. In order to check where exactly you are and how many results there is in total you should check response headers - we put there special custom headers: TotalCount, TotalPages, CurrentPage, PerPage.

 

CORS (AJAX requests)

Cross-Origin Resource Sharing (CORS) mechanism is not supported by APIv3. It means that AJAX requests to the API will be blocked by the browser's same-origin policy. Please use a server-side application to access the API.