Making requests

📘
Conventions
In the examples, $API_URL stands for the api_url of the connected license and $ACCESS_TOKEN for a valid access token. See Quickstart.

Endpoints

The API consists of JSON-RPC-style methods exposed over HTTPS, in the form:

{api_url}/{category}.{action}

For example: users.me, companies.list, invoices.purchases.new, book-entries.miscellaneous-operations.update.

Action suffix	Meaning
`.list`	Retrieve a filtered list of entities.
`.info`	Retrieve a single entity by its `Id`.
`.new`	Create an entity.
`.update`	Update an existing entity.
`.delete` / `.clear`	Remove one / all related entities.
`.download`	Download a file's bytes.

All identifiers (Id, FolderId, CompanyId…) are GUIDs.

Headers

Header	When	Value
`Authorization`	Every request	`Bearer` followed by the access token
`Content-Type`	Requests with a body	`application/json` (recommended), `application/x-www-form-urlencoded` or `multipart/form-data`
`Content-Encoding`	Optional	`gzip`, to receive compressed responses (see Gzip compression)

HTTP methods

All methods must be called over HTTPS.

Kind of action	HTTP method	Arguments
Simple reading (`.info`, `.me`)	`GET`	Query string parameters, e.g. `companies.info?Id=…`
Reading with complex filters (most `.list`)	`POST`	Request body
Creation and modification	`POST`	Request body
Deletion	`DELETE` or `POST`	See each endpoint in the API Reference

A simple read with GET:

curl "$API_URL/companies.info?Id=32ebe925-23cc-4a3e-8b36-8b2b33780fc1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

📘
Why POST for reading?
Reading actions with complex arguments (filters, arrays, date ranges) use POST, so that arguments are easy to build and never exceed the maximum URL length.

Request bodies

Bodies can be sent as JSON or URL-encoded data. Set the Content-Type header accordingly:

Format	Header
JSON (recommended)	`Content-Type: application/json`
URL-encoded	`Content-Type: application/x-www-form-urlencoded`
File upload	`Content-Type: multipart/form-data` (see Documents & attachments)

We strongly recommend JSON: it makes complex arguments such as nested objects and arrays much easier to build.

curl -X POST "$API_URL/companies.list" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
        "Filter": { "IsCustomer": true, "Name": "Horus" }
      }'

Filters

Most .list endpoints accept a Filter object:

filters on strings use a contains comparison (e.g. "Name": "Horus" matches Horus Software), unless stated otherwise in the API Reference;
an entity must match all specified filters to be returned;
omitted or null filters are ignored.

Many lists also offer ModifiedAfter / ModifiedBefore filters, which are ideal for incremental synchronisation (see Reading accounting data).

Dates

Dates are exchanged as ISO 8601 strings with a time zone offset, e.g. 2019-09-04T00:00:00+00:00.

Partial updates

On .update endpoints for master data (companies, accounts, daybooks…), provide only the fields you want to change, or leave them null:

null or omitted → the current value is kept;
"" (empty, non-null string) → the current value is erased.

Gzip compression

Gzip compression is available on every endpoint and highly recommended to reduce payload sizes. Add a Content-Encoding: gzip header to your request and the response will be gzipped automatically.