Skip to main content

​
Request body or query parameter?

One rule holds across the whole API:
  • the body of a request describes the resource itself — the data that will be stored (the fields of an invoice, a relation, a journal…);
  • query parameters configure the call — options that change its behavior without being stored, such as ?ignore_duplicate=true when creating a relation, ?type=purchase on a file import, or ?send_peppol=true to send an invoice right at creation.
A query parameter sent in the body is not ignored: the request is refused with a 422 naming the offending field.

​
Reading responses

Responses follow the same reading rules everywhere:
  • Amounts are JSON numbers — never strings.
  • A missing value is null — never an empty string: "phone": null means no phone is recorded.
  • A field that does not exist for the type is absent, not null: a company relation carries vat, identifier, electronic_address, is_customer, is_supplier; a contact carries first_name, last_name — each without the other’s fields.
  • An enumeration can read unknown — a historical value the API cannot classify comes out that way; handle it in your mappings.
Test for null to mean “no value”, and for the absence of the key to mean “not applicable to this type”.

​
Tracing a request

Every response carries an X-Request-ID header — an opaque identifier for that exact call on our side:
Record it alongside your own logs. When you contact support about a failed or surprising call, quote this value: it points us straight at that request’s trace and server logs, and removes the back-and-forth over when it happened and which endpoint. It is especially useful on a 500 internal_error.

​
Creating and updating

Three rules hold for every POST and PATCH:
  • All or nothing — a request that violates any rule is refused as a whole: an object is never created or updated halfway.
  • A PATCH applies only the fields present — omitting a field leaves it unchanged; there is no need to send the full object back.
  • An unknown or read-only field is an error — the request is refused with a 422 naming it, never silently ignored: a typo does not go unnoticed.