Skip to main content
A relation is a third party of the company: either a company or an individual contact. Both come through the same resource; type (company | contact) says which one you are looking at.

​
Listing relations

GET /relations — paginated list. Filters: type, is_customer, is_supplier, vat, identifier. The company-only filters naturally exclude contacts when set.

​
Retrieving a relation

GET /relations/{id} — the full relation, with its address.

​
Company or contact

Fields that do not exist for a type are absent from the response, not null. A contact’s name is derived from first_name + last_name and cannot be set.

​
Creating a relation

POST /relations — requires the create permission on relations. The response is the full relation (201), as a later GET will return it.
  • language ∈ fr, en, nl, de — default en.
  • is_customer / is_supplier default to true.
  • Sending a field that belongs to the other type returns 422 field_not_editable.

​
Address

address is required, with at least country_code (ISO 3166-1 alpha-2, uppercased). Two rules always hold, otherwise 422 invalid_address: a relation can never end up without a country_code, and street_number cannot be set without street. province is free text (province, state or region depending on the country).

​
Duplicates

A company whose vat, identifier or electronic_address already belongs to another company of yours is refused (409 duplicate_relation), the message giving the id of the existing one. Empty values do not count. To create the duplicate anyway, add ?ignore_duplicate=true.
The duplicate check only concerns companies: a contact has none of these fields, and ?ignore_duplicate=true on a contact returns 422 invalid_parameter.

​
Updating a relation

PATCH /relations/{id} — requires the update permission on relations. Only the fields present in the body are applied; the response is the full relation. A request that violates any rule is refused as a whole.

​
Type

The type of a relation is set at creation: a company does not become a contact, nor the other way round. Changing it returns 422 field_not_editable — delete and recreate the relation.

​
Address merge

Every field sent replaces the stored value, except address, which is merged: sending only city fixes the city without re-sending the rest. The address rules are checked on the merged result.

​
Clearing a field

Sending null clears a field, except the ones creation makes required (name of a company, first_name of a contact, address).

​
Duplicates on update

The same rules as at creation apply: an update that would give a company the vat, identifier or electronic_address of another one is refused (409 duplicate_relation), unless ?ignore_duplicate=true is set.

​
Deleting a relation

DELETE /relations/{id} — requires the delete permission on relations. Returns 204. Deletion is definitive, and refused (409 relation_in_use) as long as anything still points at the relation: a document it issued or received, a subscription, a subscription invoice, a timesheet line, a project, or its match with the accounting system. The message says what blocks.
Deleting a relation also deletes its delivery locations and its links to contacts. The contacts themselves are never deleted with the company, only the links.

​
On documents

documents.relation_id carries the public UUID of the linked relation (relation_type gives its nature), resolvable through GET /relations/{id}. To issue a document, the relation must have an address.