> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.fidly.be/llms.txt
> Use this file to discover all available pages before exploring further.

# Relations

> The third parties of the company: companies and individual contacts, unified.

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

|                         | `company`                                                               | `contact`                       |
| ----------------------- | ----------------------------------------------------------------------- | ------------------------------- |
| required at creation    | `type`, `name`, `address`                                               | `type`, `first_name`, `address` |
| optional, common        | `email`, `phone`, `language`                                            | `email`, `phone`, `language`    |
| optional, type-specific | `vat`, `identifier`, `electronic_address`, `is_customer`, `is_supplier` | `last_name`                     |

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`.

<Note>
  The duplicate check only concerns companies: a contact has none of these fields, and
  `?ignore_duplicate=true` on a contact returns `422 invalid_parameter`.
</Note>

## 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.

<Warning>
  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.
</Warning>

## 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.