**Versions de l’API** · [V2 (Latest)](/integrations/v2/docs?lang=fr) · **V1**

> **Cette version de l’API est obsolète.** Utilisez la dernière version pour toute nouvelle intégration. [Voir la documentation actuelle](/integrations/v2/docs?lang=fr)

# Contacts

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Donateurs/membres de l’organisation — opérations d’écriture complètes avec noms de champs anglais explicites (firstName, lastName, gender "M"/"F", email, phone, birthDate, tags, customFields, relationship SPOUSE/PARENT/CHILD…). Lecture (liste/recherche/obtention), CRUD d’identité (create = upsert qui ne remplit que les champs vides, avec dédoublonnage par téléphone/email ; PATCH = remplacement explicite) et sous-ressources (adresses/téléphones/emails/catégories/champs personnalisés typés/liens familiaux/enfants/interactions/documents). `tags` sont des étiquettes booléennes ; `customFields` des paires clé/valeur typées — ne les confondez pas. Les interactions consignent appels, visites et notes dans un historique dédié. Les documents sont des fichiers associés au contact (reçus, scans de pièces d’identité…) : téléversez-les via POST /uploads/pdf|image puis joignez-les par leur nom de fichier, ou indiquez directement une URL http(s). Parcours guidé d’import de tableur : `get_contact_import_schema` (catalogue des champs et alias pour associer les colonnes), `normalize_contacts` (nettoyage pur par colonne : phone→E.164, email, birthDate→ISO, civilité→genre), `lookup_contacts` (dédoublonnage par lot, sans écriture) et `import_contacts` (upsert en masse ≤ 500 lignes, avec plan `dryRun` par ligne). Parcours Excel type : obtenir le schéma → associer les colonnes → normaliser → rechercher les correspondances → dryRun → corriger les erreurs → importer. Autorisations : `contacts:read`/`contacts:write`.

## Opérations

## GET /contacts

Lister les contacts

`list_contacts`

Autorisation requise : `contacts:read`. Liste/filtre les contacts de l’organisation, chacun renvoyé dans sa structure complète (identité + sous-collections). `email`/`phone` sont ici des correspondances scalaires EXACTES (pour une recherche floue de doublon, utilisez GET /contacts/search). Résultats paginés.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre de résultats par page."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Curseur opaque renvoyé par la requête précédente."
}
```

```json
{
  "name": "createdAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Filtre : créé après cette date (ISO 8601)."
}
```

```json
{
  "name": "updatedAfter",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "date-time"
  },
  "description": "Contacts modifiés après cette date uniquement."
}
```

```json
{
  "name": "email",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Correspondance exacte (en minuscules) de l’email principal."
}
```

```json
{
  "name": "phone",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Correspondance exacte du téléphone principal."
}
```

```json
{
  "name": "tag",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Filtrer par catégorie (normalisée, par ex. \"Donateur\" → DONATEUR)."
}
```

```json
{
  "name": "isLocal",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "Filtrer par indicateur de proximité « local » (true/false)."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts

Créer ou compléter un contact

`create_contact`

Autorisation requise : `contacts:write`. UPSERT INTELLIGENT : si un contact avec ce `phone` ou cet `email` (normalisé) existe déjà, il est MIS À JOUR uniquement pour remplir les champs vides — les valeurs d’identité existantes ne sont JAMAIS remplacées ; téléphones/emails/adresses/catégories/champs personnalisés secondaires sont ajoutés, et la réponse indique `created:false`. Seule une véritable insertion déclenche le webhook `contact.created`. Fournissez `?forceCreate=true` pour toujours insérer un nouveau document. Pour REMPLACER une valeur d’identité connue, utilisez plutôt PATCH /contacts/{id}. À la création, si aucun `tags` n’est fourni, la catégorie source `#API` est définie. Formats : `gender` "M"/"F"/null (jamais une civilité), `phone` tout format → E.164, `birthDate` ISO. `tags` sont des étiquettes booléennes ; `customFields` sont des paires clé/valeur typées (upsert par clé ; NUMBER/DATETIME enregistrés comme TEXT).

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "forceCreate",
  "in": "query",
  "schema": {
    "type": "boolean"
  },
  "description": "true → toujours insérer un nouveau contact, même si un téléphone/email correspond à un contact existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCreateInput"
      },
      "example": {
        "firstName": "david",
        "lastName": "levy",
        "gender": "M",
        "email": "David.Levy@GMAIL.com ",
        "phone": "06 11 22 33 44",
        "tags": [
          "Donateur"
        ],
        "customFields": [
          {
            "key": "classe",
            "type": "TEXT",
            "value": "CM2"
          }
        ]
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "created": {
                "type": "boolean",
                "description": "true = un nouveau contact a été inséré ; false = un contact existant a été mis à jour en remplissant uniquement les champs vides."
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "ERREUR_DE_VALIDATION",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/search

Rechercher un contact par téléphone/email (dédoublonnage)

`search_contacts`

Autorisation requise : `contacts:read`. Recherche avant création pour dédoublonner : normalise `email`/`phone` et renvoie l’unique contact correspondant (`{found, contact}`) — ce n’est PAS une liste paginée. À utiliser avant create_contact pour savoir si le contact existe déjà. Fournissez au moins `email` ou `phone`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "email",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Email à faire correspondre (normalisé)."
}
```

```json
{
  "name": "phone",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Téléphone à faire correspondre (normalisé)."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "found": {
                "type": "boolean"
              },
              "contact": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Contact"
                  }
                ],
                "nullable": true
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "PARAMÈTRE_REQUIS",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_QUERY"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/import/schema

Découvrir les champs et options importables

`get_contact_import_schema`

Autorisation requise : `contacts:read`. Guide d’importation auto-descriptif — appelez-le EN PREMIER pour découvrir chaque champ importable (avec ses alias pour associer les colonnes du tableur) et les options disponibles, puis exécutez normalisation → recherche → import dryRun → import. Renvoie `fields[]` ({key, label, type, kind, multi, example, description, aliases[]}) et `options` (dedupStrategy, defaultPhoneCountry, dateFormat, requireContact, applyTags). Reprend l’étape d’association des colonnes de la page ImportPage de l’admin.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ContactImportSchema"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/normalize

Normaliser les lignes d’un tableur (sans enregistrement)

`normalize_contacts`

Autorisation requise : `contacts:read`. Normalisation PURE des lignes de tableur non nettoyées, colonne par colonne — aucune base de données ni donnée d’organisation n’est modifiée. Pour chaque ligne, nettoie phone→E.164 (+ pays détecté), email, birthDate→ISO et civilité→`gender` "M"/"F", et signale les `issues`. ÉTAPE 2 du parcours d’import Excel (après get_contact_import_schema ; ensuite lookup_contacts, puis import_contacts dryRun). Exemple : `{phone:"06 12 34 56 78", birthDate:"15/03/1990", gender:"Mme", firstName:"sarah", category:"Séder night"}` → `{phone:{e164:"+33612345678", country:"FR", valid:true}, birthDate:{value:"1990-03-15", valid:true}, gender:"F", firstName:"Sarah", tags:["SEDER_NIGHT"]}`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactNormalizeInput"
      },
      "example": {
        "rows": [
          {
            "phone": "06 12 34 56 78",
            "birthDate": "15/03/1990",
            "gender": "Mme",
            "firstName": "sarah",
            "category": "Séder night"
          }
        ],
        "defaultPhoneCountry": "FR"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/NormalizeResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/lookup

Rechercher les correspondances par lot (sans écriture)

`lookup_contacts`

Autorisation requise : `contacts:read`. Pour chaque élément, recherche le contact correspondant de l’organisation SANS rien écrire (un contact supprimé logiquement n’est jamais réactivé). ÉTAPE 3 du parcours d’import Excel : exécutez après normalize_contacts pour repérer les lignes déjà présentes (`matchedContactId`) avant l’import.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLookupInput"
      },
      "example": {
        "items": [
          {
            "phone": "+33611223344"
          },
          {
            "email": "david.levy@gmail.com"
          }
        ],
        "defaultPhoneCountry": "FR"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/LookupResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/import

Importer des contacts en masse (simulation + import réel)

`import_contacts`

Autorisation requise : `contacts:write`. Upsert en masse de 500 lignes maximum (500+ → 400 IMPORT_TOO_LARGE ; répartissez vous-même le fichier). ÉTAPE 4 du parcours Excel : appelez d’ABORD avec `dryRun:true` pour obtenir le PLAN par ligne (`report.lines[].action` = create/update/skip/error + `issues`), SANS rien enregistrer ; corrigez les lignes signalées `error`, puis rappelez avec `dryRun:false`. `options.dedupStrategy` = skip|update|create (update par défaut). Exemple de simulation `{contacts:[{__row:2, lastName:"cohen", phone:"061122", birthDate:"32/13/1990"}], dryRun:true}` → `report.lines:[{row:2, action:"error", issues:[{field:"phone", reason:"INVALID_PHONE", severity:"error"}, {field:"birthDate", reason:"INVALID_DATE", severity:"error"}]}]`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportInput"
      },
      "example": {
        "contacts": [
          {
            "__row": 2,
            "firstName": "sarah",
            "lastName": "cohen",
            "phone": "06 12 34 56 78",
            "birthDate": "15/03/1990"
          }
        ],
        "options": {
          "dedupStrategy": "update",
          "applyTags": [
            "Import 2026"
          ]
        },
        "dryRun": true
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ImportResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "IMPORT_TROP_VOLUMINEUX",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "IMPORT_TOO_LARGE"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/{id}

Obtenir un contact

`get_contact`

Autorisation requise : `contacts:read`. Renvoie le contact complet (identité + addresses/secondaryPhones/secondaryEmails/tags/customFields/familyLinks). Renvoie 404 (jamais 403) si l’identifiant appartient à une autre organisation.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Contact"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERREUR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "AUTORISATION_INSUFFISANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /contacts/{id}

Modifier l’identité d’un contact (remplacement explicite)

`update_contact`

Autorisation requise : `contacts:write`. REMPLACEMENT EXPLICITE des champs d’identité (liste autorisée + nouvelle normalisation) — contrairement à create_contact, cette opération REMPLACE la valeur enregistrée. Les sous-collections (téléphones/emails/adresses secondaires, catégories, customFields) ne sont PAS modifiées — utilisez les opérations dédiées aux sous-ressources. Une chaîne vide ("") signifie « ne pas modifier » (ajout uniquement : l’identité n’est jamais effacée). Une valeur invalide pour `email`, `phone` ou `birthDate` entraîne une erreur 400.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactUpdateInput"
      },
      "example": {
        "lastName": "LEVY",
        "gender": "M",
        "email": "d.levy@pro.com"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_EMAIL, INVALID_PHONE ou INVALID_DATE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_EMAIL, INVALID_PHONE or INVALID_DATE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/addresses

Ajouter une adresse

`add_contact_address`

Autorisation requise : `contacts:write`. Ajoute une adresse : PRINCIPALE si le contact n’en possède aucune (ou si `main:true`), sinon adresse SECONDAIRE dédoublonnée (avec identifiant stable, modifiable ensuite).

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactAddressInput"
      },
      "example": {
        "label": "Bureau",
        "type": "PRO",
        "address": "12 rue de la Paix",
        "postalCode": "75002",
        "city": "Paris"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "ADRESSE_MANQUANTE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_ADDRESS"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## PATCH /contacts/{id}/addresses/{addressId}

Modifier une adresse secondaire

`update_contact_address`

Autorisation requise : `contacts:write`. Fusionne les champs fournis dans l’adresse SECONDAIRE désignée par `addressId` (UUID provenant de `adresses[].id`). Seuls les champs fournis sont modifiés. L’adresse PRINCIPALE n’a pas d’identifiant et ne peut pas être modifiée ici — utilisez PATCH /contacts/{id} ou POST /contacts/{id}/addresses avec main:true. 404 ADDRESS_NOT_FOUND si l’identifiant ne désigne pas une adresse secondaire de ce contact.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "addressId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Identifiant de l’adresse secondaire (issu de `adresses[].id`)."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactAddressPatchInput"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou ADDRESS_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND or ADDRESS_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/phones

Ajouter un téléphone secondaire

`add_contact_phone`

Autorisation requise : `contacts:write`. Ajoute un téléphone SECONDAIRE (E.164, après dédoublonnage). Le téléphone principal se définit via create_contact / update_contact. 400 INVALID_PHONE si le numéro ne peut pas être analysé.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPhoneInput"
      },
      "example": {
        "phone": "06 98 76 54 32",
        "phoneCountry": "FR"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_PHONE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_PHONE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/{id}/emails

Ajouter un email secondaire

`add_contact_email`

Autorisation requise : `contacts:write`. Ajoute un email SECONDAIRE (après dédoublonnage). L’email principal se définit via create_contact / update_contact. 400 INVALID_EMAIL si l’email est invalide.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactEmailInput"
      },
      "example": {
        "email": "perso@gmail.com"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_EMAIL",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INVALID_EMAIL"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## POST /contacts/{id}/tags

Ajouter une ou plusieurs catégories

`add_contact_tags`

Autorisation requise : `contacts:write`. Ajoute une ou plusieurs catégories (idempotent — une nouvelle attribution ne fait rien). Chacune est normalisée (majuscules, sans accents, espaces→`_`, par ex. "Séder night" → SEDER_NIGHT). Une catégorie est une étiquette booléenne — PAS un champ personnalisé clé/valeur (voir POST /contacts/{id}/custom-fields).

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagsInput"
      },
      "example": {
        "tags": [
          "Donateur régulier",
          "Séder night"
        ]
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "CATÉGORIES_MANQUANTES",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_TAGS"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/tags/{tag}

Retirer une catégorie

`remove_contact_tag`

Autorisation requise : `contacts:write`. Retire UNE catégorie du contact (sans effet si elle est absente). `tag` est une chaîne libre (encodez `#FORM` dans l’URL) ; elle est normalisée de la même façon qu’à l’ajout.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "tag",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Catégorie à retirer (encodée pour l’URL ; normalisée côté serveur)."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/custom-fields

Définir des champs personnalisés (upsert par clé)

`set_contact_custom_fields`

Autorisation requise : `contacts:write`. Met à jour les champs personnalisés typés PAR CLÉ (réécrire la même clé met à jour le champ existant unique, sans doublon). `override` (true par défaut — modification explicite) remplace la valeur ; false ne remplit que les champs vides. `type` est réduit à TEXT/DATE/BOOL — NUMBER/DATETIME sont enregistrés comme TEXT. Les champs personnalisés sont distincts des catégories.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCustomFieldsInput"
      },
      "example": {
        "customFields": [
          {
            "key": "classe",
            "type": "TEXT",
            "value": "CM2"
          },
          {
            "key": "casher",
            "type": "BOOL",
            "value": true
          }
        ]
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "CHAMPS_PERSONNALISÉS_MANQUANTS",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_CUSTOM_FIELDS"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/custom-fields/{key}

Supprimer un champ personnalisé

`remove_contact_custom_field`

Autorisation requise : `contacts:write`. Supprime un champ personnalisé par clé (insensible à la casse et au séparateur : `_` et `-` sont équivalents). Sans effet si le champ est absent.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "key",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Clé du champ à supprimer (encodée pour l’URL ; insensible à la casse/au séparateur)."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/family

Ajouter un lien familial

`add_contact_family_link`

Autorisation requise : `contacts:write`. Ajoute un lien familial BIDIRECTIONNEL entre ce contact et `relatedContactId` (le lien inverse est ajouté automatiquement). `relatedContactId` DOIT appartenir à la même organisation (sinon 404 — aucun oracle inter-organisations). 400 UNKNOWN_RELATIONSHIP pour une valeur `relationship` hors énumération ; 400 SELF_LINK si le lien cible le contact lui-même.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactFamilyLinkInput"
      },
      "example": {
        "relationship": "PARENT",
        "relatedContactId": "b3f1c2d4-5678-49ab-8cde-0123456789ab"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UNKNOWN_RELATIONSHIP ou SELF_LINK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "UNKNOWN_RELATIONSHIP or SELF_LINK"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou RELATED_CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND or RELATED_CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/family/{relatedContactId}

Supprimer un lien familial

`remove_contact_family_link`

Autorisation requise : `contacts:write`. Supprime le lien familial (et son inverse) entre ce contact et `relatedContactId`. `?relationship` précise quel lien supprimer. `relatedContactId` doit appartenir à l’organisation (sinon 404).

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "relatedContactId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Identifiant du contact associé."
}
```

```json
{
  "name": "relationship",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "SPOUSE",
      "PARENT",
      "CHILD",
      "SIBLING",
      "GRANDPARENT",
      "GRANDCHILD",
      "IN_LAW",
      "EX",
      "COUSIN",
      "FRIEND"
    ]
  },
  "description": "Lien familial à supprimer (OBLIGATOIRE — son omission renvoie 400 UNKNOWN_RELATIONSHIP)."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UNKNOWN_RELATIONSHIP",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "UNKNOWN_RELATIONSHIP"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou RELATED_CONTACT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND or RELATED_CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/children

Ajouter un enfant

`add_contact_child`

Autorisation requise : `contacts:write`. Ajoute un enfant en bas âge (sans téléphone/email) dont les parents sont ce contact et son éventuel conjoint SPOUSE détecté. Dédoublonnage par prénom parmi les enfants des parents : un enfant existant est réutilisé (`created:false`), sinon un nouveau contact enfant est créé. Un lien PARENT↔CHILD est créé automatiquement. Exemple `{firstName:"Rivka", birthDate:"2015-09-01"}`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactChildInput"
      },
      "example": {
        "firstName": "Rivka",
        "birthDate": "2015-09-01"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "created": {
                "type": "boolean",
                "description": "false = un enfant existant a été réutilisé."
              },
              "childId": {
                "type": "string"
              },
              "data": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FIRST_NAME",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FIRST_NAME"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/{id}/interactions

Lister les interactions d’un contact

`list_contact_interactions`

Autorisation requise : `contacts:read`. Renvoie les interactions consignées (appels, visites, notes) pour ce contact, de la plus récente à la plus ancienne, avec pagination par curseur. Une interaction est une entrée `contact_activity` — distincte d’un champ personnalisé ou d’une catégorie.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Nombre de résultats par page."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Curseur opaque renvoyé par la requête précédente."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactInteraction"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/interactions

Consigner une interaction

`add_contact_interaction`

Autorisation requise : `contacts:write`. Consigne un échange avec le contact (appel, visite, note). `type` est obligatoire — pour rester cohérent, réutilisez une valeur de GET /contacts/{id}/interactions/types. Exemple `{type:"Appel", content:"Rappelé pour la campagne de Pessah", actions:["Discussion"]}`.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionInput"
      },
      "example": {
        "type": "Appel",
        "content": "Rappelé pour la campagne de Pessah",
        "actions": [
          "Discussion"
        ]
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/ContactInteraction"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_TYPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_TYPE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /contacts/{id}/interactions/types

Lister les types d’interaction

`list_contact_interaction_types`

Autorisation requise : `contacts:read`. Renvoie les libellés distincts de `type` déjà utilisés dans l’organisation (ainsi que les valeurs courantes par défaut comme « Appel », « Visite »). Choisissez l’un d’eux lors de la consignation pour assurer la cohérence CRM et éviter les libellés presque identiques.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/documents

Lister les documents d’un contact

`list_contact_documents`

Autorisation requise : `contacts:read`. Fichiers associés au contact (reçus, scans de pièce d’identité, mandats signés…), du plus récent au plus ancien. Chacun possède un `id` (pour le supprimer), un `name`, un `filename` hébergé et une `url` de téléchargement.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ContactDocument"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/{id}/documents

Joindre un document

`create_contact_document`

Autorisation requise : `contacts:write`. Associe un document au contact. « Téléverser d’abord, joindre ensuite » : fournissez SOIT un `filename` déjà hébergé via POST /uploads/pdf|image, SOIT une `url` http(s) réhébergée côté serveur (image/PDF uniquement). `name` facultatif pour le libellé.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDocumentInput"
      },
      "example": {
        "url": "https://example.com/receipt-2026.pdf",
        "name": "Reçu fiscal 2026"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "$ref": "#/components/schemas/ContactDocument"
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "MISSING_FILE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "MISSING_FILE"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_INTROUVABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CONTACT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## DELETE /contacts/{id}/documents/{docId}

Détacher un document

`delete_contact_document`

Autorisation requise : `contacts:write`. Retire un document du contact par son `docId` (le fichier reste hébergé). Renvoie 404 si le contact ou l’identifiant du document est inconnu ici.

### Authentification

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Permissions requises

```json
{
  "accepted": "contacts:write",
  "additional": []
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
  },
  "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
}
```

```json
{
  "name": "docId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "Identifiant du document renvoyé par GET /contacts/{id}/documents."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "deleted": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "DOCUMENT_NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "DOCUMENT_NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## Schémas

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Nombre de résultats par page."
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Curseur opaque renvoyé par la requête précédente."
      },
      "CreatedAfterParam": {
        "name": "createdAfter",
        "in": "query",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "description": "Filtre : créé après cette date (ISO 8601)."
      },
      "IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
        },
        "description": "Identifiant de ressource — doit être un UUID. Un identifiant mal formé est refusé avec 400 INVALID_UUID (pas simplement 404). Besoin d’un nouvel identifiant ? Appelez GET /utils/uuid."
      }
    },
    "schemas": {
      "Contact": {
        "type": "object",
        "description": "Un contact (donateur / membre) de l’organisation. Les champs d’identité sont à plat ; les sous-collections à valeurs multiples (adresses, téléphones et emails secondaires, balises, champs personnalisés, liens familiaux) sont des tableaux. Tous les champs `readOnly` sont calculés et ne sont jamais acceptés lors d’une écriture.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "UUID généré par le serveur. Utilisez-le comme `{id}` dans chaque chemin de sous-ressource."
          },
          "firstName": {
            "type": "string",
            "description": "Prénom. Enregistré avec une majuscule initiale (« david » → « David »)."
          },
          "lastName": {
            "type": "string",
            "description": "Nom de famille. Enregistré EN MAJUSCULES (« levy » → « LEVY »)."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F"
            ],
            "nullable": true,
            "description": "Genre : « M » (masculin) ou « F » (féminin), null = inconnu. Déduit de la civilité lors de l’importation — jamais deviné."
          },
          "email": {
            "type": "string",
            "description": "Email principal (en minuscules). Les emails supplémentaires se trouvent dans `secondaryEmails[]`."
          },
          "phone": {
            "type": "string",
            "description": "Téléphone principal au format E.164 (`+33612345678`). Les numéros supplémentaires se trouvent dans `secondaryPhones[]`."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Date de naissance, au format ISO `YYYY-MM-DD`."
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Prénom hébraïque."
          },
          "taxId": {
            "type": "string",
            "nullable": true,
            "description": "Identifiant national / fiscal (par ex. Teudat Zehut israélienne). Déclaratif — aucune vérification auprès d’un registre."
          },
          "giftAid": {
            "type": "boolean",
            "description": "Indicateur d’éligibilité au Gift Aid britannique. Déclaratif."
          },
          "address": {
            "type": "string",
            "description": "Adresse principale — ligne de rue (à plat, sans identifiant)."
          },
          "postalCode": {
            "type": "string",
            "description": "Adresse principale — code postal."
          },
          "city": {
            "type": "string",
            "description": "Adresse principale — ville."
          },
          "region": {
            "type": "string",
            "description": "Adresse principale — état / région / province."
          },
          "country": {
            "type": "string",
            "description": "Adresse principale — pays."
          },
          "note": {
            "type": "string",
            "nullable": true,
            "description": "Note libre sur l’adresse principale."
          },
          "addresses": {
            "type": "array",
            "description": "Adresses SECONDAIRES (chacune avec un UUID `id` stable — modifiables via PATCH /contacts/{id}/addresses/{addressId}). L’adresse principale est représentée à plat par les champs `address`/`postalCode`/`city` ci-dessus et ne possède AUCUN identifiant.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "readOnly": true
                },
                "label": {
                  "type": "string",
                  "description": "Libellé libre de l’adresse (par ex. « Bureau »)."
                },
                "type": {
                  "type": "string",
                  "nullable": true,
                  "description": "PRO | PERSO (libellé libre)."
                },
                "address": {
                  "type": "string",
                  "description": "Ligne de rue."
                },
                "postalCode": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "companyId": {
                  "type": "string",
                  "nullable": true,
                  "description": "Numéro d’immatriculation de l’entreprise (pour une adresse PRO)."
                },
                "note": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "secondaryPhones": {
            "type": "array",
            "description": "Téléphones supplémentaires (E.164). Le numéro principal est `phone`.",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string"
                }
              }
            }
          },
          "secondaryEmails": {
            "type": "array",
            "description": "Emails supplémentaires. L’email principal est `email`.",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                }
              }
            }
          },
          "tags": {
            "type": "array",
            "description": "Balises de catégorie — étiquettes booléennes (en majuscules et sans accents, par ex. `DONATEUR`, `#FORM`). Ce ne sont PAS des champs personnalisés clé/valeur — voir `customFields[]`.",
            "items": {
              "type": "string"
            }
          },
          "customFields": {
            "type": "array",
            "description": "Champs personnalisés typés clé/valeur. Une entrée par clé (jamais de doublon). `type` vaut uniquement TEXT/DATE/BOOL — NUMBER/SELECT sont enregistrés en TEXT. À distinguer de `tags[]`.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "readOnly": true
                },
                "key": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "description": "TEXT | DATE | BOOL"
                },
                "value": {
                  "nullable": true,
                  "description": "Valeur enregistrée (chaîne, date ISO ou booléen)."
                }
              }
            }
          },
          "familyLinks": {
            "type": "array",
            "description": "Liens familiaux. `contactId` = contact associé, `relationship` = SPOUSE/PARENT/CHILD/SIBLING/GRANDPARENT/GRANDCHILD/IN_LAW/EX/COUSIN/FRIEND. Bidirectionnels (le lien inverse se trouve sur l’autre contact).",
            "items": {
              "type": "object",
              "properties": {
                "relationship": {
                  "type": "string",
                  "enum": [
                    "SPOUSE",
                    "PARENT",
                    "CHILD",
                    "SIBLING",
                    "GRANDPARENT",
                    "GRANDCHILD",
                    "IN_LAW",
                    "EX",
                    "COUSIN",
                    "FRIEND"
                  ],
                  "nullable": true
                },
                "contactId": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "isLocal": {
            "type": "boolean",
            "readOnly": true,
            "description": "Indique si le contact est un contact de proximité « local » (habite dans la zone d’action de l’organisation) ; défini automatiquement ou manuellement."
          },
          "isLocalSource": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "Comment `isLocal` a été défini : AUTO | MANUAL | null."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Date de création."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "Date de dernière modification."
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "ContactCreateInput": {
        "type": "object",
        "description": "Identité d’un contact à CRÉER ou à INSÉRER/REMPLACER (UPSERT). Tous les champs sont facultatifs — un simple `phone` ou `email` suffit pour créer un contact utile. Formats : `gender` = « M » (masculin), « F » (féminin) ou null (inconnu — JAMAIS « Mr »/« Mme ») ; `phone` accepte une chaîne non normalisée (« 06 11 22 33 44 »), convertie au format E.164 ; `birthDate` au format ISO `YYYY-MM-DD` ; chaque entrée de `tags` est convertie en majuscules et sans accents (« Donateur régulier » → « DONATEUR_REGULIER »). Les `tags` sont des catégories booléennes ; `customFields` contient des champs typés clé/valeur — ne les confondez pas.",
        "required": [],
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Prénom (enregistré avec une majuscule initiale)."
          },
          "lastName": {
            "type": "string",
            "description": "Nom de famille (enregistré EN MAJUSCULES)."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F"
            ],
            "nullable": true,
            "description": "« M » (masculin), « F » (féminin) ou null (inconnu). Jamais une civilité telle que « Mr »/« Mme »."
          },
          "email": {
            "type": "string",
            "description": "Email principal. Les emails non valides sont ignorés."
          },
          "phone": {
            "type": "string",
            "description": "Téléphone principal (n’importe quel format ; converti au format E.164). Fournissez `phoneCountry` pour les numéros locaux sans indicatif de pays."
          },
          "phoneCountry": {
            "type": "string",
            "description": "Code pays ISO 3166-1 alpha-2 (par ex. « FR », « IL ») utilisé pour normaliser un `phone`/`phones` local sans préfixe `+`."
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Téléphones supplémentaires (secondaires)."
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Emails supplémentaires (secondaires)."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Date de naissance au format ISO `YYYY-MM-DD`. Lors d’un upsert, renseignée uniquement si vide (jamais remplacée)."
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Prénom hébraïque."
          },
          "taxId": {
            "type": "string",
            "description": "Identifiant national / fiscal (par ex. Teudat Zehut israélienne). Déclaratif."
          },
          "giftAid": {
            "type": "boolean",
            "description": "Indicateur Gift Aid britannique. Déclaratif."
          },
          "address": {
            "type": "string",
            "description": "Adresse postale principale. Si le contact possède déjà une adresse principale, celle-ci est ajoutée comme adresse secondaire."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "description": "État / région / province."
          },
          "country": {
            "type": "string",
            "description": "Pays (par défaut : « France »)."
          },
          "note": {
            "type": "string",
            "description": "Note libre sur l’adresse principale."
          },
          "addresses": {
            "type": "array",
            "description": "Adresses SECONDAIRES supplémentaires à ajouter.",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "description": "PRO | PERSO"
                },
                "address": {
                  "type": "string"
                },
                "postalCode": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "companyId": {
                  "type": "string",
                  "description": "Numéro d’immatriculation de l’entreprise (pour une adresse PRO)."
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Balises de catégorie à associer (chacune normalisée EN MAJUSCULES). À la CRÉATION, la première balise sert de catégorie initiale ; en l’absence de balise, la balise source `#API` est définie."
          },
          "customFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactFieldEntry"
            },
            "description": "Champs personnalisés typés clé/valeur (upsert par clé). Lors de la création/importation, ils ne renseignent que les champs vides (ajout uniquement). À distinguer de `tags[]`."
          }
        }
      },
      "ContactFieldEntry": {
        "type": "object",
        "description": "Champ personnalisé typé. À l’enregistrement, `type` est réduit à TEXT/DATE/BOOL — NUMBER/SELECT/etc. sont enregistrés comme TEXT (la valeur récupérée reste une chaîne).",
        "required": [
          "key"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Clé du champ (insensible à la casse ; `_` et `-` sont équivalents). Upsert par clé : écrire deux fois la même clé met à jour l’unique champ existant, sans jamais créer de doublon."
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "DATETIME",
              "BOOL"
            ],
            "description": "TEXT | NUMBER | DATE | DATETIME | BOOL. NUMBER/DATETIME sont enregistrés comme TEXT.",
            "default": "TEXT"
          },
          "value": {
            "description": "Valeur du champ (chaîne / nombre / date ISO / booléen)."
          }
        }
      },
      "ContactImportSchema": {
        "type": "object",
        "description": "Guide d’importation auto-descriptif : catalogue des champs importables (chacun avec ses alias permettant de faire correspondre les colonnes du tableur) et options d’importation disponibles. Appelez-le EN PREMIER, associez vos colonnes à ces clés de champ, puis exécutez : normalisation → recherche des correspondances → import dryRun → import.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "fields": {
            "type": "array",
            "description": "Chaque champ public importable.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Clé du champ public à utiliser dans les lignes de normalisation/import (par ex. \"firstName\", \"phone\", \"tags\")."
                },
                "label": {
                  "type": "string",
                  "description": "Libellé destiné à l’utilisateur."
                },
                "type": {
                  "type": "string",
                  "description": "string | enum | date | boolean | object[]."
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "identity",
                    "address",
                    "contact",
                    "tag",
                    "customField"
                  ],
                  "description": "Partie du contact alimentée par ce champ."
                },
                "multi": {
                  "type": "boolean",
                  "description": "Indique si le champ accepte plusieurs valeurs (par ex. tags, téléphones secondaires)."
                },
                "example": {
                  "description": "Valeur d’exemple."
                },
                "description": {
                  "type": "string"
                },
                "aliases": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "En-têtes de colonnes courants des tableurs FR/EN correspondant à ce champ — utilisez-les pour associer automatiquement vos colonnes."
                }
              }
            }
          },
          "options": {
            "type": "object",
            "description": "Options d’importation (dedupStrategy, defaultPhoneCountry, dateFormat, requireContact, applyTags), avec leurs valeurs autorisées et valeurs par défaut ; elles reprennent l’étape d’import de la page ImportPage de l’admin.",
            "additionalProperties": true
          }
        }
      },
      "ContactNormalizeInput": {
        "type": "object",
        "description": "Lignes de colonnes brutes (issues d’Excel/CSV non nettoyés) à normaliser colonne par colonne. Opération PURE — aucune base de données ni donnée d’organisation n’est modifiée. À utiliser EN PREMIER lors de l’import d’un tableur : nettoie téléphone→E.164 (+ pays détecté), email, birthDate→ISO et civilité→gender « M »/« F », et signale les `issues` de chaque ligne.",
        "required": [
          "rows"
        ],
        "properties": {
          "rows": {
            "type": "array",
            "description": "Chaque objet contient les valeurs brutes des cellules d’une ligne du tableur.",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string",
                  "description": "Téléphone brut, par ex. \"06 12 34 56 78\"."
                },
                "email": {
                  "type": "string",
                  "description": "Email brut, par ex. \"David.Levy@GMAIL.com \"."
                },
                "birthDate": {
                  "type": "string",
                  "description": "Date de naissance brute, par ex. \"15/03/1990\" (JJ/MM/AAAA par défaut)."
                },
                "lastName": {
                  "type": "string"
                },
                "firstName": {
                  "type": "string"
                },
                "gender": {
                  "type": "string",
                  "description": "Civilité/genre brut, par ex. \"Mme\", \"Mr\", \"מר\", \"M\", \"F\" → genre \"M\"/\"F\"."
                },
                "category": {
                  "type": "string",
                  "description": "Balise de catégorie brute, par ex. \"Séder night\" → SEDER_NIGHT."
                }
              }
            }
          },
          "defaultPhoneCountry": {
            "type": "string",
            "description": "Pays ISO 3166-1 alpha-2 (par ex. \"FR\") pour normaliser les téléphones locaux sans indicatif de pays. Par défaut : \"ZZ\" (aucun)."
          },
          "dateFormat": {
            "type": "string",
            "description": "Indication pour les dates ambiguës (par ex. \"M/D/YYYY\" pour les fichiers américains). Les dates sont analysées avec un analyseur de dates, JAMAIS avec new Date(). Jour en premier (JJ/MM/AAAA) par défaut."
          }
        }
      },
      "NormalizeResult": {
        "type": "object",
        "description": "Résultat de normalisation pour chaque ligne. Consultez `valid`/`country` pour chaque colonne afin de déterminer les corrections à apporter avant l’importation.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "phone": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string"
                    },
                    "e164": {
                      "type": "string",
                      "nullable": true
                    },
                    "national": {
                      "type": "string",
                      "nullable": true
                    },
                    "country": {
                      "type": "string",
                      "nullable": true
                    },
                    "valid": {
                      "type": "boolean"
                    }
                  }
                },
                "email": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string",
                      "nullable": true
                    },
                    "valid": {
                      "type": "boolean"
                    }
                  }
                },
                "birthDate": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string",
                      "nullable": true,
                      "description": "Date ISO."
                    },
                    "valid": {
                      "type": "boolean"
                    }
                  }
                },
                "lastName": {
                  "type": "string",
                  "nullable": true
                },
                "firstName": {
                  "type": "string",
                  "nullable": true
                },
                "gender": {
                  "type": "string",
                  "enum": [
                    "M",
                    "F"
                  ],
                  "nullable": true,
                  "description": "Déduit de la colonne de civilité/genre brute. null si non reconnu."
                },
                "civilityMatched": {
                  "type": "boolean",
                  "description": "Indique si la chaîne de civilité/genre brute a été reconnue."
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Balises de catégorie normalisées et déduites de la ligne."
                },
                "issues": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "reason": {
                        "type": "string"
                      },
                      "severity": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ContactLookupInput": {
        "type": "object",
        "description": "Dédoublonnage par lot — pour chaque élément, rechercher le contact correspondant de l’organisation SANS rien écrire. À utiliser après la normalisation et avant l’import pour repérer les lignes déjà présentes (matchedContactId).",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string",
                  "description": "Téléphone à faire correspondre (normalisé en E.164 avant la recherche)."
                },
                "email": {
                  "type": "string",
                  "description": "Email à faire correspondre (converti en minuscules avant la recherche)."
                }
              }
            }
          },
          "defaultPhoneCountry": {
            "type": "string",
            "description": "Pays ISO utilisé pour normaliser les téléphones locaux. Par défaut : \"ZZ\"."
          }
        }
      },
      "LookupResult": {
        "type": "object",
        "description": "Résultat de la recherche groupée. Chaque élément indique le contact correspondant éventuel, sans aucune écriture.",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": {
                  "type": "integer"
                },
                "matchedContactId": {
                  "type": "string",
                  "nullable": true
                },
                "matchedOn": {
                  "type": "string",
                  "nullable": true,
                  "description": "\"phone\" ou \"email\"."
                },
                "matchedName": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "matched": {
                "type": "integer"
              },
              "unmatched": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ContactImportInput": {
        "type": "object",
        "description": "Upsert en masse de 500 contacts maximum (500+ → 400 IMPORT_TOO_LARGE ; répartir sur plusieurs pages). Définissez `dryRun:true` pour obtenir le PLAN détaillé par ligne (action + problèmes), SANS rien enregistrer. Chaque ligne est normalisée et validée comme avec create_contact ; toute ligne comportant une erreur bloquante est ignorée (action:\"error\"). Appelez d’abord get_contact_import_schema pour connaître les clés de champs importables et leurs alias.",
        "required": [
          "contacts"
        ],
        "properties": {
          "contacts": {
            "type": "array",
            "description": "Lignes à importer (≤ 500). Chaque ligne accepte les mêmes champs d’identité publics que ContactCreateInput (firstName/lastName/gender/email/phone/birthDate/tags/customFields/address…), ainsi qu’un `__row` facultatif (numéro de ligne source du tableur, renvoyé dans le rapport).",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/ContactCreateInput"
                },
                {
                  "type": "object",
                  "properties": {
                    "__row": {
                      "description": "Numéro d’origine de la ligne du tableur, renvoyé dans `report.lines[].row`."
                    }
                  }
                }
              ]
            }
          },
          "options": {
            "type": "object",
            "description": "Options d’importation.",
            "properties": {
              "dedupStrategy": {
                "type": "string",
                "enum": [
                  "skip",
                  "update",
                  "create"
                ],
                "description": "En cas de correspondance : ignorer (ne rien modifier), mettre à jour (ne remplir que les champs vides, par défaut) ou créer (toujours insérer un nouveau document).",
                "default": "update"
              },
              "applyTags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Balises de catégorie ajoutées à CHAQUE contact importé (normalisées EN MAJUSCULES)."
              },
              "defaultPhoneCountry": {
                "type": "string",
                "description": "Pays ISO utilisé pour normaliser les téléphones locaux. Par défaut : \"ZZ\"."
              },
              "dateFormat": {
                "type": "string",
                "description": "Indication pour les dates ambiguës (par ex. \"M/D/YYYY\")."
              }
            }
          },
          "dryRun": {
            "type": "boolean",
            "description": "true = validation et planification uniquement, AUCUNE écriture. Les compteurs sont des PROJECTIONS ; `report.lines` indique l’action prévue pour chaque ligne.",
            "default": false
          }
        }
      },
      "ImportResult": {
        "type": "object",
        "description": "Résultat de l’importation. Même structure pour une simulation et un import réel : en mode simulation, les compteurs sont des PROJECTIONS et rien n’est enregistré ; `report.lines` est toujours présent (plan détaillé par ligne).",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "report": {
            "type": "object",
            "properties": {
              "created": {
                "type": "integer",
                "description": "Contacts créés (projection en mode simulation)."
              },
              "updated": {
                "type": "integer",
                "description": "Contacts mis à jour (projection en mode simulation)."
              },
              "skipped": {
                "type": "integer",
                "description": "Lignes ignorées (correspondance trouvée + dedupStrategy skip)."
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "row": {
                      "description": "__row ou index."
                    },
                    "reason": {
                      "description": "Problèmes bloquants de cette ligne."
                    }
                  }
                }
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "row": {},
                    "reason": {
                      "type": "string"
                    }
                  }
                }
              },
              "lines": {
                "type": "array",
                "description": "Une entrée par ligne d’entrée (simulation ET import réel).",
                "items": {
                  "type": "object",
                  "properties": {
                    "row": {
                      "description": "__row (si fourni) ou index à partir de 0."
                    },
                    "action": {
                      "type": "string",
                      "enum": [
                        "create",
                        "update",
                        "skip",
                        "error"
                      ],
                      "description": "Action prévue/effectuée. \"error\" = problème bloquant → aucune écriture."
                    },
                    "matchedContactId": {
                      "type": "string",
                      "nullable": true,
                      "description": "Contact existant détecté lors du dédoublonnage (null = nouveau)."
                    },
                    "issues": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "description": "Champ PUBLIC concerné par le problème (par ex. \"phone\", \"email\", \"birthDate\")."
                          },
                          "reason": {
                            "type": "string",
                            "description": "MISSING_IDENTITY | INVALID_PHONE | INVALID_EMAIL | INVALID_DATE | INVALID_BOOL | DUPLICATE_IN_BATCH | UNKNOWN_RELATIONSHIP."
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "error",
                              "warning"
                            ],
                            "description": "error bloque l’écriture ; warning ne la bloque pas."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ContactUpdateInput": {
        "type": "object",
        "description": "Champs d’identité à REMPLACER sur un contact existant (modification explicite — remplace la valeur enregistrée, contrairement à la création/upsert qui ne remplit que les champs vides). Les sous-collections (téléphones / emails / adresses secondaires, balises, champs personnalisés) ne sont PAS modifiées ici — utilisez les opérations dédiés aux sous-ressources. Une chaîne vide (\"\") signifie « ne pas modifier ». L’identité n’est jamais effacée. Mêmes formats que ContactCreateInput.",
        "required": [],
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Remplace le prénom (majuscule initiale). \"\" = ne pas modifier."
          },
          "lastName": {
            "type": "string",
            "description": "Remplace le nom de famille (majuscules). \"\" = ne pas modifier."
          },
          "gender": {
            "type": "string",
            "enum": [
              "M",
              "F"
            ],
            "nullable": true,
            "description": "« M » (masculin), « F » (féminin) ou null (inconnu)."
          },
          "email": {
            "type": "string",
            "description": "Remplace l’email principal (doit être valide → 400 INVALID_EMAIL)."
          },
          "phone": {
            "type": "string",
            "description": "Remplace le téléphone principal (E.164 ; 400 INVALID_PHONE si impossible à analyser)."
          },
          "phoneCountry": {
            "type": "string",
            "description": "Pays ISO utilisé pour normaliser un `phone` local."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Remplace la date de naissance (ISO). 400 INVALID_DATE si impossible à analyser."
          },
          "hebrewFirstName": {
            "type": "string",
            "description": "Remplace le prénom hébraïque."
          },
          "taxId": {
            "type": "string",
            "description": "Remplace l’identifiant national / fiscal (Teudat Zehut)."
          },
          "giftAid": {
            "type": "boolean",
            "description": "Remplace l’indicateur Gift Aid britannique."
          },
          "address": {
            "type": "string",
            "description": "Remplace l’adresse PRINCIPALE (rue)."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "ContactAddressInput": {
        "type": "object",
        "description": "Adresse à ajouter. Si le contact n’a pas d’adresse principale (ou si `main:true`), elle devient l’adresse principale ; sinon, elle est ajoutée comme adresse secondaire après dédoublonnage.",
        "required": [
          "address"
        ],
        "properties": {
          "main": {
            "type": "boolean",
            "description": "Définir cette adresse comme adresse PRINCIPALE (remplace celle à plat)."
          },
          "label": {
            "type": "string",
            "description": "Libellé libre (par ex. « Bureau »)."
          },
          "type": {
            "type": "string",
            "description": "PRO | PERSO."
          },
          "address": {
            "type": "string",
            "description": "Adresse (rue), obligatoire."
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string",
            "description": "État / région / province."
          },
          "country": {
            "type": "string",
            "description": "Pays (par défaut : « France »)."
          },
          "companyId": {
            "type": "string",
            "description": "Numéro d’immatriculation de l’entreprise (pour une adresse PRO)."
          },
          "note": {
            "type": "string"
          }
        }
      },
      "ContactAddressPatchInput": {
        "type": "object",
        "description": "Champs autorisés à fusionner dans une adresse SECONDAIRE (ciblée par son UUID `addressId`). Seuls les champs fournis sont modifiés. L’adresse PRINCIPALE n’a pas d’identifiant et ne peut pas être modifiée ici (utilisez PATCH /contacts/{id} ou POST /contacts/{id}/addresses avec main:true).",
        "properties": {
          "label": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "PRO | PERSO."
          },
          "address": {
            "type": "string"
          },
          "postalCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "companyId": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "ContactPhoneInput": {
        "type": "object",
        "description": "Téléphone SECONDAIRE à ajouter (après dédoublonnage). Le téléphone principal se définit via POST/PATCH /contacts.",
        "required": [
          "phone"
        ],
        "properties": {
          "phone": {
            "type": "string",
            "description": "Téléphone (n’importe quel format ; normalisé en E.164 ; 400 INVALID_PHONE si impossible à analyser)."
          },
          "phoneCountry": {
            "type": "string",
            "description": "Code pays ISO utilisé pour normaliser un numéro local."
          }
        }
      },
      "ContactEmailInput": {
        "type": "object",
        "description": "Email SECONDAIRE à ajouter (après dédoublonnage). L’email principal se définit via POST/PATCH /contacts.",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "Email (en minuscules ; 400 INVALID_EMAIL s’il est invalide)."
          }
        }
      },
      "ContactTagsInput": {
        "type": "object",
        "description": "Une ou plusieurs catégories à associer (idempotent — ajouter à nouveau une balise ne fait rien). Chacune est normalisée (majuscules, sans accents, espaces remplacés par `_`). Les catégories système (#FORM/#PAIEMENT/#ABONNEMENT/#ACCOUNT/codes de devise) sont également autorisées. Une balise est une étiquette booléenne — PAS un champ personnalisé clé/valeur (voir ContactCustomFieldsInput).",
        "required": [
          "tags"
        ],
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Balises, par ex. [\"Donateur\", \"Séder night\"] → enregistrées DONATEUR, SEDER_NIGHT."
          }
        }
      },
      "ContactCustomFieldsInput": {
        "type": "object",
        "description": "Champs personnalisés typés clé/valeur à mettre à jour par clé. `override` (true par défaut ici — modification explicite) remplace la valeur enregistrée ; définissez-le à false pour ne remplir que les champs vides. `type` est réduit à TEXT/DATE/BOOL (NUMBER/DATETIME sont enregistrés comme TEXT). À distinguer des catégories.",
        "required": [
          "customFields"
        ],
        "properties": {
          "customFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactFieldEntry"
            },
            "description": "Champs à définir (upsert par clé, sans doublons)."
          },
          "override": {
            "type": "boolean",
            "description": "true (par défaut) remplace une valeur existante ; false ne remplit que les champs vides.",
            "default": true
          }
        }
      },
      "ContactFamilyLinkInput": {
        "type": "object",
        "description": "Lien familial bidirectionnel entre le contact et `relatedContactId`. Le lien inverse est ajouté automatiquement (PARENT↔CHILD et GRANDPARENT↔GRANDCHILD sont asymétriques ; les autres types sont symétriques). `relatedContactId` DOIT appartenir à la même organisation (sinon 404).",
        "required": [
          "relationship",
          "relatedContactId"
        ],
        "properties": {
          "relationship": {
            "type": "string",
            "enum": [
              "SPOUSE",
              "PARENT",
              "CHILD",
              "SIBLING",
              "GRANDPARENT",
              "GRANDCHILD",
              "IN_LAW",
              "EX",
              "COUSIN",
              "FRIEND"
            ],
            "description": "Lien DE ce contact VERS `relatedContactId` : SPOUSE, PARENT (ce contact est le parent → lien inverse CHILD), CHILD, SIBLING, GRANDPARENT (→ lien inverse GRANDCHILD), GRANDCHILD, IN_LAW, EX, COUSIN, FRIEND."
          },
          "relatedContactId": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant de l’autre contact (doit appartenir à l’organisation)."
          }
        }
      },
      "ContactChildInput": {
        "type": "object",
        "description": "Enfant en bas âge à rattacher au contact (et à son éventuel conjoint SPOUSE détecté) comme parent. Dédoublonnage par prénom parmi les enfants des parents : un enfant existant est réutilisé (created:false), sinon un nouveau contact enfant est créé sans téléphone ni email. Un lien PARENT↔CHILD est créé automatiquement.",
        "required": [
          "firstName"
        ],
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Prénom de l’enfant (utilisé pour le dédoublonnage)."
          },
          "lastName": {
            "type": "string",
            "description": "Nom de famille de l’enfant (en majuscules)."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Date de naissance (ISO)."
          }
        }
      },
      "ContactInteraction": {
        "type": "object",
        "description": "Interaction consignée avec le contact (appel, visite, note). Projection en lecture d’un document `contact_activity`.",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          },
          "type": {
            "type": "string",
            "description": "Type d’interaction, par ex. « Appel », « Visite »."
          },
          "content": {
            "type": "string",
            "description": "Notes en texte libre."
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Balises textuelles facultatives décrivant ce qui a été fait."
          },
          "author": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "Nom du membre du personnel auteur lorsque l’entrée vient de l’admin/copilote ; null pour les entrées créées via l’API."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "ContactInteractionInput": {
        "type": "object",
        "description": "Nouvelle interaction à consigner pour le contact. Utilisez-la pour enregistrer un appel/une visite/une note depuis une automatisation. Pour rester cohérent, réutilisez un `type` de GET /contacts/{id}/interactions/types au lieu d’inventer un nouveau libellé à chaque fois.",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Type d’interaction (libellé libre), par ex. « Appel », « Visite », « Rencontre »."
          },
          "content": {
            "type": "string",
            "description": "Notes libres sur l’interaction."
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Balises textuelles facultatives, par ex. [« Tefiline », « Discussion »]."
          }
        }
      },
      "ContactDocument": {
        "type": "object",
        "description": "Fichier joint au contact (reçu, scan d’une pièce d’identité, mandat signé…). Projection en lecture d’un sous-document `contact.docs[]`.",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true,
            "description": "Identifiant du document (UUID) — transmettez-le à DELETE /contacts/{id}/documents/{docId}."
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Libellé lisible (par défaut, le nom de fichier si aucun n’a été fourni)."
          },
          "filename": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "Nom du fichier hébergé (md5.ext). Réutilisable pour joindre le MÊME fichier ailleurs sans le téléverser à nouveau."
          },
          "url": {
            "type": "string",
            "nullable": true,
            "readOnly": true,
            "description": "URL absolue de téléchargement du fichier."
          },
          "uploadedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "readOnly": true
          }
        }
      },
      "ContactDocumentInput": {
        "type": "object",
        "description": "Joindre un document au contact. Fournissez EXACTEMENT UN de ces éléments : `filename` (fichier déjà hébergé via POST /uploads/pdf|image) ou `url` (lien http(s), réhébergé côté serveur — image/PDF uniquement, parcours MCP/IA). Images et PDF uniquement (un document de contact est un scan, pas une vidéo). Parcours habituel : « téléverser d’abord, joindre ensuite » : POST /uploads/pdf → récupérer son `filename` → effectuer POST ici.",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Nom du fichier hébergé renvoyé par POST /uploads/pdf ou POST /uploads/image (md5.ext). Il doit appartenir à cette organisation."
          },
          "url": {
            "type": "string",
            "description": "URL http(s) publique d’une image ou d’un PDF à télécharger et héberger. Utilisez-la depuis un agent MCP/IA qui ne peut pas transmettre un flux binaire."
          },
          "name": {
            "type": "string",
            "description": "Libellé facultatif du document (par défaut, le nom de fichier)."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
