API Reference

Overview

The Bizyness API allows customers to create and search for accounting objects such as invoices, clients, payments and to generate various reports.

This documentation provides information about each endpoint in the API. The right-hand pane of this page shows example requests and responses for each endpoint in cURL and many other languages.

Getting started

Follow these steps to start licensing media:

  1. Create a Bizyness account

  2. Go in your Profile and create an API Key, you can also use the JWT method to authenticate your requests

Request/Response Format

The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200 OK HTTP status.

Some general information about responses:

  • Dates are returned in ISO 8601.
  • Resource IDs are returned as strings.
  • Any decimal monetary amount, such as prices or totals, will be returned as strings with two decimal places.
  • Other amounts, such as item counts, are returned as integers.

Errors

The API returns error codes such as 400, 403, 404, and 500 along with information about the error. Here are some common error responses:

A 400 Bad Request response often means that the request body is improperly formatted or missing required fields. In the case of missing fields, the response includes the name of the field that is missing, as in the example in the right-hand column.

A 401 Unauthorized response often means that the request did not include a valid authentication.

A 404 Not Found response can mean that the object you are trying to access does not exist.

A 500 Internal Server Error response means that an error happened on the server. This can mean that the request is not valid, such as if you try to delete or edit a collection that does not exist, or if the API otherwise can't do what you requested. It can also mean a temporary problem with the API. Check your request and try again or contact us.

Pagination

Requests that return multiple items will be restricted to 100 items by default, with a maximum of 250 items. Alternatively the items per page can be specified with the limit parameter:

GET /invoices?limit=200

The (zero-based) offset query parameter is used to exclude from a response the first N items of a resource collection.

GET /invoices?offset=10

You can combine the limit and the offset parameters to request a particular set of items. Note that the offset option is applied before the limit option, regardless of its position in the request.

The total entries will be set in the HTTP header X-Total-Count

Sorting

Multiple items returned in a request can be sorted using sort parameter.

GET /invoices?sort=+name,-subject

Attributes used in the sort parameter must be part of the requested resources. If multiple attributes are sorted they must be separated by a comma (,). The order of each attribute must be set using either + (ascending) or - (descending). If no sign is set, the default ordering is ascending.

PUT/PATCH methods

PUT and PATCH requests are used to update objects identified in the requests' paths:

  • PUT method can be used to update all attributes of an object in one call.
  • PATCH method can be used to update partial attributes of an object. This method supports JSON Patch and JSON Merge. The media type of the request is used to set the proper PATCH method, either application/json-patch+json (JSON Path) or application/merge-patch+json (JSON Merge).

Dates

Dates used in payloads can use two formats:

  • A long representing the number of milliseconds since the epoch of 1970-01-01T00:00:00Z (UTC), exemple 1685267473348
  • A string representing the date in ISO 8601, example 2023-05-28T11:48:21+02:00

Dates used in request parameters for filtering/searching must follow the patter 'yyyy-MM-dd'. Dates will be automatically set to the start/end of the day in the user's timezone: date_min time will be set to 00:00:00 and date_max time will be set to 23:59:59.

Rate limits

All applications are limited to a certain number of API requests per minute. If your application exceeds its limit, the API returns an error response with a status code of 429.

The API supports a limit of 10 requests per second.