Url structure
The structure of the URL is always the same and starts with 'https://api.simplybooks.be/api' followed by the version number of the data, currently 'v1'. Then comes the domain, eg. 'invoices', 'clients' or 'activities'. This is already a full URL, but you can then pass on the ID of the element. After this you can optionally pass on a subdomain whether or not followed by an ID. This gives, for example: https://api.simplybooks.be/api/v1/clients/101/contacts/9283 (contact person with ID 9283 of customer with ID 101).
Some examples:
- https://api.simplybooks.be/api/v1/clients: Customer
- https://api.simplybooks.be/api/v1/invoices/3003: Invoice with ID 3003
- https://api.simplybooks.be/api/v1/quotes/4004/items: Items of quotation with ID 4004
- https://api.simplybooks.be/api/v1/invoices/3003/items/4005: Item with ID 4005 of invoice with ID 3003
- https://api.simplybooks.be/api/v1/uploads: File Uploads/Attachments
The format
The format of the communication runs along XML by default, but JSON is also supported. In addition, you can also use the standard form-encoding when changing data. For example, if you send data via JSON, you can also expect an answer in JSON. For example, if you send your data in XML or form-encoding, a response will be sent back in XML. If you wish to deviate from this and decide for yourself what the returned answer will be, you can give this as an argument in the URL provided.
- ?format=xml: XML-formaat (default)
- ?format=json: JSON-format
- ?format=csv: CSV-formaat, can be opened in Excel
- ?format=html: an HTML-table
- ?format=pdf: as PDF (only for domains, invoices, receipts, quotes, orders and deliveries)
- ?format=efff: E-fff formaat – electronic invoice (only for domain invoices)
- ?format=ublbe: UBL.BE format– electronic invoice (only for domain invoices)
- ?format=peppolbis3: PEPPOL BIS 3.0 format – electronic invoice (only for domain invoices)
The 4 methods
De 4 standard form-methods are supported: GET, POST, PUT and DELETE:
- GET: Retrieving data
- POST: Creating or updating data where unlisted data remains unchanged
- PUT: Updating of data with the displayed data being considered as the only new data (existing data not displayed are deleted)
- DELETE: Deletion data
Result codes
When requests to the API, a result is always returned in the requested format. In addition, a result code is returned that generally indicates whether or not an action has been succeeded.
The result codes that can be returned
- 200: Action succeeded
- 201: Data created
- 400: Error due to incorrect data
- 401: User authentication not accepted
- 403: No access
- 404: Requested data not found
- 500: Internal error