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.
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).
For PHP we have a package/class on GitHub including multiple examples and explanations available here: https://github.com/lourenssystems/smartbusiness-api2-php
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:
|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.|
For all endpoints which require authentication you need to provide your access token in the header:
How the access token is obtained is described here.
All available endpoints and actions are documented and listed here, as well as they can be tested directly from within the documentation.
To every response additional headers will be attached.
|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-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.
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.