> For the complete documentation index, see [llms.txt](https://docs.abby.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abby.fr/mcp/clients.md).

# Clients

Les outils clients permettent de gérer vos contacts (particuliers) et organisations (entreprises). Ces clients sont ensuite utilisables dans la facturation.

Abby distingue deux types de clients :

* **Contacts** — clients particuliers (personnes physiques)
* **Organisations** — clients professionnels (entreprises, associations, etc.)

Les organisations peuvent avoir plusieurs contacts associés. Les mêmes objets existent côté API REST : voir [Contacts](https://docs.abby.fr/reference-de-lapi/clients.md) et [Organisations](https://docs.abby.fr/reference-de-lapi/organisations.md). Les règles communes à tous les outils sont dans [Conventions](https://docs.abby.fr/mcp/conventions.md).

## Lecture

### `get-contacts`

Récupère les contacts avec pagination et recherche.

**Paramètres**

| Paramètre  | Type    | Requis | Description                               |
| ---------- | ------- | ------ | ----------------------------------------- |
| `page`     | number  | Non    | Numéro de page (défaut : 1)               |
| `limit`    | number  | Non    | Résultats par page, max 100 (défaut : 50) |
| `search`   | string  | Non    | Recherche par prénom ou nom               |
| `archived` | boolean | Non    | Filtrer par statut d'archivage            |

**Réponse**

```json
{
  "success": true,
  "total": 15,
  "page": 1,
  "limit": 50,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPrevPage": false,
  "contacts": [
    {
      "id": "string",
      "firstname": "Jean",
      "lastname": "Dupont",
      "emails": ["jean.dupont@email.com"],
      "phone": "+33612345678",
      "jobTitle": "Directeur technique",
      "organizationId": "string",
      "organizationName": "Dupont SARL",
      "notes": "",
      "addresses": [...],
      "archivedAt": null,
      "hasBillings": true,
      "createdAt": "…"
    }
  ]
}
```

**Scope** : `client:read`

***

### `get-contact-by-id`

Récupère un contact par son identifiant. Retourne les détails incluant nom, email, téléphone, poste, organisation et adresses.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |

**Scope** : `client:read`

***

### `get-organizations`

Récupère les organisations avec pagination et recherche.

**Paramètres**

| Paramètre  | Type    | Requis | Description                               |
| ---------- | ------- | ------ | ----------------------------------------- |
| `page`     | number  | Non    | Numéro de page (défaut : 1)               |
| `limit`    | number  | Non    | Résultats par page, max 100 (défaut : 50) |
| `search`   | string  | Non    | Recherche par nom                         |
| `archived` | boolean | Non    | Filtrer par statut d'archivage            |

**Réponse**

```json
{
  "success": true,
  "total": 8,
  "page": 1,
  "limit": 50,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPrevPage": false,
  "organizations": [
    {
      "id": "string",
      "name": "Dupont SARL",
      "commercialName": "Dupont & Fils",
      "emails": ["contact@dupont.fr"],
      "siret": "12345678901234",
      "vatNumber": "FR12345678901",
      "countContacts": 3,
      "notes": "",
      "addresses": [...],
      "archivedAt": null,
      "hasBillings": true,
      "createdAt": "…"
    }
  ]
}
```

**Scope** : `client:read`

***

### `get-organization-by-id`

Récupère une organisation par son identifiant. Retourne les détails incluant nom, SIRET, TVA, nombre de contacts et adresses.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

**Scope** : `client:read`

***

### `get-organization-contacts`

Récupère tous les contacts associés à une organisation.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

**Réponse**

```json
{
  "success": true,
  "total": 3,
  "organizationId": "string",
  "contacts": [
    {
      "id": "string",
      "firstname": "Marie",
      "lastname": "Martin",
      "emails": ["m.martin@dupont.fr"],
      "jobTitle": "Comptable",
      "defaultContact": true
    }
  ]
}
```

**Scope** : `client:read`

***

## Création

### `create-contact`

Crée un nouveau contact (client particulier). Nécessite au minimum un prénom et un nom.

**Paramètres**

| Paramètre                   | Type      | Requis | Description                                                                                                                     |
| --------------------------- | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `firstname`                 | string    | Oui    | Prénom                                                                                                                          |
| `lastname`                  | string    | Oui    | Nom de famille                                                                                                                  |
| `emails`                    | string\[] | Non    | Adresses email                                                                                                                  |
| `phone`                     | string    | Non    | Numéro de téléphone                                                                                                             |
| `jobTitle`                  | string    | Non    | Poste / fonction                                                                                                                |
| `notes`                     | string    | Non    | Notes libres                                                                                                                    |
| `billingAddress`            | object    | Non    | Adresse de facturation                                                                                                          |
| `billingAddress.address`    | string    | Oui    | Rue                                                                                                                             |
| `billingAddress.complement` | string    | Non    | Complément (bâtiment, étage, etc.)                                                                                              |
| `billingAddress.city`       | string    | Oui    | Ville                                                                                                                           |
| `billingAddress.zipCode`    | string    | Oui    | Code postal                                                                                                                     |
| `billingAddress.country`    | string    | Oui    | Code pays ISO 3166-1 alpha-2 (ex : `FR`, `GB`, `US`)                                                                            |
| `organizationId`            | string    | Non    | Identifiant d'une organisation de votre entreprise. Le contact est alors créé dans cette organisation et hérite de ses adresses |
| `deliveryAddress`           | object    | Non    | Adresse de livraison (même structure, exige une adresse de facturation)                                                         |

Avec `organizationId`, n'envoyez ni `billingAddress` ni `deliveryAddress`. Pour rattacher un contact à une nouvelle organisation, appelez d'abord `create-organization`, puis `create-contact` avec son identifiant.

**Scope** : `client:write`

***

### `create-organization`

Crée une nouvelle organisation (client professionnel). Nécessite au minimum un nom.

**Paramètres**

| Paramètre         | Type      | Requis | Description                                                             |
| ----------------- | --------- | ------ | ----------------------------------------------------------------------- |
| `name`            | string    | Oui    | Raison sociale                                                          |
| `commercialName`  | string    | Non    | Nom commercial                                                          |
| `emails`          | string\[] | Non    | Adresses email                                                          |
| `siret`           | string    | Non    | Numéro SIRET                                                            |
| `vatNumber`       | string    | Non    | Numéro de TVA intracommunautaire                                        |
| `notes`           | string    | Non    | Notes libres                                                            |
| `billingAddress`  | object    | Non    | Adresse de facturation (même structure que `create-contact`)            |
| `deliveryAddress` | object    | Non    | Adresse de livraison (même structure, exige une adresse de facturation) |

**Scope** : `client:write`

***

## Modification

### `update-contact`

Met à jour un contact existant. C'est un remplacement complet : envoyez toujours `firstname` et `lastname`, même s'ils ne changent pas, et renvoyez les champs facultatifs que vous voulez conserver (`emails`, `phone`, `jobTitle`, adresses). Lisez d'abord le contact avec `get-contact-by-id`.

**Paramètres**

| Paramètre         | Type      | Requis | Description                                             |
| ----------------- | --------- | ------ | ------------------------------------------------------- |
| `contactId`       | string    | Oui    | Identifiant du contact                                  |
| `firstname`       | string    | Oui    | Prénom                                                  |
| `lastname`        | string    | Oui    | Nom de famille                                          |
| `emails`          | string\[] | Non    | Adresses email                                          |
| `phone`           | string    | Non    | Numéro de téléphone                                     |
| `jobTitle`        | string    | Non    | Poste / fonction                                        |
| `billingAddress`  | object    | Non    | Adresse de facturation                                  |
| `deliveryAddress` | object    | Non    | Adresse de livraison (exige une adresse de facturation) |

{% hint style="info" %}
Cet outil ne modifie pas les notes. Pour les changer, utilisez `update-contact-notes`.
{% endhint %}

**Scope** : `client:write`

***

### `update-organization`

Met à jour une organisation existante. C'est un remplacement complet : envoyez toujours `name`, et renvoyez les champs facultatifs que vous voulez conserver (`commercialName`, `emails`, `siret`, `vatNumber`, adresses). Lisez d'abord l'organisation avec `get-organization-by-id`.

**Paramètres**

| Paramètre         | Type      | Requis | Description                                             |
| ----------------- | --------- | ------ | ------------------------------------------------------- |
| `organizationId`  | string    | Oui    | Identifiant de l'organisation                           |
| `name`            | string    | Oui    | Raison sociale                                          |
| `commercialName`  | string    | Non    | Nom commercial                                          |
| `emails`          | string\[] | Non    | Adresses email                                          |
| `siret`           | string    | Non    | Numéro SIRET                                            |
| `vatNumber`       | string    | Non    | Numéro de TVA                                           |
| `billingAddress`  | object    | Non    | Adresse de facturation                                  |
| `deliveryAddress` | object    | Non    | Adresse de livraison (exige une adresse de facturation) |

**Scope** : `client:write`

***

### `update-contact-notes`

Remplace les notes d'un contact. Envoyez une chaîne vide pour les effacer.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |
| `notes`     | string | Oui    | Nouvelles notes        |

**Scope** : `client:write`

***

### `update-organization-notes`

Remplace les notes d'une organisation. Envoyez une chaîne vide pour les effacer.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |
| `notes`          | string | Oui    | Nouvelles notes               |

**Scope** : `client:write`

***

## Suppression et archivage

### `delete-contact`

Supprime définitivement un contact. **Échoue si le contact a des documents de facturation** — utilisez `archive-contact` dans ce cas.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |

**Scope** : `client:write`

***

### `delete-organization`

Supprime définitivement une organisation. **Échoue si l'organisation a des contacts ou des documents de facturation** — utilisez `archive-organization` dans ce cas.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

**Scope** : `client:write`

***

### `archive-contact`

Archive un contact (suppression douce). Le contact n'apparaît plus dans les listes actives mais ses données sont conservées. **Préférez l'archivage à la suppression** quand le contact a des documents de facturation.

**Paramètres**

| Paramètre   | Type   | Requis | Description            |
| ----------- | ------ | ------ | ---------------------- |
| `contactId` | string | Oui    | Identifiant du contact |

**Scope** : `client:write`

***

### `archive-organization`

Archive une organisation. L'organisation n'apparaît plus dans les listes actives mais ses données sont conservées.

**Paramètres**

| Paramètre        | Type   | Requis | Description                   |
| ---------------- | ------ | ------ | ----------------------------- |
| `organizationId` | string | Oui    | Identifiant de l'organisation |

**Scope** : `client:write`

***

## Scopes requis

| Outil                                                                                                                                                                                                                     | Scope          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `get-contacts`, `get-contact-by-id`, `get-organizations`, `get-organization-by-id`, `get-organization-contacts`                                                                                                           | `client:read`  |
| `create-contact`, `create-organization`, `update-contact`, `update-organization`, `update-contact-notes`, `update-organization-notes`, `delete-contact`, `delete-organization`, `archive-contact`, `archive-organization` | `client:write` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.abby.fr/mcp/clients.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
