Introduction

The API is a REST based API with OAuth2 authentication and enables you to either access your own account via programmable software, or access data from foreign accounts that have given you the explicit permission to do so.



Requirements for using the API

To be able to use the API you need to have a registered account (also if you are a 3rd-party softwareprovider and not using the application yourself).



Package/Class for PHP

For PHP we have a package/class on GitHub including multiple examples and explanations available here: https://github.com/lourenssystems/smartbusiness-api2-php



Basics

The interaction format (input and output) for all endpoints (except ones returning binary data like images and pdfs) is JSON.

Following HTTP methods are used:

HTTP Method Usecase
GET Used for retreiving lists and objects. Various GET parameters will be available.
POST Creating new entities. The data is posted as JSON object in the body.
PUT Updating existing entities. The data is posted as JSON object in the body.
DELETE Deleting existing entities. Various GET parameters will be available. Example:
PATCH Actions on existing entities. Data can be posted as JSON objects and / or various GET parameters can be available. Example: Sending invoice by email.


Authentication

For all endpoints which require authentication you need to provide your access token in the header:

Header key Value
Authorization Bearer YOURACCESSTOKEN


How the access token is obtained is described here.



Endpoints & Actions

All available endpoints and actions are documented and listed here, as well as they can be tested directly from within the documentation.



Response headers

To every response additional headers will be attached.

Header Type Description Example
X-Rate-Limit-Limit int The number of allowed requests in the current period 1000
X-Rate-Limit-Remaining int The number of remaining requests in the current period 999
X-Rate-Limit-Reset int The number of seconds left in the current period 3600
X-Request-Id string UUID of response c0ce64e5-d351-48fb-9c30-f19ffd3a2b0e
Access-Control-Allow-Methods string GET
Access-Control-Allow-Origin string *
Access-Control-Allow-Headers string X-Requested-With, Content-Type, Accept, Origin, Authorization

In case of support inquiries it is always optimal to pass the X-Request-ID value along with your request for faster identification of potential issues.



HTTP Response codes

As restful API we use HTTP Response codes for the basic information if a request was successful or not. Every endpoint and action has the available response codes documented and should be considered when implementing the API.

If a request fails, or any other information is available, the return body of the request will contain a JSON object with further information.