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

# Contacts

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "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/UnisoftRequest_e4688e4bc822e21f91a3"
      },
      "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é)."
}
```

```json
{
  "name": "phoneCountry",
  "in": "query",
  "schema": {
    "type": "string",
    "pattern": "^[A-Za-z]{2}$"
  },
  "description": "Pays ISO utilisé pour normaliser un numéro de téléphone local."
}
```

### 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/UnisoftRequest_f3635fecc6f75b85ba0f"
      },
      "example": {
        "rows": [
          {
            "phone": "06 12 34 56 78",
            "birthDate": "15/03/1990",
            "gender": "F",
            "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": {
        "type": "object",
        "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)."
                }
              },
              "additionalProperties": false
            }
          },
          "defaultPhoneCountry": {
            "type": "string",
            "description": "Pays ISO utilisé pour normaliser les téléphones locaux. Par défaut : \"ZZ\"."
          }
        },
        "required": [
          "items"
        ],
        "additionalProperties": false,
        "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)."
      },
      "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/UnisoftRequest_7ef2b58154210ab6fbbe"
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### 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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_731434cf8427fd36cfcb"
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "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"
          }
        },
        "required": [
          "address"
        ],
        "additionalProperties": false,
        "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."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

```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": {
        "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"
          },
          "note": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "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)."
      }
    }
  }
}
```

### 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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "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."
          }
        },
        "required": [
          "phone"
        ],
        "additionalProperties": false,
        "description": "Téléphone SECONDAIRE à ajouter (après dédoublonnage). Le téléphone principal se définit via POST/PATCH /contacts."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email (en minuscules ; 400 INVALID_EMAIL s’il est invalide)."
          }
        },
        "required": [
          "email"
        ],
        "additionalProperties": false,
        "description": "Email SECONDAIRE à ajouter (après dédoublonnage). L’email principal se définit via POST/PATCH /contacts."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Balises, par ex. [\"Donateur\", \"Séder night\"] → enregistrées DONATEUR, SEDER_NIGHT."
          }
        },
        "required": [
          "tags"
        ],
        "additionalProperties": false,
        "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)."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

```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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_b743641a58b8fd5cb226"
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

```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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "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)."
          }
        },
        "required": [
          "relationship",
          "relatedContactId"
        ],
        "additionalProperties": false,
        "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)."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

```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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "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)."
          }
        },
        "required": [
          "firstName"
        ],
        "additionalProperties": false,
        "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."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

```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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "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 »]."
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "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."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### 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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### 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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "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)."
          }
        },
        "additionalProperties": false,
        "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."
      },
      "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",
    "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}$",
    "format": "uuid"
  },
  "description": "Identifiant de la ressource cible existante, renvoyé par son opération de liste ou de lecture autorisée. Ne générez jamais un nouvel UUID pour cibler un enregistrement existant."
}
```

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

## GET /contacts/chlihout-settings

Consulter les types et niveaux de Shlihout

`get_chlihout_settings`

Autorisation requise : `contacts:read`. Renvoie les réglages et la révision de l’organisation connectée. Les clés limitées à une campagne sont refusées. Seul le vocabulaire de l’organisation est exposé ; ces opérations n’exposent aucune valeur de pratique religieuse d’un contact, note, recherche, statistique ni webhook. L’ordre des tableaux est celui de l’affichage. Les libellés sont des textes saisis par l’organisation, pas des traductions ; un libellé vide rétablit la traduction intégrée pour CHABBAT/CACHEROUT/TAHARAT/ECOLE ou les niveaux 0/1/3/5/7/10. Les autres libellés doivent contenir du texte. Les niveaux sont communs à tous les types ; zéro signifie toujours inconnu. 

### Authentification

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

### Permissions requises

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

### Réponses

#### HTTP 200

```json
{
  "description": "Réglages de l’organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ChlihoutSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Réglages invalides.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits insuffisants.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CHLIHOUT_SETTINGS_CONFLICT : rechargez les réglages avant de les modifier de nouveau.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Erreur interne.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## PUT /contacts/chlihout-settings

Personnaliser les types et niveaux de Shlihout

`update_chlihout_settings`

Autorisations requises : `contacts:read` et `contacts:write`. Réservé aux clés d’organisation et aux acteurs OAuth ADMIN actifs ; les clés limitées à une campagne et les acteurs secondaires sont refusés. Lisez d’abord get_chlihout_settings, puis transmettez les tableaux types/levels complets et cette révision. Les identifiants et valeurs numériques sont des clés stables : ne modifiez ni ne retirez jamais une clé existante. enabled:false masque un choix de façon réversible, en conservant son libellé et les données enregistrées sur les contacts. Au moins un niveau positif et le niveau zéro activé sont requis. Ajoutez un type avec un identifiant unique en majuscules ; ajoutez un niveau avec un entier inutilisé de 1 à 100. Limites : 100 types et 30 niveaux. Un enregistrement réussi incrémente la révision ; une nouvelle tentative avec l’ancienne révision renvoie 409. Relisez donc les réglages pour vérifier une réponse perdue. Seul le vocabulaire de l’organisation est exposé ; ces opérations n’exposent aucune valeur de pratique religieuse d’un contact, note, recherche, statistique ni webhook. L’ordre des tableaux est celui de l’affichage. Les libellés sont des textes saisis par l’organisation, pas des traductions ; un libellé vide rétablit la traduction intégrée pour CHABBAT/CACHEROUT/TAHARAT/ECOLE ou les niveaux 0/1/3/5/7/10. Les autres libellés doivent contenir du texte. Les niveaux sont communs à tous les types ; zéro signifie toujours inconnu. 

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740990
          },
          "types": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80,
                  "pattern": "^[A-Z][A-Z0-9_-]*$"
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "label",
                "enabled"
              ],
              "additionalProperties": false
            }
          },
          "levels": {
            "type": "array",
            "minItems": 2,
            "maxItems": 30,
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "value",
                "label",
                "enabled"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "revision",
          "types",
          "levels"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Réglages de l’organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ChlihoutSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Réglages invalides.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits insuffisants.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CHLIHOUT_SETTINGS_CONFLICT : rechargez les réglages avant de les modifier de nouveau.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Erreur interne.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contacts/merges/preview

Prévisualiser une fusion de contacts délibérée et ses liens financiers admis

`preview_contact_merge`

Nécessite explicitement contacts:merge ET contacts:read ET contacts:write ET paiements:read ET paiements:write ET promesses:read ET promesses:write. contacts:merge est un droit opt-in, jamais attribué par défaut. Les clés limitées à une collecte sont refusées. Lecture seule : choisir explicitement survivorId et absorbedId après examen du doublon proposé ; un diagnostic ne prouve pas que deux fiches désignent la même personne. Renvoie le profil public fusionné natif, les nombres exacts d’effets et une revision liée aux deux profils BSON, aux fiches liées actuelles, à la clé et aux scopes. La fiche absorbée disparaîtra si la commande ultérieure aboutit. Aucun aperçu n’est persisté, aucun contact ne change et aucun effet en attente n’est exécuté. L’aperçu est une observation, pas une réservation ni un snapshot global. Une seule paire délibérée d’UUID de contacts distincts, actifs et actuels de la même organisation est prise en charge. Aucun choix automatique de doublon ni choix de champs. Les valeurs scalaires présentes du survivant sont prioritaires (false/0 sont conservés), les objets de la source sont superposés, les tableaux/coordonnées/catégories suivent le propriétaire natif ; celui-ci fixe new:false et archived:false puis supprime physiquement absorbedId. Les identités de compte, graphes familiaux, références contact/payload d’abonnement et références non réaffectées par le propriétaire natif sont refusés avant effet, notamment activités, communications, documents fiscaux, liens Google et biométrie. Les montants de paiement/promesse liés et les snapshots historiques de facturation/fiscalité restent inchangés. Toute cible financière doit encore être disponible et appartenir à l’organisation ; les formulaires exigent forms_submit:read/write, les cibles caisse caisses:read/write, les collectes fundraising:read/write et les abonnements référencés abonnements:read. Aucun snapshot privé brut, code d’accès d’adresse ou moyen réutilisable n’est exposé. Maximum 2000 fiches liées et 4 MiB par lecture ; requêtes limitées à 10000 ms. Les propriétés de requête/corps inconnues sont refusées. Seuls les changements visibles dans le profil retourné de noms, genre enregistré, email/téléphone primaire et secondaire, adresse principale et catégories sont admis ; une modification native d’un autre champ refuse CONTACT_MERGE_PROFILE_CHOICE_UNSUPPORTED. Aucun changement privé ou non relu du profil n’est appliqué silencieusement. lockCleanup qualifie séparément le nettoyage des verrous externes : NOT_ATTEMPTED, RELEASED, RETAINED ou UNKNOWN. Une fusion physique prouvée et un journal terminal acquitté restent APPLIED_PENDING_EFFECTS si le nettoyage est inconnu ; cela n’autorise jamais un nouvel essai ni une reprise de verrou. Un journal terminal métier non prouvé reste state UNKNOWN. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:merge",
  "additional": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "survivorId": {
            "type": "string",
            "format": "uuid"
          },
          "absorbedId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "survivorId",
          "absorbedId"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Aperçu du profil natif et révision courante.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergePreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Paire invalide, entrée inconnue ou commande invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Tous les scopes de fusion et des domaines liés sont requis ; les restrictions de collecte sont refusées.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Un contact ou une commande est indisponible pour l’organisation/clé courante.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité courante, référence non prise en charge, révision, verrou ou conflit d’idempotence : examiner avant toute nouvelle intention.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source ambiguë, mal formée ou hors limite ; aucune fusion partielle n’est admise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "L’admission ou le stockage du reçu n’est pas prouvé ; ne jamais déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:merge",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "forms are related",
      "scopes": [
        "forms_submit:read",
        "forms_submit:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment targets a caisse",
      "scopes": [
        "caisses:read",
        "caisses:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment or pledge targets a campaign",
      "scopes": [
        "fundraising:read",
        "fundraising:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment has abo",
      "scopes": [
        "abonnements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/merges

Appliquer une fusion native relue une seule fois avec suivi durable du résultat

`merge_contacts`

Nécessite explicitement contacts:merge ET contacts:read ET contacts:write ET paiements:read ET paiements:write ET promesses:read ET promesses:write. contacts:merge est un droit opt-in, jamais attribué par défaut. Les clés limitées à une collecte sont refusées. Appeler d’abord preview_contact_merge et conserver exactement survivorId, absorbedId et revision. idempotencyKey identifie cette seule intention. La commande journalise l’admission, acquiert des verrous externes ordonnés par contact partagés avec les commandes externes lifecycle/bulk, revérifie toutes les sources et appelle CRM.mergeContact natif avec les contacts BSON attendus complets et son journal snapshot/CAS. Les writers internes restent actifs : atomicAcrossInternalWriters:false. La même clé et le même contenu renvoient le reçu sans rappeler le propriétaire ; un contenu modifié donne IDEMPOTENCY_CONFLICT. APPLIED_PENDING_EFFECTS confirme la fusion physique et la relecture des payloads financiers inchangés ; les effets dérivés natifs sont mis en file et ne sont pas exécutés pendant l’appel (dont le géocodage). Cela ne confirme pas que toutes les projections dérivées sont à jour. REJECTED précède l’appel au propriétaire. ADMITTING/RUNNING peuvent être en cours ou interrompus. UNKNOWN signifie qu’un effet appelé ou sa relecture n’est pas prouvé et conserve les deux verrous externes. success:true confirme un reçu stocké, pas une fusion réussie. canRetry:false dans tous les états. Après timeout ou incertitude, appeler get_contact_merge_command avec commandId ; ne jamais réessayer avec une autre clé, contourner les verrous, reprendre le travail natif ou déduire un échec de l’ancienneté. Aucune annulation/récupération automatique ni reprise de verrou ancien n’est exposée. Une seule paire délibérée d’UUID de contacts distincts, actifs et actuels de la même organisation est prise en charge. Aucun choix automatique de doublon ni choix de champs. Les valeurs scalaires présentes du survivant sont prioritaires (false/0 sont conservés), les objets de la source sont superposés, les tableaux/coordonnées/catégories suivent le propriétaire natif ; celui-ci fixe new:false et archived:false puis supprime physiquement absorbedId. Les identités de compte, graphes familiaux, références contact/payload d’abonnement et références non réaffectées par le propriétaire natif sont refusés avant effet, notamment activités, communications, documents fiscaux, liens Google et biométrie. Les montants de paiement/promesse liés et les snapshots historiques de facturation/fiscalité restent inchangés. Toute cible financière doit encore être disponible et appartenir à l’organisation ; les formulaires exigent forms_submit:read/write, les cibles caisse caisses:read/write, les collectes fundraising:read/write et les abonnements référencés abonnements:read. Aucun snapshot privé brut, code d’accès d’adresse ou moyen réutilisable n’est exposé. Maximum 2000 fiches liées et 4 MiB par lecture ; requêtes limitées à 10000 ms. Les propriétés de requête/corps inconnues sont refusées. Seuls les changements visibles dans le profil retourné de noms, genre enregistré, email/téléphone primaire et secondaire, adresse principale et catégories sont admis ; une modification native d’un autre champ refuse CONTACT_MERGE_PROFILE_CHOICE_UNSUPPORTED. Aucun changement privé ou non relu du profil n’est appliqué silencieusement. lockCleanup qualifie séparément le nettoyage des verrous externes : NOT_ATTEMPTED, RELEASED, RETAINED ou UNKNOWN. Une fusion physique prouvée et un journal terminal acquitté restent APPLIED_PENDING_EFFECTS si le nettoyage est inconnu ; cela n’autorise jamais un nouvel essai ni une reprise de verrou. Un journal terminal métier non prouvé reste state UNKNOWN. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:merge",
  "additional": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "survivorId": {
            "type": "string",
            "format": "uuid"
          },
          "absorbedId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "survivorId",
          "absorbedId",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Reçu stocké appliqué avec effets en attente ou refusé ; examiner state.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Reçu stocké en cours ou incertain ; ne jamais rejouer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Paire invalide, entrée inconnue ou commande invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Tous les scopes de fusion et des domaines liés sont requis ; les restrictions de collecte sont refusées.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Un contact ou une commande est indisponible pour l’organisation/clé courante.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité courante, référence non prise en charge, révision, verrou ou conflit d’idempotence : examiner avant toute nouvelle intention.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source ambiguë, mal formée ou hors limite ; aucune fusion partielle n’est admise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "L’admission ou le stockage du reçu n’est pas prouvé ; ne jamais déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:merge",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "forms are related",
      "scopes": [
        "forms_submit:read",
        "forms_submit:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment targets a caisse",
      "scopes": [
        "caisses:read",
        "caisses:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment or pledge targets a campaign",
      "scopes": [
        "fundraising:read",
        "fundraising:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment has abo",
      "scopes": [
        "abonnements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/merge-commands/{commandId}

Lire le résultat d’une commande de fusion sans la rejouer

`get_contact_merge_command`

Nécessite explicitement contacts:merge ET contacts:read ET contacts:write ET paiements:read ET paiements:write ET promesses:read ET promesses:write. contacts:merge est un droit opt-in, jamais attribué par défaut. Les clés limitées à une collecte sont refusées. Utiliser le commandId retourné, pas un UUID de contact. Lit uniquement le reçu externe durable de cette clé et de cette organisation. APPLIED_PENDING_EFFECTS décrit l’état vérifié à l’exécution ; des changements internes ultérieurs restent possibles. UNKNOWN/RUNNING/ADMITTING n’autorisent jamais un nouvel essai ni une reprise de verrou. L’historique natif reste privé pour une revue Unisoft autorisée. Aucune commande n’est reprise, aucun effet exécuté, contact chargé, verrou libéré ou annulation déclenchée. Aucun paramètre de requête ni corps n’est accepté. canRetry:false. Une seule paire délibérée d’UUID de contacts distincts, actifs et actuels de la même organisation est prise en charge. Aucun choix automatique de doublon ni choix de champs. Les valeurs scalaires présentes du survivant sont prioritaires (false/0 sont conservés), les objets de la source sont superposés, les tableaux/coordonnées/catégories suivent le propriétaire natif ; celui-ci fixe new:false et archived:false puis supprime physiquement absorbedId. Les identités de compte, graphes familiaux, références contact/payload d’abonnement et références non réaffectées par le propriétaire natif sont refusés avant effet, notamment activités, communications, documents fiscaux, liens Google et biométrie. Les montants de paiement/promesse liés et les snapshots historiques de facturation/fiscalité restent inchangés. Toute cible financière doit encore être disponible et appartenir à l’organisation ; les formulaires exigent forms_submit:read/write, les cibles caisse caisses:read/write, les collectes fundraising:read/write et les abonnements référencés abonnements:read. Aucun snapshot privé brut, code d’accès d’adresse ou moyen réutilisable n’est exposé. Maximum 2000 fiches liées et 4 MiB par lecture ; requêtes limitées à 10000 ms. Les propriétés de requête/corps inconnues sont refusées. Seuls les changements visibles dans le profil retourné de noms, genre enregistré, email/téléphone primaire et secondaire, adresse principale et catégories sont admis ; une modification native d’un autre champ refuse CONTACT_MERGE_PROFILE_CHOICE_UNSUPPORTED. Aucun changement privé ou non relu du profil n’est appliqué silencieusement. lockCleanup qualifie séparément le nettoyage des verrous externes : NOT_ATTEMPTED, RELEASED, RETAINED ou UNKNOWN. Une fusion physique prouvée et un journal terminal acquitté restent APPLIED_PENDING_EFFECTS si le nettoyage est inconnu ; cela n’autorise jamais un nouvel essai ni une reprise de verrou. Un journal terminal métier non prouvé reste state UNKNOWN. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:merge",
  "additional": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ]
}
```

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier reçu durable ; aucune continuation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Reçu incertain ou en cours ; aucune continuation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Paire invalide, entrée inconnue ou commande invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification requise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Tous les scopes de fusion et des domaines liés sont requis ; les restrictions de collecte sont refusées.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Un contact ou une commande est indisponible pour l’organisation/clé courante.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité courante, référence non prise en charge, révision, verrou ou conflit d’idempotence : examiner avant toute nouvelle intention.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Source ambiguë, mal formée ou hors limite ; aucune fusion partielle n’est admise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "L’admission ou le stockage du reçu n’est pas prouvé ; ne jamais déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMergeError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:merge",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write",
    "paiements:read",
    "paiements:write",
    "promesses:read",
    "promesses:write"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "forms are related",
      "scopes": [
        "forms_submit:read",
        "forms_submit:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment targets a caisse",
      "scopes": [
        "caisses:read",
        "caisses:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment or pledge targets a campaign",
      "scopes": [
        "fundraising:read",
        "fundraising:write"
      ],
      "allRequired": true
    },
    {
      "condition": "payment has abo",
      "scopes": [
        "abonnements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/notes

Lire la note générale CRM et sa révision exacte

`get_contact_notes`

Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. Requiert contacts:read. Retourne seulement la note générale, son marqueur de présence et sa révision. Un historique absent/null reste null, sans note vide fabriquée. Les notes d’adresse sont gérées séparément.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID exact du contact dans cette organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Note générale CRM enregistrée sans champs de contact non concernés.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactNotesReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

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

## PATCH /contacts/{id}/notes

Corriger la note générale CRM avec une commande journalisée

`edit_contact_notes`

Requiert l’attribution explicite contacts:manage-interactions ET contacts:read ET contacts:write. Lire d’abord la cible exacte, puis fournir son expectedRevision et une idempotencyKey stable (8–128 lettres/chiffres ASCII/._:-). Le journal et un verrou externe par contact précèdent l’effet métier. Un compare-and-set BSON exact modifie seulement les champs ciblés ; les champs omis et métadonnées privées non concernées restent intacts. Les écrivains internes et autres contacts restent actifs : ce n’est pas un verrou transactionnel global ni une garantie d’état futur. La même clé et intention retourne le reçu existant sans répéter l’écriture ; une intention différente retourne IDEMPOTENCY_CONFLICT. success:true confirme un reçu de commande, y compris pour une commande refusée ou incertaine. APPLIED signifie qu’une mise à jour enregistrée de la cible a été acquittée ; NO_CHANGE signifie qu’aucune mutation n’était nécessaire ; REJECTED n’a exécuté aucun effet métier ; CONFLICT a perdu le CAS ; ADMITTING/RUNNING peuvent être actifs ou interrompus. UNKNOWN signifie que l’effet ou le reçu final n’est pas prouvé et conserve le verrou externe. canRetry:false est constant. Lire get_contact_interaction_command ; ne jamais utiliser une nouvelle clé, un ancien endpoint non gardé ou d’autres credentials pour contourner l’incertitude. Aucun réessai automatique, rollback, reprise de verrou expiré ou endpoint de récupération n’existe. Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. content est un texte brut d’au plus 20000 caractères. Une chaîne explicitement vide efface seulement cette note générale. Aucune note d’adresse, interaction ou donnée financière n’est modifiée.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID exact du contact dans cette organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "content": {
            "type": "string",
            "maxLength": 20000
          }
        },
        "required": [
          "expectedRevision",
          "idempotencyKey",
          "content"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Statut conservateur de commande ; lire state avant de considérer success:true comme une correction appliquée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est en admission, en cours ou interrompue ; aucune seconde exécution métier n’est lancée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE ou CONTACT_MUTATION_FENCE_UNAVAILABLE. Ne pas substituer une nouvelle commande pour contourner un reçu inconnu ou un garde d’admission indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-mcp-output-schema": true
}
```

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

Lire une interaction CRM existante et sa précision temporelle

`get_contact_interaction`

Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. Requiert contacts:read. Résoudre l’interaction via la liste autorisée existante, puis la lire ici pour obtenir sa révision. time.precision=DAY retourne seulement occurredOn ; l’ancre native de tri à midi UTC n’est pas une heure d’événement et n’est jamais présentée comme telle. INSTANT retourne un instant ISO qualifié. UNKNOWN conserve une heure historique indisponible ou incohérente. Les snapshots d’accès du personnel et métadonnées IA/privées sont exclus.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID exact du contact dans cette organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "interactionId",
  "in": "path",
  "required": true,
  "description": "UUID exact d’interaction existante retourné par la liste autorisée ; distinct de l’UUID du contact ou de la commande.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Interaction existante avec précision temporelle explicite : jour, instant ou inconnue.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

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

## PATCH /contacts/{id}/interactions/{interactionId}

Corriger une interaction CRM existante sans créer un autre événement

`edit_contact_interaction`

Requiert l’attribution explicite contacts:manage-interactions ET contacts:read ET contacts:write. Lire d’abord la cible exacte, puis fournir son expectedRevision et une idempotencyKey stable (8–128 lettres/chiffres ASCII/._:-). Le journal et un verrou externe par contact précèdent l’effet métier. Un compare-and-set BSON exact modifie seulement les champs ciblés ; les champs omis et métadonnées privées non concernées restent intacts. Les écrivains internes et autres contacts restent actifs : ce n’est pas un verrou transactionnel global ni une garantie d’état futur. La même clé et intention retourne le reçu existant sans répéter l’écriture ; une intention différente retourne IDEMPOTENCY_CONFLICT. success:true confirme un reçu de commande, y compris pour une commande refusée ou incertaine. APPLIED signifie qu’une mise à jour enregistrée de la cible a été acquittée ; NO_CHANGE signifie qu’aucune mutation n’était nécessaire ; REJECTED n’a exécuté aucun effet métier ; CONFLICT a perdu le CAS ; ADMITTING/RUNNING peuvent être actifs ou interrompus. UNKNOWN signifie que l’effet ou le reçu final n’est pas prouvé et conserve le verrou externe. canRetry:false est constant. Lire get_contact_interaction_command ; ne jamais utiliser une nouvelle clé, un ancien endpoint non gardé ou d’autres credentials pour contourner l’incertitude. Aucun réessai automatique, rollback, reprise de verrou expiré ou endpoint de récupération n’existe. Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. changes accepte seulement les champs fournis type, content, actions, address et soit occurredOn SOIT datetime. Les limites de texte sont type/action 100, content 20000, address 2000 caractères ; actions remplace la liste entière, au plus 50 libellés uniques. occurredOn est un jour civil exact YYYY-MM-DD (années 1–9999) ; datetime est un instant ISO avec fuseau et au plus trois décimales. Ils sont mutuellement exclusifs. Le propriétaire natif contact_activity_update préserve un jour connu pour les corrections de texte seules et modifie explicitement la précision lorsqu’un nouveau jour/instant est fourni. Aucune identité d’auteur/source n’est fabriquée et aucune interaction n’est créée ou supprimée.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID exact du contact dans cette organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "interactionId",
  "in": "path",
  "required": true,
  "description": "UUID exact d’interaction existante retourné par la liste autorisée ; distinct de l’UUID du contact ou de la commande.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Statut conservateur de commande ; lire state avant de considérer success:true comme une correction appliquée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est en admission, en cours ou interrompue ; aucune seconde exécution métier n’est lancée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE ou CONTACT_MUTATION_FENCE_UNAVAILABLE. Ne pas substituer une nouvelle commande pour contourner un reçu inconnu ou un garde d’admission indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/{id}/attachments

Lire les pièces jointes du contact et la révision exacte de leur ensemble

`get_contact_attachments`

Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. Requiert contacts:read. Retourne au plus 100 références de pièces jointes CRM existantes avec la révision de leur ensemble. Chaque filename disponible est admis par le propriétaire média pour cette organisation, le stockage régulier, MIME/signature et une taille image/PDF d’au plus 15 MiB. Un fichier historique indisponible ou étranger donne filename:null et availability:UNAVAILABLE, jamais une URL privée. recordedAt est la date de rattachement/remplacement enregistrée si elle est valide, pas une preuve d’upload de fichier ou d’émission documentaire. Les dates absentes/invalides restent null. Cette lecture ne télécharge aucun média et ne prouve ni analyse antivirus, ni authenticité documentaire, ni autorité financière.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID exact du contact dans cette organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Références de pièces jointes du contact ; les médias indisponibles restent masqués.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactAttachmentsReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

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

## POST /contacts/{id}/attachments/commands

Ajouter, corriger ou détacher une pièce jointe CRM du contact

`edit_contact_attachments`

Requiert l’attribution explicite contacts:manage-interactions ET contacts:read ET contacts:write. Lire d’abord la cible exacte, puis fournir son expectedRevision et une idempotencyKey stable (8–128 lettres/chiffres ASCII/._:-). Le journal et un verrou externe par contact précèdent l’effet métier. Un compare-and-set BSON exact modifie seulement les champs ciblés ; les champs omis et métadonnées privées non concernées restent intacts. Les écrivains internes et autres contacts restent actifs : ce n’est pas un verrou transactionnel global ni une garantie d’état futur. La même clé et intention retourne le reçu existant sans répéter l’écriture ; une intention différente retourne IDEMPOTENCY_CONFLICT. success:true confirme un reçu de commande, y compris pour une commande refusée ou incertaine. APPLIED signifie qu’une mise à jour enregistrée de la cible a été acquittée ; NO_CHANGE signifie qu’aucune mutation n’était nécessaire ; REJECTED n’a exécuté aucun effet métier ; CONFLICT a perdu le CAS ; ADMITTING/RUNNING peuvent être actifs ou interrompus. UNKNOWN signifie que l’effet ou le reçu final n’est pas prouvé et conserve le verrou externe. canRetry:false est constant. Lire get_contact_interaction_command ; ne jamais utiliser une nouvelle clé, un ancien endpoint non gardé ou d’autres credentials pour contourner l’incertitude. Aucun réessai automatique, rollback, reprise de verrou expiré ou endpoint de récupération n’existe. Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. Lire d’abord get_contact_attachments et fournir la révision de l’ensemble. ADD accepte filename et name facultatif, crée un UUID de document déterministe et refuse un filename déjà attaché. EDIT sélectionne un documentId exact et modifie filename et/ou name ; les autres entrées, cet UUID et les métadonnées non concernées restent intacts. Une référence de fichier remplacée actualise la date de rattachement enregistrée ; un changement de nom seul la conserve. DETACH accepte seulement documentId et retire cette référence CRM, jamais les octets hébergés ou un document financier. Au plus 100 pièces jointes sont admises. filename doit déjà être hébergé pour cette organisation et passer la validation canonique image/PDF à 15 MiB ; aucune URL, chemin, copie distante ou liaison de pièce jointe à une interaction n’est accepté. L’upload est une capacité distincte avec son propre scope. Un filename/libellé disant reçu, mandat ou identité n’émet/valide pas ce document et n’active aucun moyen de paiement.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID exact du contact dans cette organisation.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Statut conservateur de commande ; lire state avant de considérer success:true comme une correction appliquée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est en admission, en cours ou interrompue ; aucune seconde exécution métier n’est lancée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE ou CONTACT_MUTATION_FENCE_UNAVAILABLE. Ne pas substituer une nouvelle commande pour contourner un reçu inconnu ou un garde d’admission indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/interaction-commands/{commandId}

Lire une commande de correction CRM enregistrée sans la réessayer

`get_contact_interaction_command`

Requiert l’attribution explicite contacts:manage-interactions ET contacts:read ET contacts:write. Lire d’abord la cible exacte, puis fournir son expectedRevision et une idempotencyKey stable (8–128 lettres/chiffres ASCII/._:-). Le journal et un verrou externe par contact précèdent l’effet métier. Un compare-and-set BSON exact modifie seulement les champs ciblés ; les champs omis et métadonnées privées non concernées restent intacts. Les écrivains internes et autres contacts restent actifs : ce n’est pas un verrou transactionnel global ni une garantie d’état futur. La même clé et intention retourne le reçu existant sans répéter l’écriture ; une intention différente retourne IDEMPOTENCY_CONFLICT. success:true confirme un reçu de commande, y compris pour une commande refusée ou incertaine. APPLIED signifie qu’une mise à jour enregistrée de la cible a été acquittée ; NO_CHANGE signifie qu’aucune mutation n’était nécessaire ; REJECTED n’a exécuté aucun effet métier ; CONFLICT a perdu le CAS ; ADMITTING/RUNNING peuvent être actifs ou interrompus. UNKNOWN signifie que l’effet ou le reçu final n’est pas prouvé et conserve le verrou externe. canRetry:false est constant. Lire get_contact_interaction_command ; ne jamais utiliser une nouvelle clé, un ancien endpoint non gardé ou d’autres credentials pour contourner l’incertitude. Aucun réessai automatique, rollback, reprise de verrou expiré ou endpoint de récupération n’existe. Une seule organisation authentifiée. Les clés restreintes à des collectes, y compris les restrictions vides, sont refusées. Les UUIDs de contact, interaction et document sont des identités distinctes, réadmises comme ids scalaires exacts après Mongo ; un lien ou nom enregistré n’accorde aucune autorité. La note générale CRM est contact.description, distincte de la note d’adresse. Une interaction est un enregistrement CRM, jamais un paiement, rappel, envoi de message ou preuve qu’un événement a eu lieu. Les pièces jointes appartiennent au CONTACT, sans lien natif à une interaction précise ; cette API n’invente jamais ce lien. Aucun paiement, promesse, abonnement, document fiscal, accès membre, état prestataire ou fichier média physique n’est supprimé ou modifié. Aucune requête ne déclenche de téléchargement distant, d’envoi de message ou d’appel prestataire. Les champs query/body inconnus sont refusés. L’authentification de clé API peut enregistrer une télémétrie d’utilisation. Lit uniquement le journal de commandes. Un commandId diffère des UUIDs de contact, interaction et document. Un 404 ou vieux reçu RUNNING ne prouve pas l’échec d’une ancienne écriture. Aucun verrou n’est libéré ou récupéré par cette lecture.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-interactions",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "description": "UUID de commande retourné par une correction CRM, distinct de l’UUID du contact ou de la pièce jointe.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier état de commande enregistré ; canRetry reste toujours false.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, forme d’entrée, révision, clé d’idempotence ou date d’événement invalide ; paramètre inconnu ou corps de lecture non vide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY. Ne pas contourner les restrictions d’accès.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, INTERACTION_NOT_FOUND ou COMMAND_NOT_FOUND. Les ressources absentes, supprimées ou étrangères partagent le même refus.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Historique enregistré ambigu ou invalide, IDEMPOTENCY_CONFLICT, CONTACT_MUTATION_BLOCKED, ou préalable propriétaire indisponible. Aucun objet privé partiel n’est retourné.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. Lire le reçu de commande avant de décider si une écriture soumise peut avoir eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactInteractionsError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-interactions",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /contacts/sync/google/connections

Lire la configuration Google Contacts stockée et qualifiée

`list_contact_google_connections`

Nécessite contacts:read et contacts:sync:read explicitement attribué ; ce dernier est optionnel et ne découle jamais des droits contacts. Les clés restreintes par campagne, même avec une restriction vide, sont refusées car les connexions Google n’ont pas de garde de campagne correspondante. Lecture des seules métadonnées stockées de l’intégration contrôlée actuelle Google Contacts dans l’organisation authentifiée. Cette lecture n’expose ni n’appelle l’ancienne synchronisation Google. Aucun OAuth, rafraîchissement de token, appel Google, test de connexion, réveil de worker, changement de planning, import, confirmation, décision de conflit, écriture de contact ou facturation ; l’authentification peut actualiser sa télémétrie de clé. Aucun email/subject de compte, identité staff propriétaire, environnement/callback privé, credential, token, fiche prestataire, photo, erreur brute, coordonnée de candidat, proposition/snapshot prepared privé ou URL réutilisable n’est retourné. providerChecked:false et workerReadiness:null restent non vérifiés même avec status CONNECTED ou scheduleEnabled:true. Compteurs, booléens, états et dates non natives absents/mal formés restent null, sans zéro/false/date actuelle fabriqués. completeHistory:false : runs/lignes ont une rétention et peuvent expirer ; un résultat vide ne prouve ni absence d’import passé ni absence de conflit. Chaque connexion/run parent actuel est réadmis comme scalaire exact dans l’organisation. Un parent indisponible/inaccessible renvoie 404, jamais une page vide de substitution. limit 1–100, défaut 50 ; source limitée à 5000 lignes et 2 MiB de métadonnées projetées avec 10000 ms par requête. Dépassement ou identité incohérente renvoie 422 sans catalogue partiel ; ne pas retirer de restrictions pertinentes. Un curseur lié à l’instantané modifié exige une nouvelle première page. readAt est l’observation, consistentSnapshot:false. Paramètres query inconnus/répétés, IDs/types invalides et tout corps GET non vide sont refusés. Un 503 est un échec de lecture bornée, jamais l’autorisation de démarrer ou réessayer un import. Connexions triées ID_ASC. Seule une configuration stockée complète acceptée par le vrai validateur pur est projetée ; une configuration absente/invalide vaut null avec UNAVAILABLE_OR_INVALID. Aucun DEFAULT, pays France ou politique absente n’est ajouté. Les enums de champs/politique décrivent le mapping entrant stocké, sans permission sortante ni preuve de préparation. groupIds sont des noms de ressources Google contactGroups enregistrés, jamais des UUID Unisoft ; les mappings gardent leurs paires source/key/type et catégories exactes. La configuration privée d’exécution est exclue. lastRunStats et lastRunState sont le résumé stocké de la connexion, sans recalcul de run courant ni garantie du dernier import réussi. hasImported reste un booléen natif stocké ; absent, il vaut null.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille de page 1–100, défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque lié à l’organisation, clé API/scopes, sélection parente et instantané complet des métadonnées retournées. Recommencer si la configuration/le run/la ligne projetés changent."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée et qualifiée de métadonnées Google Contacts stockées.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncConnectionResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identité, query, corps ou curseur d’instantané périmé invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contacts/synchronisation explicites absents ou restriction de campagne non prise en charge.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Connexion ou run actuel indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Limite de source stockée ou identités incohérentes empêchant une page qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Lecture des métadonnées indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "contacts:sync:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/sync/google/connections/{connectionId}/runs

Lire les runs Google Contacts enregistrés

`list_contact_google_runs`

Nécessite contacts:read et contacts:sync:read explicitement attribué ; ce dernier est optionnel et ne découle jamais des droits contacts. Les clés restreintes par campagne, même avec une restriction vide, sont refusées car les connexions Google n’ont pas de garde de campagne correspondante. Lecture des seules métadonnées stockées de l’intégration contrôlée actuelle Google Contacts dans l’organisation authentifiée. Cette lecture n’expose ni n’appelle l’ancienne synchronisation Google. Aucun OAuth, rafraîchissement de token, appel Google, test de connexion, réveil de worker, changement de planning, import, confirmation, décision de conflit, écriture de contact ou facturation ; l’authentification peut actualiser sa télémétrie de clé. Aucun email/subject de compte, identité staff propriétaire, environnement/callback privé, credential, token, fiche prestataire, photo, erreur brute, coordonnée de candidat, proposition/snapshot prepared privé ou URL réutilisable n’est retourné. providerChecked:false et workerReadiness:null restent non vérifiés même avec status CONNECTED ou scheduleEnabled:true. Compteurs, booléens, états et dates non natives absents/mal formés restent null, sans zéro/false/date actuelle fabriqués. completeHistory:false : runs/lignes ont une rétention et peuvent expirer ; un résultat vide ne prouve ni absence d’import passé ni absence de conflit. Chaque connexion/run parent actuel est réadmis comme scalaire exact dans l’organisation. Un parent indisponible/inaccessible renvoie 404, jamais une page vide de substitution. limit 1–100, défaut 50 ; source limitée à 5000 lignes et 2 MiB de métadonnées projetées avec 10000 ms par requête. Dépassement ou identité incohérente renvoie 422 sans catalogue partiel ; ne pas retirer de restrictions pertinentes. Un curseur lié à l’instantané modifié exige une nouvelle première page. readAt est l’observation, consistentSnapshot:false. Paramètres query inconnus/répétés, IDs/types invalides et tout corps GET non vide sont refusés. Un 503 est un échec de lecture bornée, jamais l’autorisation de démarrer ou réessayer un import. Résoudre connectionId depuis list_contact_google_connections. Runs triés par createdAt BSON natif décroissant, anciennes entrées sans date à la fin et UUID croissant à égalité ; null n’est pas placé à une date inventée. PREVIEW et IMPORT sont distincts ; un PREVIEW réussi n’a pas importé de contacts. Les compteurs loaded/created/updated/skipped/review/failed/pending gardent les inconnues et n’affirment ni succès de toutes les lignes ni activité bancaire/email. PARTIAL/FAILED/STOPPED et WRITE_UNCERTAIN exigent une inspection ; aucune opération retry/resume/confirm n’est exposée ici. Codes d’erreur sur liste explicite ; codes stockés non pris en charge deviennent UNKNOWN_STORED_CODE.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "connectionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID exact actuel de connexion/run Google retourné par ce parcours de métadonnées autorisé ; pas un nom de ressource prestataire, UUID contact ou subject de compte."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille de page 1–100, défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque lié à l’organisation, clé API/scopes, sélection parente et instantané complet des métadonnées retournées. Recommencer si la configuration/le run/la ligne projetés changent."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée et qualifiée de métadonnées Google Contacts stockées.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncRunResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identité, query, corps ou curseur d’instantané périmé invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contacts/synchronisation explicites absents ou restriction de campagne non prise en charge.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Connexion ou run actuel indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Limite de source stockée ou identités incohérentes empêchant une page qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Lecture des métadonnées indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "contacts:sync:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/sync/google/connections/{connectionId}/runs/{runId}/conflicts

Lire les motifs de contrôle Google Contacts stockés

`list_contact_google_conflicts`

Nécessite contacts:read et contacts:sync:read explicitement attribué ; ce dernier est optionnel et ne découle jamais des droits contacts. Les clés restreintes par campagne, même avec une restriction vide, sont refusées car les connexions Google n’ont pas de garde de campagne correspondante. Lecture des seules métadonnées stockées de l’intégration contrôlée actuelle Google Contacts dans l’organisation authentifiée. Cette lecture n’expose ni n’appelle l’ancienne synchronisation Google. Aucun OAuth, rafraîchissement de token, appel Google, test de connexion, réveil de worker, changement de planning, import, confirmation, décision de conflit, écriture de contact ou facturation ; l’authentification peut actualiser sa télémétrie de clé. Aucun email/subject de compte, identité staff propriétaire, environnement/callback privé, credential, token, fiche prestataire, photo, erreur brute, coordonnée de candidat, proposition/snapshot prepared privé ou URL réutilisable n’est retourné. providerChecked:false et workerReadiness:null restent non vérifiés même avec status CONNECTED ou scheduleEnabled:true. Compteurs, booléens, états et dates non natives absents/mal formés restent null, sans zéro/false/date actuelle fabriqués. completeHistory:false : runs/lignes ont une rétention et peuvent expirer ; un résultat vide ne prouve ni absence d’import passé ni absence de conflit. Chaque connexion/run parent actuel est réadmis comme scalaire exact dans l’organisation. Un parent indisponible/inaccessible renvoie 404, jamais une page vide de substitution. limit 1–100, défaut 50 ; source limitée à 5000 lignes et 2 MiB de métadonnées projetées avec 10000 ms par requête. Dépassement ou identité incohérente renvoie 422 sans catalogue partiel ; ne pas retirer de restrictions pertinentes. Un curseur lié à l’instantané modifié exige une nouvelle première page. readAt est l’observation, consistentSnapshot:false. Paramètres query inconnus/répétés, IDs/types invalides et tout corps GET non vide sont refusés. Un 503 est un échec de lecture bornée, jamais l’autorisation de démarrer ou réessayer un import. Résoudre connectionId puis runId avec les outils de métadonnées autorisés. Retourne seulement les lignes stockées dont state est REVIEW ou resolution.kind est REVIEW, triées par index puis ID de ligne. rowId est le hash natif de 64 caractères, pas un UUID contact. Une ligne peut garder une ancienne résolution REVIEW après décision ; c’est un motif de contrôle enregistré, sans garantie de conflit actuellement ouvert. requiresHumanReview:true et canDecide:false : la lecture ne donne aucun droit d’action, ne prouve pas un doublon et n’autorise pas LINK/CREATE. IDs/nombres de candidats, noms, email/téléphone, source, proposal, prepared et indices de cible ne sortent pas ; une référence historique ne donne aucun accès contact actuel. Les motifs sont des codes natifs explicitement autorisés ; les autres deviennent UNKNOWN_STORED_CODE. Les lignes peuvent expirer indépendamment des résumés de runs ; meta.total désigne le sous-ensemble de contrôle actuellement conservé, pas le nombre initial de conflits.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "connectionId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID exact actuel de connexion/run Google retourné par ce parcours de métadonnées autorisé ; pas un nom de ressource prestataire, UUID contact ou subject de compte."
}
```

```json
{
  "name": "runId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID exact actuel de connexion/run Google retourné par ce parcours de métadonnées autorisé ; pas un nom de ressource prestataire, UUID contact ou subject de compte."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille de page 1–100, défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque lié à l’organisation, clé API/scopes, sélection parente et instantané complet des métadonnées retournées. Recommencer si la configuration/le run/la ligne projetés changent."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée et qualifiée de métadonnées Google Contacts stockées.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncConflictResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Identité, query, corps ou curseur d’instantané périmé invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contacts/synchronisation explicites absents ou restriction de campagne non prise en charge.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Connexion ou run actuel indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Limite de source stockée ou identités incohérentes empêchant une page qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Lecture des métadonnées indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSyncError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "contacts:sync:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/communication-preferences

Lire les refus de communication enregistrés pour un contact CRM

`get_contact_communication_preferences`

Autorisation contacts:read requise dans l’organisation connectée ; toute clé restreinte à une campagne est refusée. id est l’UUID exact du contact CRM, pas un compte membre, un UUID d’envoi ni une adresse email. Observation en lecture seule et aperçu d’une désinscription EMAIL explicite. Retourne une révision et l’adresse email normalisée pour la commande ; cette lecture ne crée ni consentement ni commande. Aucun corps ni paramètre de requête n’est accepté. Seul l’email principal courant du contact est observé ; aucune adresse secondaire, de parent ou de famille ne lui est substituée. Le refus EMAIL est attaché à l’adresse normalisée pour toute l’organisation : tous les contacts partageant cette adresse sont donc concernés ; une modification ultérieure de l’email du contact n’est pas suivie. RECORDED indique un refus enregistré dans la politique partagée native ou la liste de désinscription, tandis que NOT_RECORDED indique l’absence de refus enregistré et ne constitue jamais un consentement, une inscription, une preuve de délivrabilité ni une autorisation d’envoyer. sharedPolicyOptOut est le marqueur partagé blocked ; historicalEmailRefusal inclut les anciennes adresses de désinscription dont la casse ou les espaces extérieurs diffèrent, reconnues par cette politique ; legacyOptOut exige une ligne normalisée exacte réellement utilisée par la préparation historique des campagnes. Ces marqueurs peuvent diverger : un refus historique seul ne prouve pas que tous les expéditeurs natifs excluent l’adresse. L’absence d’email principal donne ADDRESS_UNAVAILABLE et des preuves null. SMS et WHATSAPP restent UNKNOWN/NO_CANONICAL_OPTOUT_OWNER sans commande de modification ; ne pas inventer de marqueurs ni supprimer des coordonnées pour simuler un refus. Aucune opération de réinscription ou de consentement positif n’existe. Les lectures réadmettent les propriétaires et références scalaires exacts après Mongo, avec au plus 100 lignes historiques de désinscription correspondantes et 10000 ms par lecture, sans instantané globalement atomique. Une source malformée ou excessive fait refuser toute l’observation. Aucun message n’est envoyé, aucune ligne de file existante n’est annulée et aucun prestataire n’est contacté ; le refus enregistré ne garantit pas l’arrêt des messages déjà préparés ni de tous les expéditeurs transactionnels. Les audiences et exclusions de campagnes restent gérées par leurs parcours existants. 

### 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"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Refus observés et couverture des commandes disponibles ; aucun consentement ni droit d’envoyer n’est déduit.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferencesResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, entrée, email, révision ou clé d’idempotence invalide, ou acquiescement absent ; CHANNEL_OPTOUT_UNSUPPORTED refuse SMS/WHATSAPP. Tous les paramètres de requête et les corps GET sont interdits.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Clé API absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY ; aucun contact ni reçu n’accorde d’autorisation supplémentaire.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou PREFERENCE_COMMAND_NOT_FOUND. L’absence de reçu ne prouve pas qu’une autre demande n’a produit aucun effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PREFERENCE_SOURCE_AMBIGUOUS ou IDEMPOTENCY_CONFLICT ; vérifier les sources ou lire le reçu d’origine sans changer sa clé ni son contenu.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "PREFERENCE_SOURCE_LIMIT : toute l’observation est refusée ; aucune conclusion partielle de consentement n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR ; aucune exception privée ni donnée de prestataire n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission ou le résultat n’a pas pu être prouvé. Lire la commande d’origine ; ne pas réessayer avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## POST /contacts/{id}/communication-preferences/unsubscribe

Enregistrer un refus explicite dans toute l’organisation pour l’email du contact revu

`unsubscribe_contact_email`

Autorisation contacts:read requise dans l’organisation connectée ; toute clé restreinte à une campagne est refusée. id est l’UUID exact du contact CRM, pas un compte membre, un UUID d’envoi ni une adresse email. Exige aussi l’autorisation contacts:unsubscribe explicitement attribuée, sans attribution par défaut. Lire d’abord get_contact_communication_preferences. Fournir channel EMAIL, son adresse normalisée exacte et sa revision, un idempotencyKey stable et acknowledgeSharedAddress:true après avoir expliqué l’effet sur l’adresse partagée. L’utilisateur doit demander ce refus ; ne pas désinscrire pour tester un envoi. Le serveur vérifie à nouveau l’adresse et la révision, enregistre un reçu durable, prend un verrou externe par adresse et effectue un compare-and-set de ADMITTING vers RUNNING avant d’appeler une seule fois le propriétaire natif recordUnsubscribe. Celui-ci bloque d’abord la politique partagée puis écrit la liste de désinscription historique. La même clé et le même contenu lisent uniquement le reçu ; un contenu différent donne IDEMPOTENCY_CONFLICT. ownerInvocationPossible:true signifie que le propriétaire a été admis et a pu démarrer, jamais une preuve d’appel réel ou de fin. COMPLETED sans effet avec ownerInvocationPossible:false signifie que les deux sources ont déjà été observées bloquées. COMPLETED vérifie les deux sources pour l’adresse explicitement revue ; cela n’implique ni l’annulation des envois en file ni un verrou global contre les écritures internes. REJECTED signifie qu’aucun appel natif n’a eu lieu ; examiner error, par exemple REVISION_CONFLICT, EMAIL_ADDRESS_CHANGED ou PREFERENCE_COMMAND_BUSY. ADMITTING/RUNNING décrivent une commande en cours ou interrompue ; le temps écoulé ne prouve pas son échec. PARTIAL/UNKNOWN conservent le verrou de l’adresse et n’autorisent jamais une autre tentative, une nouvelle clé ni la suppression des coordonnées. canRetry est toujours false ; après une réponse perdue, lire get_contact_communication_preference_command et demander une revue autorisée de l’incertitude. Si aucun commandId n’a été reçu, répéter uniquement le POST identique avec sa clé et son contenu d’origine pour retrouver le reçu durable ; cela ne rappelle jamais le propriétaire. success:true et HTTP 200 confirment un reçu, y compris REJECTED : examiner donc state avant d’annoncer que le refus est entièrement enregistré. Seul l’email principal courant du contact est observé ; aucune adresse secondaire, de parent ou de famille ne lui est substituée. Le refus EMAIL est attaché à l’adresse normalisée pour toute l’organisation : tous les contacts partageant cette adresse sont donc concernés ; une modification ultérieure de l’email du contact n’est pas suivie. RECORDED indique un refus enregistré dans la politique partagée native ou la liste de désinscription, tandis que NOT_RECORDED indique l’absence de refus enregistré et ne constitue jamais un consentement, une inscription, une preuve de délivrabilité ni une autorisation d’envoyer. sharedPolicyOptOut est le marqueur partagé blocked ; historicalEmailRefusal inclut les anciennes adresses de désinscription dont la casse ou les espaces extérieurs diffèrent, reconnues par cette politique ; legacyOptOut exige une ligne normalisée exacte réellement utilisée par la préparation historique des campagnes. Ces marqueurs peuvent diverger : un refus historique seul ne prouve pas que tous les expéditeurs natifs excluent l’adresse. L’absence d’email principal donne ADDRESS_UNAVAILABLE et des preuves null. SMS et WHATSAPP restent UNKNOWN/NO_CANONICAL_OPTOUT_OWNER sans commande de modification ; ne pas inventer de marqueurs ni supprimer des coordonnées pour simuler un refus. Aucune opération de réinscription ou de consentement positif n’existe. Les lectures réadmettent les propriétaires et références scalaires exacts après Mongo, avec au plus 100 lignes historiques de désinscription correspondantes et 10000 ms par lecture, sans instantané globalement atomique. Une source malformée ou excessive fait refuser toute l’observation. Aucun message n’est envoyé, aucune ligne de file existante n’est annulée et aucun prestataire n’est contacté ; le refus enregistré ne garantit pas l’arrêt des messages déjà préparés ni de tous les expéditeurs transactionnels. Les audiences et exclusions de campagnes restent gérées par leurs parcours existants. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "address": {
            "type": "string",
            "maxLength": 320,
            "format": "email"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          },
          "acknowledgeSharedAddress": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "channel",
          "address",
          "revision",
          "idempotencyKey",
          "acknowledgeSharedAddress"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Reçu durable COMPLETED, REJECTED, PARTIAL ou UNKNOWN ; examiner state et les deux marqueurs de vérification.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferenceReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La même commande reste ADMITTING ou RUNNING ; aucun appel natif n’a été répété.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferenceReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, entrée, email, révision ou clé d’idempotence invalide, ou acquiescement absent ; CHANNEL_OPTOUT_UNSUPPORTED refuse SMS/WHATSAPP. Tous les paramètres de requête et les corps GET sont interdits.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Clé API absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY ; aucun contact ni reçu n’accorde d’autorisation supplémentaire.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou PREFERENCE_COMMAND_NOT_FOUND. L’absence de reçu ne prouve pas qu’une autre demande n’a produit aucun effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PREFERENCE_SOURCE_AMBIGUOUS ou IDEMPOTENCY_CONFLICT ; vérifier les sources ou lire le reçu d’origine sans changer sa clé ni son contenu.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "PREFERENCE_SOURCE_LIMIT : toute l’observation est refusée ; aucune conclusion partielle de consentement n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR ; aucune exception privée ni donnée de prestataire n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission ou le résultat n’a pas pu être prouvé. Lire la commande d’origine ; ne pas réessayer avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:unsubscribe",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/{id}/communication-preferences/commands/{commandId}

Lire une commande durable de refus d’email d’un contact sans la rejouer

`get_contact_communication_preference_command`

Autorisation contacts:read requise dans l’organisation connectée ; toute clé restreinte à une campagne est refusée. id est l’UUID exact du contact CRM, pas un compte membre, un UUID d’envoi ni une adresse email. Exige aussi l’autorisation contacts:unsubscribe explicitement attribuée. Lire l’UUID commandId retourné par unsubscribe_contact_email. Un contact courant de la même organisation doit exister ; une modification ultérieure de son email ne redirige pas l’adresse du reçu, et un contact supprimé logiquement dans la même organisation peut conserver son reçu. Aucun corps ni paramètre de requête n’est accepté. Retourne uniquement le dernier état durable, sans interroger de prestataire, rappeler le propriétaire natif ni récupérer un verrou. ADMITTING/RUNNING peuvent décrire une commande en cours ou interrompue. PARTIAL/UNKNOWN exigent une revue autorisée ; aucune reprise avec une nouvelle clé, prise de verrou fondée sur son âge ni solution de repli interne n’est disponible. L’absence de reçu ne prouve pas que la demande initiale n’a produit aucun effet. Seul l’email principal courant du contact est observé ; aucune adresse secondaire, de parent ou de famille ne lui est substituée. Le refus EMAIL est attaché à l’adresse normalisée pour toute l’organisation : tous les contacts partageant cette adresse sont donc concernés ; une modification ultérieure de l’email du contact n’est pas suivie. RECORDED indique un refus enregistré dans la politique partagée native ou la liste de désinscription, tandis que NOT_RECORDED indique l’absence de refus enregistré et ne constitue jamais un consentement, une inscription, une preuve de délivrabilité ni une autorisation d’envoyer. sharedPolicyOptOut est le marqueur partagé blocked ; historicalEmailRefusal inclut les anciennes adresses de désinscription dont la casse ou les espaces extérieurs diffèrent, reconnues par cette politique ; legacyOptOut exige une ligne normalisée exacte réellement utilisée par la préparation historique des campagnes. Ces marqueurs peuvent diverger : un refus historique seul ne prouve pas que tous les expéditeurs natifs excluent l’adresse. L’absence d’email principal donne ADDRESS_UNAVAILABLE et des preuves null. SMS et WHATSAPP restent UNKNOWN/NO_CANONICAL_OPTOUT_OWNER sans commande de modification ; ne pas inventer de marqueurs ni supprimer des coordonnées pour simuler un refus. Aucune opération de réinscription ou de consentement positif n’existe. Les lectures réadmettent les propriétaires et références scalaires exacts après Mongo, avec au plus 100 lignes historiques de désinscription correspondantes et 10000 ms par lecture, sans instantané globalement atomique. Une source malformée ou excessive fait refuser toute l’observation. Aucun message n’est envoyé, aucune ligne de file existante n’est annulée et aucun prestataire n’est contacté ; le refus enregistré ne garantit pas l’arrêt des messages déjà préparés ni de tous les expéditeurs transactionnels. Les audiences et exclusions de campagnes restent gérées par leurs parcours existants. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier reçu durable ; aucune réexécution ni reprise.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCommunicationPreferenceReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "UUID, entrée, email, révision ou clé d’idempotence invalide, ou acquiescement absent ; CHANNEL_OPTOUT_UNSUPPORTED refuse SMS/WHATSAPP. Tous les paramètres de requête et les corps GET sont interdits.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Clé API absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY ; aucun contact ni reçu n’accorde d’autorisation supplémentaire.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou PREFERENCE_COMMAND_NOT_FOUND. L’absence de reçu ne prouve pas qu’une autre demande n’a produit aucun effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "PREFERENCE_SOURCE_AMBIGUOUS ou IDEMPOTENCY_CONFLICT ; vérifier les sources ou lire le reçu d’origine sans changer sa clé ni son contenu.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "PREFERENCE_SOURCE_LIMIT : toute l’observation est refusée ; aucune conclusion partielle de consentement n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR ; aucune exception privée ni donnée de prestataire n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission ou le résultat n’a pas pu être prouvé. Lire la commande d’origine ; ne pas réessayer avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:unsubscribe",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/lists/{listId}/members

Consulter les membres d’une liste calculée de contacts autorisée

`list_contact_list_members`

Nécessite contacts:read et tous les droits source du listId exact. Copier listId depuis list_contact_lists : form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID> ou fundraising:<UUID> ; l’UUID source seul est invalide. form/product nécessitent forms:read ET forms_submit:read ; cagnotte nécessite caisses:read ET paiements:read ; event nécessite tous ces droits plus events:read ; fundraising nécessite fundraising:read ET paiements:read ET abonnements:read ET promesses:read. La restriction de collecte de la clé s’applique aux sources fundraising. Utilise les mêmes propriétaires de découverte/CRM protégés que search_contacts_advanced : sources courantes, références scalaires exactes, génération de projection active et tous les droits de domaine sont réadmis. Aucun faux contexte ADMIN ni droit d’accès fondé sur contact.poles enregistré n’est utilisé. Les contacts archivés sont exclus par défaut ; archived:true sélectionne les contacts archivés à la place. Les contacts supprimés restent exclus. Les résultats sont des résumés minimaux de contacts en ordre binaire ID_ASC ; limit vaut 50 par défaut, au plus 100. Conserver archived/limit et le curseur opaque jusqu’à hasMore:false, y compris après une page vide. meta.count est seulement le nombre de lignes de cette page, pas le total des membres. Les sources peuvent changer en parallèle ; listComputedAt est uniquement un instant de dernière projection réussie connu et consistentSnapshot:false. Changer de génération de listes invalide la continuation. Les lectures source sont bornées à 20000 lignes et 10000 ms chacune ; une limite/erreur ne produit aucune appartenance partielle inventée. Ces listes sont des projections automatiques de participation/contribution, pas des listes manuelles modifiables, consentements, validations d’accès ou règlements bancaires. Aucun propriétaire ne permet la création/suppression manuelle des définitions de liste ni l’ajout/retrait direct des membres calculés ; utiliser le vrai parcours formulaire/paiement/événement si explicitement autorisé, ne jamais simuler l’appartenance en écrivant les projections. Aucune synchronisation, reconstruction, mutation source, appel prestataire ou effet métier n’a lieu. Aucun corps n’est accepté et seuls limit/cursor/archived sont autorisés en requête. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "listId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 400
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

```json
{
  "name": "archived",
  "in": "query",
  "schema": {
    "type": "boolean"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page qualifiée de membres utilisant le contrat de réponse de découverte des contacts existant.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou ACCESS_CHANGE_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et tous les droits pertinents sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE ou COMMAND_NOT_FOUND : sélectionner une liste, un pôle ou un reçu courant autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir la projection/l’historique du propriétaire ou conserver le contenu de commande d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE ou CONTACT_SEARCH_AMBIGUOUS_ID : réduire la sélection ou corriger ses identités source ; aucune page de membres tronquée/partielle n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED ou POLE_RULE_JOURNAL_UNAVAILABLE : une lecture qualifiée ou le résultat de commande n’a pas pu être prouvé ; aucun nouvel essai automatique de commande.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-conditional-scopes": [
    {
      "condition": "listId is a form: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a product: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a cagnotte: list",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a event: list",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "listId is a fundraising: list",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/poles/{poleId}/members

Consulter l’appartenance dérivée actuelle à un pôle de contacts

`list_contact_pole_members`

Nécessite contacts:read ET events:read ET forms:read ET forms_submit:read ET caisses:read ET paiements:read. Toute clé limitée à des collectes est refusée. poleId est l’UUID d’un pôle courant ou MAIN pour le pôle par défaut id:null. Calcule l’appartenance native actuelle depuis les règles de catégories et les sources métier autorisées, sans réparer la projection de pôle enregistrée. Utilise les mêmes propriétaires de découverte/CRM protégés que search_contacts_advanced : sources courantes, références scalaires exactes, génération de projection active et tous les droits de domaine sont réadmis. Aucun faux contexte ADMIN ni droit d’accès fondé sur contact.poles enregistré n’est utilisé. Les contacts archivés sont exclus par défaut ; archived:true sélectionne les contacts archivés à la place. Les contacts supprimés restent exclus. Les résultats sont des résumés minimaux de contacts en ordre binaire ID_ASC ; limit vaut 50 par défaut, au plus 100. Conserver archived/limit et le curseur opaque jusqu’à hasMore:false, y compris après une page vide. meta.count est seulement le nombre de lignes de cette page, pas le total des membres. Les sources peuvent changer en parallèle ; listComputedAt est uniquement un instant de dernière projection réussie connu et consistentSnapshot:false. Changer de génération de listes invalide la continuation. Les lectures source sont bornées à 20000 lignes et 10000 ms chacune ; une limite/erreur ne produit aucune appartenance partielle inventée. Ces listes sont des projections automatiques de participation/contribution, pas des listes manuelles modifiables, consentements, validations d’accès ou règlements bancaires. Aucun propriétaire ne permet la création/suppression manuelle des définitions de liste ni l’ajout/retrait direct des membres calculés ; utiliser le vrai parcours formulaire/paiement/événement si explicitement autorisé, ne jamais simuler l’appartenance en écrivant les projections. Aucune synchronisation, reconstruction, mutation source, appel prestataire ou effet métier n’a lieu. Aucun corps n’est accepté et seuls limit/cursor/archived sont autorisés en requête. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "poleId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

```json
{
  "name": "archived",
  "in": "query",
  "schema": {
    "type": "boolean"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page qualifiée des membres actuels du pôle ; aucune écriture d’appartenance ou de projection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou ACCESS_CHANGE_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et tous les droits pertinents sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE ou COMMAND_NOT_FOUND : sélectionner une liste, un pôle ou un reçu courant autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir la projection/l’historique du propriétaire ou conserver le contenu de commande d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE ou CONTACT_SEARCH_AMBIGUOUS_ID : réduire la sélection ou corriger ses identités source ; aucune page de membres tronquée/partielle n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED ou POLE_RULE_JOURNAL_UNAVAILABLE : une lecture qualifiée ou le résultat de commande n’a pas pu être prouvé ; aucun nouvel essai automatique de commande.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/poles/{poleId}/category-rules

Consulter la règle de catégories contrôlant l’appartenance au pôle de contacts

`get_contact_pole_category_rules`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites ; manage est opt-in et les clés limitées à des collectes (même avec une restriction vide) sont refusées. poleId est l’UUID d’un pôle courant ; MAIN sélectionne le pôle natif par défaut id:null, pas un UUID personnalisé ni la chaîne null. Les modifications affectent la visibilité des contacts de l’organisation via la règle native d’appartenance au pôle par catégorie. L’affectation directe de contact.poles n’est pas disponible : l’appartenance vient de l’une des catégories sélectionnées OU de sources d’inscription/paiement éligibles. Les catalogues existants list_contact_lists/list_contact_poles découvrent les identifiants ; un tag et un identifiant de liste sont des objets différents. Lit uniquement les critères de catégories des contacts, le libellé, la présence de configuration et la révision. Aucune liste des accès du personnel ni configuration privée de l’organisation n’est exposée. Une configuration absente signifie configured:false et tags:[], pas un total de membres inventé. La règle native correspond à l’un des tags ; des tags vides retirent uniquement l’appartenance par catégorie, tandis que les inscriptions/paiements peuvent encore conférer l’appartenance. Il ne s’agit pas de l’appartenance complète au pôle ni d’une liste manuelle de membres. projectionRefreshed:false signifie qu’aucune reconstruction de projection enregistrée n’est effectuée. Aucun corps, paramètre de requête, actualisation source, appel prestataire ou mutation métier n’a lieu.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "poleId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Règle de catégories actuelle et révision ; aucune liste des accès du personnel.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleStateResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou ACCESS_CHANGE_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et tous les droits pertinents sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE ou COMMAND_NOT_FOUND : sélectionner une liste, un pôle ou un reçu courant autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir la projection/l’historique du propriétaire ou conserver le contenu de commande d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE ou CONTACT_SEARCH_AMBIGUOUS_ID : réduire la sélection ou corriger ses identités source ; aucune page de membres tronquée/partielle n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED ou POLE_RULE_JOURNAL_UNAVAILABLE : une lecture qualifiée ou le résultat de commande n’a pas pu être prouvé ; aucun nouvel essai automatique de commande.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /contacts/poles/{poleId}/category-rules

Remplacer la règle d’appartenance par catégorie d’un pôle avec une commande protégée

`set_contact_pole_category_rules`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites ; manage est opt-in et les clés limitées à des collectes (même avec une restriction vide) sont refusées. poleId est l’UUID d’un pôle courant ; MAIN sélectionne le pôle natif par défaut id:null, pas un UUID personnalisé ni la chaîne null. Les modifications affectent la visibilité des contacts de l’organisation via la règle native d’appartenance au pôle par catégorie. L’affectation directe de contact.poles n’est pas disponible : l’appartenance vient de l’une des catégories sélectionnées OU de sources d’inscription/paiement éligibles. Les catalogues existants list_contact_lists/list_contact_poles découvrent les identifiants ; un tag et un identifiant de liste sont des objets différents. Commencer par get_contact_pole_category_rules ; fournir sa revision, le tableau tags de remplacement complet (0–500 libellés), une idempotencyKey stable (8–128 caractères ASCII lettres/chiffres/._:-) et acknowledgeAccessChange:true après avoir expliqué l’effet sur la visibilité. Les libellés exacts déjà observés/configurés sont conservés ; les nouveaux reçoivent le formatage CRM canonique (majuscules, accents retirés, espaces remplacés par des tirets bas). Les tags sont dédupliqués/triés. Aucun tag de contact n’est modifié, aucun contact n’est directement affecté/retiré et la liste des accès du personnel reste intacte. Des tags vides désactivent uniquement l’appartenance par catégorie ; ils ne retirent pas les appartenances issues de paiements/inscriptions et ne suppriment pas le pôle/la liste. Il s’agit d’une adaptation du writer natif de configuration de pôle, avec un reçu durable/verrou externe par pôle avant effet, contrôle de révision, comparaison-écriture BSON exacte d’une configuration existante puis relecture. Une configuration absente est créée une fois avec une identité Mongo déterministe ; un doublon natif concurrent est détecté après insertion et signalé UNKNOWN, jamais sélectionné silencieusement. Même clé/contenu retourne le reçu ; un autre contenu renvoie IDEMPOTENCY_CONFLICT. APPLIED/NO_CHANGE vérifient les critères enregistrés et retournent leurs appliedTags canoniques ; null signifie qu’aucun snapshot de tags qualifié n’est disponible, jamais une règle vide. REJECTED n’a fait aucun effet, CONFLICT a perdu la comparaison-écriture et UNKNOWN conserve le verrou lorsque l’effet/la vérification n’est pas prouvé. ADMITTING/RUNNING peuvent être en cours ou interrompus. success:true confirme un reçu, pas un recalcul d’appartenance. canRetry:false : lire get_contact_pole_rule_command après une incertitude et ne jamais répéter avec une autre clé ni écrire contact.poles en contournement. Aucune annulation, récupération automatique ou reprise d’un verrou ancien n’existe. projectionRefreshed:false : comme dans le parcours natif de configuration, les projections d’appartenance enregistrées ne sont pas reconstruites ici ; les lectures de membres utilisent les propriétaires courants et peuvent montrer des changements indépendamment. Aucun prestataire, message ou mutation d’une autre source n’a lieu. Aucun champ de requête n’est accepté.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "poleId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          },
          "acknowledgeAccessChange": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "tags",
          "revision",
          "idempotencyKey",
          "acknowledgeAccessChange"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Reçu terminal enregistré du changement de règle ; aucune affectation directe d’appartenance.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est ADMITTING ou RUNNING ; aucun effet n’a été rejoué.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou ACCESS_CHANGE_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et tous les droits pertinents sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE ou COMMAND_NOT_FOUND : sélectionner une liste, un pôle ou un reçu courant autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir la projection/l’historique du propriétaire ou conserver le contenu de commande d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE ou CONTACT_SEARCH_AMBIGUOUS_ID : réduire la sélection ou corriger ses identités source ; aucune page de membres tronquée/partielle n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED ou POLE_RULE_JOURNAL_UNAVAILABLE : une lecture qualifiée ou le résultat de commande n’a pas pu être prouvé ; aucun nouvel essai automatique de commande.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/pole-rule-commands/{commandId}

Consulter l’état durable d’une commande de règle de catégories d’un pôle

`get_contact_pole_rule_command`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites ; manage est opt-in et les clés limitées à des collectes (même avec une restriction vide) sont refusées. poleId est l’UUID d’un pôle courant ; MAIN sélectionne le pôle natif par défaut id:null, pas un UUID personnalisé ni la chaîne null. Les modifications affectent la visibilité des contacts de l’organisation via la règle native d’appartenance au pôle par catégorie. L’affectation directe de contact.poles n’est pas disponible : l’appartenance vient de l’une des catégories sélectionnées OU de sources d’inscription/paiement éligibles. Les catalogues existants list_contact_lists/list_contact_poles découvrent les identifiants ; un tag et un identifiant de liste sont des objets différents. Utiliser le commandId UUID retourné par set_contact_pole_category_rules. Lit uniquement le dernier reçu durable, en revérifiant les droits courants et l’organisation. Aucun corps ni paramètre de requête n’est accepté. Aucune nouvelle tentative, synchronisation, reconstruction de projection ou libération de verrou n’a lieu. ADMITTING/RUNNING peuvent être interrompus ; UNKNOWN reste incertain et bloque une commande de règle pour ce pôle avec une nouvelle clé. Demander une revue Unisoft autorisée. L’âge, un délai dépassé ou un reçu absent ne prouvent jamais l’absence d’effet. appliedTags décrit seulement les critères vérifiés lors de l’exécution, pas une règle courante ultérieure. Une règle APPLIED vérifiée ne prouve pas une actualisation complète de l’appartenance. canRetry:false dans tous les états.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier état durable de changement de règle ; aucun nouvel essai ni effet de projection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPoleRuleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_MEMBERS_QUERY, INVALID_CONTACT_LIST_ID, INVALID_POLE_ID, INVALID_POLE_RULE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_TAGS, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou ACCESS_CHANGE_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et tous les droits pertinents sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "POLE_NOT_FOUND, CONTACT_LIST_UNAVAILABLE, CONTACT_POLE_UNAVAILABLE ou COMMAND_NOT_FOUND : sélectionner une liste, un pôle ou un reçu courant autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CONTACT_LIST_NOT_READY, CONTACT_LIST_HISTORY_INCOMPLETE, AMBIGUOUS_POLE_CONFIGURATION, INVALID_POLE_RULE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir la projection/l’historique du propriétaire ou conserver le contenu de commande d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "CONTACT_SEARCH_SOURCE_LIMIT, CONTACT_SEARCH_INVALID_SOURCE ou CONTACT_SEARCH_AMBIGUOUS_ID : réduire la sélection ou corriger ses identités source ; aucune page de membres tronquée/partielle n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "CONTACT_LIST_OWNER_UNAVAILABLE, CONTACT_SEARCH_LIMIT_REACHED ou POLE_RULE_JOURNAL_UNAVAILABLE : une lecture qualifiée ou le résultat de commande n’a pas pu être prouvé ; aucun nouvel essai automatique de commande.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/households/capabilities

Découvrir les commandes d’appartenance et de rôle des foyers CRM

`get_contact_household_capabilities`

Exige contact_households:read ET contacts:read, explicitement attribués. Un foyer CRM est le regroupement nommé existant de contacts, pas un compte membre, un accès familial visiteur, une organisation ni un registre financier de foyer. Une personne peut appartenir à plusieurs foyers. Appartenance, rôle enregistré HEAD/MEMBER du foyer, drapeau global contact.isGlobalFamilyHead et relation CRM dirigée sont des faits distincts : aucun n’accorde de connexion, rôle administrateur ou droit financier. Aucun genre, conjoint, parent, tutelle ni rôle légal/fiscal n’est déduit. id est l’UUID du foyer ; les identifiants de contacts viennent des outils de contacts autorisés. name est le libellé stocké ; displayName suit l’affichage natif à partir des prénom/nom du chef actuellement membre et peut être vide. recordedHeadContactId est le chef enregistré réadmis même s’il n’est pas membre ; headContactId est non nul seulement pour un membre actuel. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifie cette observation, pas un état d’accès. Les noms/drapeaux null restent inconnus. Les détails renvoient uniquement l’identité minimale des membres, les révisions opaques du contact/foyer, les relations enregistrées entre membres actuels et les anciens parents dans ce même périmètre. Les relations hors du foyer ne sont pas listées et leur omission ne prouve pas une absence historique. legacyParentContactIds est le stockage natif enfant-vers-parent, distinct de la liste explicite relationships. Le type source PARENT signifie que sourceContactId est parent de relatedContactId ; CHILD est son inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD et les autres valeurs du schéma gardent leur direction exacte. Aucun CRM brut, coordonnées, note, document, paramètre, mot de passe, session, identifiant réutilisable ni montant n’est renvoyé. Aucun état de paiement, promesse, abonnement, reçu, facturation ou compte membre n’est écrit. L’accès membre depuis une application externe reste reporté par décision produit. Chaque identité renvoyée est réadmise comme scalaire exact dans l’organisation authentifiée ; les clés restreintes à des collectes sont refusées car l’appartenance au foyer n’accorde pas d’autorité indépendante de collecte. Les lectures n’initialisent, corrigent, infèrent/récupèrent ni synchronisent une famille, n’appellent aucun fournisseur et ne modifient aucune donnée métier ; l’authentification peut actualiser l’utilisation de la clé. Paramètres/types inconnus et corps GET non vide sont refusés. Les lectures courantes ne sont ni une transaction ni un instantané historique. Détails bornés à 200 membres, 200 appartenances/parents historiques par contact, 2000 relations stockées par contact et 1000 entrées de relations/parents publiées au total ; un dépassement refuse tout le résultat sans troncature. Capacité statique seulement : aucun foyer/contact n’est inspecté ni impact calculé. Aucun paramètre de requête/corps accepté. Les clés restreintes à des collectes peuvent découvrir ce résultat statique mais ne peuvent pas lire/modifier les foyers. Les rôles sont seulement les HEAD et MEMBER natifs ; aucun rôle familial/de compte personnalisé n’est créé.

### Authentification

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

### Permissions requises

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

### Réponses

#### HTTP 200

```json
{
  "description": "Observation courante autorisée du foyer CRM.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactHouseholdCapabilities"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND ou UNEXPECTED_REQUEST_BODY : utiliser uniquement les arguments exacts déclarés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : aucune autorité sur le foyer ni aucun accès de compte n’est accordé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND : foyer, contact, chef ou référence d’ascendance nécessaire absent, supprimé, étranger ou inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité/historique ambigu, révision modifiée, conflit de chef/appartenance/relation, cycle d’ascendance, dépassement de graphe/membres, commande concurrente ou intention idempotente différente. Examiner le code exact ; ne pas le contourner par les anciens outils de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE ou HOUSEHOLD_COMMAND_UNAVAILABLE : conserver l’identité initiale de la commande après une réponse perdue/incertaine ; ne jamais en déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/households

Lister les identifiants et libellés des foyers CRM existants

`list_contact_households`

Exige contact_households:read ET contacts:read, explicitement attribués. Un foyer CRM est le regroupement nommé existant de contacts, pas un compte membre, un accès familial visiteur, une organisation ni un registre financier de foyer. Une personne peut appartenir à plusieurs foyers. Appartenance, rôle enregistré HEAD/MEMBER du foyer, drapeau global contact.isGlobalFamilyHead et relation CRM dirigée sont des faits distincts : aucun n’accorde de connexion, rôle administrateur ou droit financier. Aucun genre, conjoint, parent, tutelle ni rôle légal/fiscal n’est déduit. id est l’UUID du foyer ; les identifiants de contacts viennent des outils de contacts autorisés. name est le libellé stocké ; displayName suit l’affichage natif à partir des prénom/nom du chef actuellement membre et peut être vide. recordedHeadContactId est le chef enregistré réadmis même s’il n’est pas membre ; headContactId est non nul seulement pour un membre actuel. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifie cette observation, pas un état d’accès. Les noms/drapeaux null restent inconnus. Les détails renvoient uniquement l’identité minimale des membres, les révisions opaques du contact/foyer, les relations enregistrées entre membres actuels et les anciens parents dans ce même périmètre. Les relations hors du foyer ne sont pas listées et leur omission ne prouve pas une absence historique. legacyParentContactIds est le stockage natif enfant-vers-parent, distinct de la liste explicite relationships. Le type source PARENT signifie que sourceContactId est parent de relatedContactId ; CHILD est son inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD et les autres valeurs du schéma gardent leur direction exacte. Aucun CRM brut, coordonnées, note, document, paramètre, mot de passe, session, identifiant réutilisable ni montant n’est renvoyé. Aucun état de paiement, promesse, abonnement, reçu, facturation ou compte membre n’est écrit. L’accès membre depuis une application externe reste reporté par décision produit. Chaque identité renvoyée est réadmise comme scalaire exact dans l’organisation authentifiée ; les clés restreintes à des collectes sont refusées car l’appartenance au foyer n’accorde pas d’autorité indépendante de collecte. Les lectures n’initialisent, corrigent, infèrent/récupèrent ni synchronisent une famille, n’appellent aucun fournisseur et ne modifient aucune donnée métier ; l’authentification peut actualiser l’utilisation de la clé. Paramètres/types inconnus et corps GET non vide sont refusés. Les lectures courantes ne sont ni une transaction ni un instantané historique. Détails bornés à 200 membres, 200 appartenances/parents historiques par contact, 2000 relations stockées par contact et 1000 entrées de relations/parents publiées au total ; un dépassement refuse tout le résultat sans troncature. Catalogue seulement : renvoie UUID et libellés stockés, sans compteurs de membres, chefs ni impact. limit vaut 50 par défaut, 100 au maximum. Tri par UUID exact croissant ; conserver nextCursor opaque avec la même organisation, clé et droits jusqu’à hasMore=false si un catalogue complet est requis. count est la taille de cette page, jamais le total organisationnel. L’appartenance peut changer entre les pages. Ces outils ne créent pas de foyer.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "maxLength": 400,
    "pattern": "^[A-Za-z0-9_-]+$"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Observation courante autorisée du foyer CRM.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactHouseholdSummary"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "count",
              "hasMore",
              "nextCursor"
            ],
            "properties": {
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND ou UNEXPECTED_REQUEST_BODY : utiliser uniquement les arguments exacts déclarés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : aucune autorité sur le foyer ni aucun accès de compte n’est accordé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND : foyer, contact, chef ou référence d’ascendance nécessaire absent, supprimé, étranger ou inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité/historique ambigu, révision modifiée, conflit de chef/appartenance/relation, cycle d’ascendance, dépassement de graphe/membres, commande concurrente ou intention idempotente différente. Examiner le code exact ; ne pas le contourner par les anciens outils de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE ou HOUSEHOLD_COMMAND_UNAVAILABLE : conserver l’identité initiale de la commande après une réponse perdue/incertaine ; ne jamais en déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/households/{id}

Lire un foyer CRM, ses membres actuels, son chef et son graphe familial

`get_contact_household`

Exige contact_households:read ET contacts:read, explicitement attribués. Un foyer CRM est le regroupement nommé existant de contacts, pas un compte membre, un accès familial visiteur, une organisation ni un registre financier de foyer. Une personne peut appartenir à plusieurs foyers. Appartenance, rôle enregistré HEAD/MEMBER du foyer, drapeau global contact.isGlobalFamilyHead et relation CRM dirigée sont des faits distincts : aucun n’accorde de connexion, rôle administrateur ou droit financier. Aucun genre, conjoint, parent, tutelle ni rôle légal/fiscal n’est déduit. id est l’UUID du foyer ; les identifiants de contacts viennent des outils de contacts autorisés. name est le libellé stocké ; displayName suit l’affichage natif à partir des prénom/nom du chef actuellement membre et peut être vide. recordedHeadContactId est le chef enregistré réadmis même s’il n’est pas membre ; headContactId est non nul seulement pour un membre actuel. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifie cette observation, pas un état d’accès. Les noms/drapeaux null restent inconnus. Les détails renvoient uniquement l’identité minimale des membres, les révisions opaques du contact/foyer, les relations enregistrées entre membres actuels et les anciens parents dans ce même périmètre. Les relations hors du foyer ne sont pas listées et leur omission ne prouve pas une absence historique. legacyParentContactIds est le stockage natif enfant-vers-parent, distinct de la liste explicite relationships. Le type source PARENT signifie que sourceContactId est parent de relatedContactId ; CHILD est son inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD et les autres valeurs du schéma gardent leur direction exacte. Aucun CRM brut, coordonnées, note, document, paramètre, mot de passe, session, identifiant réutilisable ni montant n’est renvoyé. Aucun état de paiement, promesse, abonnement, reçu, facturation ou compte membre n’est écrit. L’accès membre depuis une application externe reste reporté par décision produit. Chaque identité renvoyée est réadmise comme scalaire exact dans l’organisation authentifiée ; les clés restreintes à des collectes sont refusées car l’appartenance au foyer n’accorde pas d’autorité indépendante de collecte. Les lectures n’initialisent, corrigent, infèrent/récupèrent ni synchronisent une famille, n’appellent aucun fournisseur et ne modifient aucune donnée métier ; l’authentification peut actualiser l’utilisation de la clé. Paramètres/types inconnus et corps GET non vide sont refusés. Les lectures courantes ne sont ni une transaction ni un instantané historique. Détails bornés à 200 membres, 200 appartenances/parents historiques par contact, 2000 relations stockées par contact et 1000 entrées de relations/parents publiées au total ; un dépassement refuse tout le résultat sans troncature. Fournir un UUID exact de foyer issu de list_contact_households ou des appartenances d’un contact. Aucun paramètre de requête/corps accepté. Relire revision fraîchement avant une commande. Un chef enregistré qui n’est pas membre actuel est qualifié NOT_A_MEMBER ; ne pas inventer de remplaçant à partir du genre, des noms ou du drapeau global de chef.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Observation courante autorisée du foyer CRM.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactHousehold"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND ou UNEXPECTED_REQUEST_BODY : utiliser uniquement les arguments exacts déclarés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : aucune autorité sur le foyer ni aucun accès de compte n’est accordé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND : foyer, contact, chef ou référence d’ascendance nécessaire absent, supprimé, étranger ou inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité/historique ambigu, révision modifiée, conflit de chef/appartenance/relation, cycle d’ascendance, dépassement de graphe/membres, commande concurrente ou intention idempotente différente. Examiner le code exact ; ne pas le contourner par les anciens outils de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE ou HOUSEHOLD_COMMAND_UNAVAILABLE : conserver l’identité initiale de la commande après une réponse perdue/incertaine ; ne jamais en déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{contactId}/households

Lire les appartenances d’un contact aux foyers CRM et sa révision de commande

`get_contact_household_memberships`

Exige contact_households:read ET contacts:read, explicitement attribués. Un foyer CRM est le regroupement nommé existant de contacts, pas un compte membre, un accès familial visiteur, une organisation ni un registre financier de foyer. Une personne peut appartenir à plusieurs foyers. Appartenance, rôle enregistré HEAD/MEMBER du foyer, drapeau global contact.isGlobalFamilyHead et relation CRM dirigée sont des faits distincts : aucun n’accorde de connexion, rôle administrateur ou droit financier. Aucun genre, conjoint, parent, tutelle ni rôle légal/fiscal n’est déduit. id est l’UUID du foyer ; les identifiants de contacts viennent des outils de contacts autorisés. name est le libellé stocké ; displayName suit l’affichage natif à partir des prénom/nom du chef actuellement membre et peut être vide. recordedHeadContactId est le chef enregistré réadmis même s’il n’est pas membre ; headContactId est non nul seulement pour un membre actuel. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifie cette observation, pas un état d’accès. Les noms/drapeaux null restent inconnus. Les détails renvoient uniquement l’identité minimale des membres, les révisions opaques du contact/foyer, les relations enregistrées entre membres actuels et les anciens parents dans ce même périmètre. Les relations hors du foyer ne sont pas listées et leur omission ne prouve pas une absence historique. legacyParentContactIds est le stockage natif enfant-vers-parent, distinct de la liste explicite relationships. Le type source PARENT signifie que sourceContactId est parent de relatedContactId ; CHILD est son inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD et les autres valeurs du schéma gardent leur direction exacte. Aucun CRM brut, coordonnées, note, document, paramètre, mot de passe, session, identifiant réutilisable ni montant n’est renvoyé. Aucun état de paiement, promesse, abonnement, reçu, facturation ou compte membre n’est écrit. L’accès membre depuis une application externe reste reporté par décision produit. Chaque identité renvoyée est réadmise comme scalaire exact dans l’organisation authentifiée ; les clés restreintes à des collectes sont refusées car l’appartenance au foyer n’accorde pas d’autorité indépendante de collecte. Les lectures n’initialisent, corrigent, infèrent/récupèrent ni synchronisent une famille, n’appellent aucun fournisseur et ne modifient aucune donnée métier ; l’authentification peut actualiser l’utilisation de la clé. Paramètres/types inconnus et corps GET non vide sont refusés. Les lectures courantes ne sont ni une transaction ni un instantané historique. Détails bornés à 200 membres, 200 appartenances/parents historiques par contact, 2000 relations stockées par contact et 1000 entrées de relations/parents publiées au total ; un dépassement refuse tout le résultat sans troncature. Fournir un UUID de contact autorisé. Renvoie contactRevision et les identifiants/libellés de foyers réadmis, y compris une liste vide pour un contact existant sans foyer. Cette révision est requise comme expectedContactRevision pour ADD_MEMBER ou REMOVE_MEMBER, en plus de la révision du foyer. Aucun paramètre de requête/corps accepté.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "contactId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Observation courante autorisée du foyer CRM.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactHouseholdContactMemberships"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND ou UNEXPECTED_REQUEST_BODY : utiliser uniquement les arguments exacts déclarés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : aucune autorité sur le foyer ni aucun accès de compte n’est accordé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND : foyer, contact, chef ou référence d’ascendance nécessaire absent, supprimé, étranger ou inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité/historique ambigu, révision modifiée, conflit de chef/appartenance/relation, cycle d’ascendance, dépassement de graphe/membres, commande concurrente ou intention idempotente différente. Examiner le code exact ; ne pas le contourner par les anciens outils de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE ou HOUSEHOLD_COMMAND_UNAVAILABLE : conserver l’identité initiale de la commande après une réponse perdue/incertaine ; ne jamais en déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/households/{id}/commands

Modifier une appartenance au foyer CRM, son chef enregistré, son libellé ou une relation familiale exacte

`apply_contact_household_command`

Exige contact_households:write ET contact_households:read ET contacts:read ET contacts:write, tous explicitement attribués. Exige contact_households:read ET contacts:read, explicitement attribués. Un foyer CRM est le regroupement nommé existant de contacts, pas un compte membre, un accès familial visiteur, une organisation ni un registre financier de foyer. Une personne peut appartenir à plusieurs foyers. Appartenance, rôle enregistré HEAD/MEMBER du foyer, drapeau global contact.isGlobalFamilyHead et relation CRM dirigée sont des faits distincts : aucun n’accorde de connexion, rôle administrateur ou droit financier. Aucun genre, conjoint, parent, tutelle ni rôle légal/fiscal n’est déduit. id est l’UUID du foyer ; les identifiants de contacts viennent des outils de contacts autorisés. name est le libellé stocké ; displayName suit l’affichage natif à partir des prénom/nom du chef actuellement membre et peut être vide. recordedHeadContactId est le chef enregistré réadmis même s’il n’est pas membre ; headContactId est non nul seulement pour un membre actuel. headState UNASSIGNED/MEMBER/NOT_A_MEMBER qualifie cette observation, pas un état d’accès. Les noms/drapeaux null restent inconnus. Les détails renvoient uniquement l’identité minimale des membres, les révisions opaques du contact/foyer, les relations enregistrées entre membres actuels et les anciens parents dans ce même périmètre. Les relations hors du foyer ne sont pas listées et leur omission ne prouve pas une absence historique. legacyParentContactIds est le stockage natif enfant-vers-parent, distinct de la liste explicite relationships. Le type source PARENT signifie que sourceContactId est parent de relatedContactId ; CHILD est son inverse. SPOUSE, SIBLING, GRANDPARENT/GRANDCHILD et les autres valeurs du schéma gardent leur direction exacte. Aucun CRM brut, coordonnées, note, document, paramètre, mot de passe, session, identifiant réutilisable ni montant n’est renvoyé. Aucun état de paiement, promesse, abonnement, reçu, facturation ou compte membre n’est écrit. L’accès membre depuis une application externe reste reporté par décision produit. Chaque identité renvoyée est réadmise comme scalaire exact dans l’organisation authentifiée ; les clés restreintes à des collectes sont refusées car l’appartenance au foyer n’accorde pas d’autorité indépendante de collecte. Les lectures n’initialisent, corrigent, infèrent/récupèrent ni synchronisent une famille, n’appellent aucun fournisseur et ne modifient aucune donnée métier ; l’authentification peut actualiser l’utilisation de la clé. Paramètres/types inconnus et corps GET non vide sont refusés. Les lectures courantes ne sont ni une transaction ni un instantané historique. Détails bornés à 200 membres, 200 appartenances/parents historiques par contact, 2000 relations stockées par contact et 1000 entrées de relations/parents publiées au total ; un dépassement refuse tout le résultat sans troncature. Relire le foyer et transmettre sa revision exacte dans expectedRevision ; fournir un nouvel UUID idempotencyKey pour cette intention exacte et le conserver avec tous les arguments initiaux en cas de réponse perdue. Seuls les champs de l’action déclarée sont acceptés ; aucun paramètre de requête. ADD_MEMBER/REMOVE_MEMBER exigent aussi expectedContactRevision exact issu de get_contact_household_memberships ou de la ligne du membre. ADD_MEMBER utilise le propriétaire natif d’ajout/dédoublonnage ; REMOVE_MEMBER retire seulement cette référence de groupe, jamais le contact, les relations CRM ni l’accès membre. Retirer le chef enregistré est refusé jusqu’à SET_HEAD avec un autre membre actuel ou un effacement explicite contactId:null. SET_HEAD adapte le champ natif de chef du foyer, exige un membre actuel et refuse une autre famille déjà dirigée par ce contact ; il ne change pas le drapeau global de chef ni n’infère parent/conjoint. RENAME change seulement le libellé stocké (1–250 caractères, non vide, sans contrôles), pas displayName dérivé. Un état déjà demandé renvoie 409 HOUSEHOLD_ALREADY_IN_STATE pour une nouvelle commande, jamais une fausse preuve de l’ancienne. ADD_RELATION/REMOVE_RELATION exigent deux contacts exacts membres actuels et la relation dans sa direction source exacte. Une paire ne peut avoir des types contradictoires. Le propriétaire natif gère l’inverse ; ne jamais envoyer une seconde commande inverse. REMOVE_RELATION utilise l’option native de paire seule applyMari=false : le lien parental d’un autre conjoint reste conservé. Il ne change ni appartenance au groupe ni parents historiques. ADD_RELATION contrôle les cycles d’ascendance par liens directs, inverses seuls et parents historiques, y compris hors du foyer, avec une limite de 500 descendants et un budget de parcours de 5 secondes par admission. Un graphe nécessaire incomplet/étranger/ambigu ou trop grand renvoie 409/404, jamais un faux verdict d’acyclicité. La propagation native du chef peut rattacher la paire à sa famille existante ou nouvellement créée par le propriétaire ; ses identités réelles sont admises, les foyers affectés sont annoncés dans nativeHouseholdIds et aucun propriétaire de récupération/reconstruction arbitraire n’est appelé. Unicité globale des identifiants natifs, organisation et contacts touchés sont vérifiés avant effet. Les verrous exacts des contacts sont partagés avec l’administration membres en cas de contacts communs ; foyer/ascendance/chef sont aussi réservés avant journal durable et seconde admission. Chaque réservation de verrou/journal exige acknowledged:true et insertedId exact avec writeConcern:{w:1,j:true} ; les CAS inline et confirmations terminales exigent un ACK durable positif. Un journal apparemment APPLIED dont la commande conserve un verrou reste UNKNOWN au rejeu. Les écritures internes/historiques ne partagent pas tous ces verrous ; les révisions sont vérifiées à l’admission, pas par une transaction atomique multi-documents, comme le signale concurrentInternalChangesPossible=true. APPLIED signifie que le propriétaire/CRUD natif conditionnel a répondu et que le résultat requis a été observé, pas une reconstruction familiale complète ni un effet financier/d’accès. resultRevision identifie cette observation confirmée ; household est une lecture courante fraîche qui peut différer au rejeu. NOT_APPLIED signifie que la seconde admission a changé avant effet. UNKNOWN signifie qu’un effet partiel/complet ou une confirmation durable perdue reste possible : les verrous conservés bloquent une autre commande et le propriétaire n’est jamais rejoué automatiquement. La même clé et intention relisent le résultat ; une autre intention donne conflit. Conserver clé, action, révision et références d’origine ; ne jamais utiliser une autre clé, révision corrigée, organisation ou d’anciens outils de contacts pour contourner UNKNOWN ou un verrou en cours. Cette surface ne demande ni approbation de compte, émission/révocation de session, réécriture financière, appel fournisseur ou notification. Après la seconde admission, le garde commun des mutations externes vérifie les ressources exactes réadmises avant tout propriétaire ou CAS inline. CONTACT_MUTATION_BLOCKED ou CONTACT_MUTATION_FENCE_UNAVAILABLE enregistre NOT_APPLIED avant effet ; le rejeu ne réessaie pas cette intention refusée. Si le propriétaire/CAS et le journal terminal ont été positivement confirmés dans la requête courante, un échec du nettoyage conserve APPLIED avec reason HOUSEHOLD_COMMAND_CLEANUP_UNCONFIRMED ; les verrous conservés n’autorisent pas une autre commande. Un rejeu ultérieur avec verrous conservés reste UNKNOWN sans preuve durable fraîche de confirmation terminale.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Examiner APPLIED, NOT_APPLIED ou UNKNOWN avant d’annoncer une modification du foyer.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "replayed",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "replayed": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ContactHouseholdCommandResult"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_HOUSEHOLD_QUERY, INVALID_HOUSEHOLD_CURSOR, INVALID_HOUSEHOLD_ID, INVALID_HOUSEHOLD_COMMAND ou UNEXPECTED_REQUEST_BODY : utiliser uniquement les arguments exacts déclarés.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : aucune autorité sur le foyer ni aucun accès de compte n’est accordé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "HOUSEHOLD_NOT_FOUND : foyer, contact, chef ou référence d’ascendance nécessaire absent, supprimé, étranger ou inadmissible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Identité/historique ambigu, révision modifiée, conflit de chef/appartenance/relation, cycle d’ascendance, dépassement de graphe/membres, commande concurrente ou intention idempotente différente. Examiner le code exact ; ne pas le contourner par les anciens outils de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "HOUSEHOLD_READ_UNAVAILABLE ou HOUSEHOLD_COMMAND_UNAVAILABLE : conserver l’identité initiale de la commande après une réponse perdue/incertaine ; ne jamais en déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_households:write",
  "x-unisoft-additional-scopes": [
    "contact_households:read",
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /contacts/import-jobs

Préparer un job borné et idempotent d’import de contacts

`create_contact_import_job`

Job durable d’import de contacts piloté par le client, privé à l’organisation authentifiée ET à l’identité stable de clé API ; aucune identité staff n’est empruntée et une autre clé ne peut ni le lire ni l’exécuter. Les lignes/options sources sont conservées dans un enregistrement privé d’intégration et jamais retournées par le statut. Schémas publics et options restent ContactImportRowInput et ContactImportInput, sans nouveau mapping métier. Lire get_contact_import_schema et le guide avant normalisation/lookup et contrôler les adresses principales actuelles : le propriétaire bulk peut remplacer celle d’un contact connu. Les champs personnalisés NUMBER/DATETIME suivent les conversions de stockage existantes. L’index de ligne est zéro-based et stable ; sourceRow conserve le __row initial, sinon index+1. Les compteurs décrivent des états enregistrés, sans garantir l’import de chaque fiche. Seuls les codes publics et UUID cibles actuellement réadmis sont exposés ; jamais coordonnées sources, erreurs brutes, provenance privée ou secrets. matchedContactAvailable:null et meta.targetReferencesChecked:false signalent une relecture accessoire indisponible ; une commande acquittée reste retournée, sans transformer un travail connu en erreur générique. L’UUID d’une création n’est pas retourné par le propriétaire et reste inconnu : ne pas l’inventer depuis matchedContactId:null. Sources limitées à 2000 lignes et 2 MiB avant staging. Pages d’états de 1–100 lignes, défaut 50, par index avec curseur opaque lié au job/clé ; les sources sont immuables mais les états peuvent changer entre pages (consistentSnapshot:false). Chaque commande contrôle contacts:write AND contacts:read, propriété, revision et état. Aucun daemon ni traitement implicite ; GET n’avance pas, n’importe pas, ne récupère pas de lease et n’appelle aucun prestataire. Un 409 de révision/busy/état/preview demande la lecture du job avant une nouvelle commande explicite. Une ligne UNKNOWN ou une lease d’exécution expirée n’est pas réessayable : arrêt ATTENTION_REQUIRED sans réexécution par cette API. Résoudre les effets incertains par relecture autorisée/revue manuelle, jamais une répétition aveugle. Les sources conservées ne sont pas effacées automatiquement. Nécessite contacts:write AND contacts:read. idempotencyKey identifie un payload source immuable pour cette organisation/clé. Même clé/payload relit le job ; un autre payload sous cette clé donne 409. Le job DRAFT est seulement stocké : aucune recherche, preview ou écriture de contact. Conserver son UUID et lire sa revision avant preview. Insertion du job, réservations de commande et chaque CAS de ligne/checkpoint demandent explicitement writeConcern durable majority+j:true. Insertions : acknowledged===true et insertedId exact ; findAndModify natif : ok===1, lastErrorObject.n===1, updatedExisting===true et job résultant réadmis exactement avant tout appel propriétaire ou ligne suivante. Document seul, w:0, métadonnées absentes/incohérentes ou erreur writeConcern ne donnent jamais la réservation. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED exige de lire le statut, sans répétition automatique ; l’incertitude après entrée dans le propriétaire réel devient UNKNOWN terminal quand elle peut être consignée durablement.

### Authentification

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

### Permissions requises

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "État durable connu du job et page bornée de résultats par ligne.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Ligne source, options, commande ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scopes de contact ou contexte stable de clé requis manquants.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job indisponible pour cette organisation et cette clé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Conflit d’idempotence, revision, preview, busy ou attention requise. Aucune répétition interdite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Bornes source/job ou données enregistrées mal formées empêchant l’opération.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Stockage ou acquittement propriétaire indisponible. Lire le statut avant toute nouvelle commande.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /contacts/import-jobs/{jobId}

Lire la progression durable et les résultats par ligne d’un import

`get_contact_import_job`

Job durable d’import de contacts piloté par le client, privé à l’organisation authentifiée ET à l’identité stable de clé API ; aucune identité staff n’est empruntée et une autre clé ne peut ni le lire ni l’exécuter. Les lignes/options sources sont conservées dans un enregistrement privé d’intégration et jamais retournées par le statut. Schémas publics et options restent ContactImportRowInput et ContactImportInput, sans nouveau mapping métier. Lire get_contact_import_schema et le guide avant normalisation/lookup et contrôler les adresses principales actuelles : le propriétaire bulk peut remplacer celle d’un contact connu. Les champs personnalisés NUMBER/DATETIME suivent les conversions de stockage existantes. L’index de ligne est zéro-based et stable ; sourceRow conserve le __row initial, sinon index+1. Les compteurs décrivent des états enregistrés, sans garantir l’import de chaque fiche. Seuls les codes publics et UUID cibles actuellement réadmis sont exposés ; jamais coordonnées sources, erreurs brutes, provenance privée ou secrets. matchedContactAvailable:null et meta.targetReferencesChecked:false signalent une relecture accessoire indisponible ; une commande acquittée reste retournée, sans transformer un travail connu en erreur générique. L’UUID d’une création n’est pas retourné par le propriétaire et reste inconnu : ne pas l’inventer depuis matchedContactId:null. Sources limitées à 2000 lignes et 2 MiB avant staging. Pages d’états de 1–100 lignes, défaut 50, par index avec curseur opaque lié au job/clé ; les sources sont immuables mais les états peuvent changer entre pages (consistentSnapshot:false). Chaque commande contrôle contacts:write AND contacts:read, propriété, revision et état. Aucun daemon ni traitement implicite ; GET n’avance pas, n’importe pas, ne récupère pas de lease et n’appelle aucun prestataire. Un 409 de révision/busy/état/preview demande la lecture du job avant une nouvelle commande explicite. Une ligne UNKNOWN ou une lease d’exécution expirée n’est pas réessayable : arrêt ATTENTION_REQUIRED sans réexécution par cette API. Résoudre les effets incertains par relecture autorisée/revue manuelle, jamais une répétition aveugle. Les sources conservées ne sont pas effacées automatiquement. Nécessite contacts:read et la clé propriétaire du job. Ne démarre, reprend, réessaie, récupère ni modifie rien. Une ligne RUNNING dont la lease d’exécution a expiré est présentée UNKNOWN/ATTENTION_REQUIRED sans écriture en base. Les lignes UNKNOWN, previews rejetées et cibles indisponibles exigent une revue explicite ; l’absence d’UUID importé ne prouve aucune absence d’effet. Une preview est un plan projeté ; SUCCEEDED/SKIPPED décrivent un résultat propriétaire acquitté. Ne pas confondre action:create et UUID de création connu. Insertion du job, réservations de commande et chaque CAS de ligne/checkpoint demandent explicitement writeConcern durable majority+j:true. Insertions : acknowledged===true et insertedId exact ; findAndModify natif : ok===1, lastErrorObject.n===1, updatedExisting===true et job résultant réadmis exactement avant tout appel propriétaire ou ligne suivante. Document seul, w:0, métadonnées absentes/incohérentes ou erreur writeConcern ne donnent jamais la réservation. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED exige de lire le statut, sans répétition automatique ; l’incertitude après entrée dans le propriétaire réel devient UNKNOWN terminal quand elle peut être consignée durablement.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "jobId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID du job retourné par create_contact_import_job pour cette même organisation et cette clé."
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "État durable connu du job et page bornée de résultats par ligne.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Ligne source, options, commande ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scopes de contact ou contexte stable de clé requis manquants.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job indisponible pour cette organisation et cette clé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Conflit d’idempotence, revision, preview, busy ou attention requise. Aucune répétition interdite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Bornes source/job ou données enregistrées mal formées empêchant l’opération.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Stockage ou acquittement propriétaire indisponible. Lire le statut avant toute nouvelle commande.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/import-jobs/{jobId}/preview

Prévisualiser les prochaines lignes bornées d’un import préparé

`preview_contact_import_job`

Job durable d’import de contacts piloté par le client, privé à l’organisation authentifiée ET à l’identité stable de clé API ; aucune identité staff n’est empruntée et une autre clé ne peut ni le lire ni l’exécuter. Les lignes/options sources sont conservées dans un enregistrement privé d’intégration et jamais retournées par le statut. Schémas publics et options restent ContactImportRowInput et ContactImportInput, sans nouveau mapping métier. Lire get_contact_import_schema et le guide avant normalisation/lookup et contrôler les adresses principales actuelles : le propriétaire bulk peut remplacer celle d’un contact connu. Les champs personnalisés NUMBER/DATETIME suivent les conversions de stockage existantes. L’index de ligne est zéro-based et stable ; sourceRow conserve le __row initial, sinon index+1. Les compteurs décrivent des états enregistrés, sans garantir l’import de chaque fiche. Seuls les codes publics et UUID cibles actuellement réadmis sont exposés ; jamais coordonnées sources, erreurs brutes, provenance privée ou secrets. matchedContactAvailable:null et meta.targetReferencesChecked:false signalent une relecture accessoire indisponible ; une commande acquittée reste retournée, sans transformer un travail connu en erreur générique. L’UUID d’une création n’est pas retourné par le propriétaire et reste inconnu : ne pas l’inventer depuis matchedContactId:null. Sources limitées à 2000 lignes et 2 MiB avant staging. Pages d’états de 1–100 lignes, défaut 50, par index avec curseur opaque lié au job/clé ; les sources sont immuables mais les états peuvent changer entre pages (consistentSnapshot:false). Chaque commande contrôle contacts:write AND contacts:read, propriété, revision et état. Aucun daemon ni traitement implicite ; GET n’avance pas, n’importe pas, ne récupère pas de lease et n’appelle aucun prestataire. Un 409 de révision/busy/état/preview demande la lecture du job avant une nouvelle commande explicite. Une ligne UNKNOWN ou une lease d’exécution expirée n’est pas réessayable : arrêt ATTENTION_REQUIRED sans réexécution par cette API. Résoudre les effets incertains par relecture autorisée/revue manuelle, jamais une répétition aveugle. Les sources conservées ne sont pas effacées automatiquement. Nécessite contacts:write AND contacts:read. Fournir la dernière revision ; limit 1–500 (défaut 500). Un checkpoint durable de commande est stocké avant l’appel au propriétaire runImport avec dryRun:true, sans mutation de contact. Les actions/problèmes natifs projetés sont enregistrés par ligne ; dix détails au maximum avec issueCount/issuesTruncated explicites. Les cibles correspondantes actuelles sont réadmises avant acceptation du plan. Continuer avec la revision retournée jusqu’à READY et conserver previewFingerprint. Une preview modifiée/échouée ne déclenche jamais d’exécution automatique. La récupération d’une lease PREVIEW expirée enregistre seulement un état récupérable puis retourne ; une nouvelle commande explicite preview traite les lignes restantes. Insertion du job, réservations de commande et chaque CAS de ligne/checkpoint demandent explicitement writeConcern durable majority+j:true. Insertions : acknowledged===true et insertedId exact ; findAndModify natif : ok===1, lastErrorObject.n===1, updatedExisting===true et job résultant réadmis exactement avant tout appel propriétaire ou ligne suivante. Document seul, w:0, métadonnées absentes/incohérentes ou erreur writeConcern ne donnent jamais la réservation. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED exige de lire le statut, sans répétition automatique ; l’incertitude après entrée dans le propriétaire réel devient UNKNOWN terminal quand elle peut être consignée durablement.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "jobId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID du job retourné par create_contact_import_job pour cette même organisation et cette clé."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "default": 500
          }
        },
        "required": [
          "revision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "État durable connu du job et page bornée de résultats par ligne.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Ligne source, options, commande ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scopes de contact ou contexte stable de clé requis manquants.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job indisponible pour cette organisation et cette clé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Conflit d’idempotence, revision, preview, busy ou attention requise. Aucune répétition interdite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Bornes source/job ou données enregistrées mal formées empêchant l’opération.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Stockage ou acquittement propriétaire indisponible. Lire le statut avant toute nouvelle commande.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contacts/import-jobs/{jobId}/execute

Exécuter un lot d’import borné explicitement confirmé

`execute_contact_import_job`

Job durable d’import de contacts piloté par le client, privé à l’organisation authentifiée ET à l’identité stable de clé API ; aucune identité staff n’est empruntée et une autre clé ne peut ni le lire ni l’exécuter. Les lignes/options sources sont conservées dans un enregistrement privé d’intégration et jamais retournées par le statut. Schémas publics et options restent ContactImportRowInput et ContactImportInput, sans nouveau mapping métier. Lire get_contact_import_schema et le guide avant normalisation/lookup et contrôler les adresses principales actuelles : le propriétaire bulk peut remplacer celle d’un contact connu. Les champs personnalisés NUMBER/DATETIME suivent les conversions de stockage existantes. L’index de ligne est zéro-based et stable ; sourceRow conserve le __row initial, sinon index+1. Les compteurs décrivent des états enregistrés, sans garantir l’import de chaque fiche. Seuls les codes publics et UUID cibles actuellement réadmis sont exposés ; jamais coordonnées sources, erreurs brutes, provenance privée ou secrets. matchedContactAvailable:null et meta.targetReferencesChecked:false signalent une relecture accessoire indisponible ; une commande acquittée reste retournée, sans transformer un travail connu en erreur générique. L’UUID d’une création n’est pas retourné par le propriétaire et reste inconnu : ne pas l’inventer depuis matchedContactId:null. Sources limitées à 2000 lignes et 2 MiB avant staging. Pages d’états de 1–100 lignes, défaut 50, par index avec curseur opaque lié au job/clé ; les sources sont immuables mais les états peuvent changer entre pages (consistentSnapshot:false). Chaque commande contrôle contacts:write AND contacts:read, propriété, revision et état. Aucun daemon ni traitement implicite ; GET n’avance pas, n’importe pas, ne récupère pas de lease et n’appelle aucun prestataire. Un 409 de révision/busy/état/preview demande la lecture du job avant une nouvelle commande explicite. Une ligne UNKNOWN ou une lease d’exécution expirée n’est pas réessayable : arrêt ATTENTION_REQUIRED sans réexécution par cette API. Résoudre les effets incertains par relecture autorisée/revue manuelle, jamais une répétition aveugle. Les sources conservées ne sont pas effacées automatiquement. Nécessite contacts:write AND contacts:read. Exige dernière revision, previewFingerprint exact READY et confirm:true. limit 1–50, défaut 10. Chaque ligne NOT_STARTED choisie est durablement marquée RUNNING avec une tentative avant tout appel propriétaire, puis recontrôlée par dry-run ; une action/cible modifiée arrête ATTENTION_REQUIRED avec PREVIEW_CHANGED avant écriture réelle. Le runImport existant applique une ligne et conserve ses règles natives de normalisation/déduplication/upsert. Chaque acquittement est persisté avant la ligne suivante. Exception, WRITE_FAILED, rapport incohérent ou checkpoint perdu après entrée dans le propriétaire réel devient UNKNOWN, avec modifications de contact possiblement partielles ; la ligne et le job ne sont pas rejouables. Une création native ne renvoie aucun nouvel UUID connu. La récupération d’une lease EXECUTE expirée marque la ligne en vol UNKNOWN sans rappel d’import ; aucune annulation présumée. Les lignes rejetées en preview ne sont pas appliquées. COMPLETED signifie toutes les lignes dans un état terminal connu, y compris rejetées/ignorées : lire les compteurs et lignes pertinentes. Ne jamais conclure à toutes les créations ni à une répétition sûre d’une ligne UNKNOWN. Insertion du job, réservations de commande et chaque CAS de ligne/checkpoint demandent explicitement writeConcern durable majority+j:true. Insertions : acknowledged===true et insertedId exact ; findAndModify natif : ok===1, lastErrorObject.n===1, updatedExisting===true et job résultant réadmis exactement avant tout appel propriétaire ou ligne suivante. Document seul, w:0, métadonnées absentes/incohérentes ou erreur writeConcern ne donnent jamais la réservation. CONTACT_IMPORT_JOB_RESULT_UNCONFIRMED exige de lire le statut, sans répétition automatique ; l’incertitude après entrée dans le propriétaire réel devient UNKNOWN terminal quand elle peut être consignée durablement. Juste avant l’import réel, après renouvellement durable de la lease vivante, la garde passive de mutation à l’échelle de l’organisation couvre aussi les créations dont l’UUID résultant est inconnu. Seul l’ID exact de ce job admis par le serveur est exclu pour éviter l’auto-blocage ; aucune exclusion ne vient du client. Autre job/verrou non résolu : CONTACT_MUTATION_BLOCKED (409) ; garde indisponible : CONTACT_MUTATION_FENCE_UNAVAILABLE (503), sans appel d’import réel. Un refus avant l’admission de commande laisse la ligne NOT_STARTED. Après réservation de la commande, un refus tardif consigne REJECTED et arrête le job ATTENTION_REQUIRED lorsque cet enregistrement est acquitté. Ne pas créer un job de remplacement pour contourner cette garde.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "jobId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  },
  "description": "UUID du job retourné par create_contact_import_job pour cette même organisation et cette clé."
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "previewFingerprint": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "confirm": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10
          }
        },
        "required": [
          "revision",
          "previewFingerprint",
          "confirm"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "État durable connu du job et page bornée de résultats par ligne.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Ligne source, options, commande ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scopes de contact ou contexte stable de clé requis manquants.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Job indisponible pour cette organisation et cette clé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Conflit d’idempotence, revision, preview, busy ou attention requise. Aucune répétition interdite.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Bornes source/job ou données enregistrées mal formées empêchant l’opération.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Stockage ou acquittement propriétaire indisponible. Lire le statut avant toute nouvelle commande.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactImportJobError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contacts/{id}/timeline

Lire une chronologie qualifiée de contact depuis des sources explicitement autorisées

`get_contact_timeline`

Nécessite contacts:read et tous les scopes de chaque source choisie, avant toute lecture source. sources est explicite : INTERACTION sans scope supplémentaire ; REGISTRATION exige forms:read AND forms_submit:read ; PAYMENT exige paiements:read, fundraising:read, promesses:read, forms:read, forms_submit:read, caisses:read ; SUBSCRIPTION exige abonnements:read et ces mêmes domaines liés. Ces droits permettent de réadmettre les objets courants sans masquer une activité comme si la chronologie était complète. Un droit manquant donne 403, jamais une chronologie partielle présentée complète. id est l’UUID d’un contact actuel de l’organisation authentifiée ; une archive explicite reste lisible. from/to sont des instants ISO avec fuseau, début inclus/fin exclue, au maximum 366 jours. Seules les BSON dates natives sont placées ; unsupportedDateCount compte les autres formats, anciennes chaînes/nombres compris, dans le périmètre source/contact admis, sans timestamp inventé. Types financiers GENERAL/CAMPAGNE/DETTE/FORM/CAISSE ouverts ; SERVICE, LIVRET et types inconnus exclus explicitement. Une clé restreinte par campagne, même avec une liste vide, limite les sources financières aux liens directs CAMPAGNE autorisés ; KEY_CAMPAIGNS_ONLY ne signifie pas l’absence d’autres activités. Chaque formulaire/soumission/campagne/promesse/caisse lié actuel est réadmis dans cette organisation avec les restrictions de campagne ; une cible indisponible donne 404 sans page partielle. Le contact racine d’abonnement fait autorité ; une racine absente/null peut utiliser payload.contact scalaire avec LEGACY_PAYLOAD_CONTACT, jamais un tableau ni une racine contradictoire. Montants racine et payload ne sont pas interchangés. Les interactions DAY conservent occurredOn ; recordedAt peut être l’ancre de tri à midi du propriétaire, pas une heure réelle connue. Le datetime d’inscription est son enregistrement, pas le début d’événement ; celui d’abonnement est une ancre de contrat, pas une prochaine échéance. Les paiements portent des montants nominaux de tentatives en unités mineures, incluant échecs/en attente/remboursements/traces techniques ; les abonnements portent le nominal contractuel payload.amount en unités mineures, jamais une prévision de recettes ou une échéance encaissée. Les devises restent séparées ; montants/devises/marqueurs inconnus restent null. imported est explicite, jamais false inféré. IN_KIND n’est pas de la trésorerie et UNKNOWN n’est pas présumé monétaire. COMPLETED peut être une autorisation Axepta avant capture ; paymentPhase interprète seulement l’état enregistré. Aucune somme, conversion, frais, déduction de remboursement, vérification bancaire, initialisation de calendrier ni appel prestataire. Les libellés contiennent seulement le type d’interaction ou le libellé courant du formulaire autorisé ; notes, snapshots d’identité, liens documentaires, cartes/mandats/secrets prestataires et métadonnées staff sont exclus. Un échec source refuse toute la demande (FAIL_CLOSED), contrairement au feed interne historique permissif. limit 1–100, défaut 50 ; tri recordedAt décroissant puis source/recordId décroissants, avec curseur opaque lié au contact, organisation, clé, scopes/restriction, sources et période. Continuer avec la même sélection ; un curseur invalide demande de recommencer. readAt date l’observation et non un calcul historique ; consistentSnapshot:false et completeContactHistory:false reconnaissent concurrence, dates/types non pris en charge et domaines non demandés tels que promesses, rappels et approximations email/téléphone. Une page vide prouve seulement l’absence de lignes plaçables dans cette sélection autorisée. Chaque requête est limitée à 10000 ms ; 503 CONTACT_TIMELINE_LIMIT_REACHED demande une période/sélection légitime plus étroite. Propriétés query/body inconnues, mauvais types et dates impossibles sont refusés. Aucune mutation de contact, synchronisation, débit, remboursement, message, émission documentaire ni facturation ; l’authentification peut actualiser la télémétrie de la clé.

### 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"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "sources": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "INTERACTION",
                "REGISTRATION",
                "PAYMENT",
                "SUBSCRIPTION"
              ]
            }
          },
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "sources",
          "from",
          "to"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page qualifiée bornée avec couverture explicite des sources/dates/finances.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Sélection de source, période, type ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Un droit de source choisie ou de domaine lié manque.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Le contact ou un objet courant lié est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une identité ou relation source mal formée empêche une page qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Au moins une source bornée a échoué ; aucune chronologie partielle n’est retournée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTimelineError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "sources contains INTERACTION",
      "scopes": [],
      "allRequired": true
    },
    {
      "condition": "sources contains REGISTRATION",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "sources contains PAYMENT",
      "scopes": [
        "paiements:read",
        "fundraising:read",
        "promesses:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read"
      ],
      "allRequired": true
    },
    {
      "condition": "sources contains SUBSCRIPTION",
      "scopes": [
        "abonnements:read",
        "fundraising:read",
        "promesses:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/bulk/preview

Prévisualiser les modifications d’un lot explicite de contacts

`preview_contact_bulk_update`

Nécessite contacts:bulk ET contacts:read ET contacts:write explicitement attribués ; aucun droit de lot par défaut. Toutes les clés limitées à des collectes, même avec une restriction vide, sont refusées avec CAMPAIGN_RESTRICTED_KEY. Utilise uniquement des UUID de contacts explicites de la même organisation, 1–100 identifiants distincts. Les contacts supprimés sont refusés ; les contacts archivés peuvent être modifiés. Tous les paramètres de requête sont interdits. changes accepte addTags/removeTags (1–50 libellés chacun) et identity avec uniquement firstName, lastName, gender M/F/null ou hebrewFirstName. Les tags utilisent le formatage canonique CRM, sont dédupliqués et ne peuvent pas être ajoutés et retirés ensemble. Les prénoms/noms ne peuvent pas être effacés ; lastName est mis en majuscules, firstName reçoit la capitalisation canonique, gender:null efface explicitement le genre et hebrewFirstName peut être vide. Aucun genre n’est déduit. Les coordonnées, adresses, dates, déclarations fiscales/Gift Aid, champs personnalisés, liens familiaux, cycle de vie, consentements et comptes membres relèvent de leurs parcours dédiés et sont refusés ici. Un même ensemble de modifications est appliqué à la sélection explicite ; il ne s’agit pas d’un import, renommage global de tag, modification de liste enregistrée ou fusion. Observation en lecture seule sans journal ni écriture métier. Toutes les identités sélectionnées et tous les types enregistrés des champs modifiés doivent être valides avant de retourner un aperçu. contactIds/changes canoniques, revision et WILL_CHANGE ou NO_CHANGE pour chaque contact sont retournés sans exposer les données d’identité existantes. Reprendre ces valeurs canoniques dans apply. La révision couvre les champs modifiés sélectionnés, le cycle de vie et les identités exactes ; une modification d’un autre champ ne l’invalide pas. snapshotGuaranteed:false : les writers internes restent actifs et aucune fiche n’est réservée. Aucun prestataire n’est appelé.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "addTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "removeTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "identity": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "M",
                      "F",
                      null
                    ],
                    "nullable": true
                  },
                  "hebrewFirstName": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "contactIds",
          "changes"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Lot canonique et modifications observées pour chaque contact ; aucune mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_BULK_INPUT, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_CONTACT_IDS, INVALID_TAGS, INVALID_BULK_VALUE, CONFLICTING_TAG_CHANGES, EMPTY_CHANGES, INVALID_GENDER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY ou INVALID_UUID : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou COMMAND_NOT_FOUND : un contact est absent, supprimé, étranger ou hors de l’autorité exacte, ou le reçu de commande est inaccessible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_STORED_CONTACT ou IDEMPOTENCY_CONFLICT : revoir l’identité/les données source ou conserver le contenu d’idempotence d’origine ; aucun nouvel effet n’est tenté.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les détails d’erreur privés sont masqués.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "BULK_JOURNAL_UNAVAILABLE : l’admission de commande ou l’enregistrement du résultat n’a pas pu être prouvé. Conserver la même clé ; ne jamais répéter un effet incertain avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:bulk",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/bulk/apply

Appliquer un lot prévisualisé avec contrôle des écritures concurrentes par contact

`apply_contact_bulk_update`

Nécessite contacts:bulk ET contacts:read ET contacts:write explicitement attribués ; aucun droit de lot par défaut. Toutes les clés limitées à des collectes, même avec une restriction vide, sont refusées avec CAMPAIGN_RESTRICTED_KEY. Utilise uniquement des UUID de contacts explicites de la même organisation, 1–100 identifiants distincts. Les contacts supprimés sont refusés ; les contacts archivés peuvent être modifiés. Tous les paramètres de requête sont interdits. changes accepte addTags/removeTags (1–50 libellés chacun) et identity avec uniquement firstName, lastName, gender M/F/null ou hebrewFirstName. Les tags utilisent le formatage canonique CRM, sont dédupliqués et ne peuvent pas être ajoutés et retirés ensemble. Les prénoms/noms ne peuvent pas être effacés ; lastName est mis en majuscules, firstName reçoit la capitalisation canonique, gender:null efface explicitement le genre et hebrewFirstName peut être vide. Aucun genre n’est déduit. Les coordonnées, adresses, dates, déclarations fiscales/Gift Aid, champs personnalisés, liens familiaux, cycle de vie, consentements et comptes membres relèvent de leurs parcours dédiés et sont refusés ici. Un même ensemble de modifications est appliqué à la sélection explicite ; il ne s’agit pas d’un import, renommage global de tag, modification de liste enregistrée ou fusion. Commencer par un aperçu, puis fournir contactIds/changes canoniques, revision et une idempotencyKey stable (8–128 caractères ASCII lettres/chiffres/._:-). Un reçu durable précède chaque effet ; son contenu est lié à la clé. Une même clé/contenu retourne le reçu existant sans nouvel essai ; un contenu différent renvoie IDEMPOTENCY_CONFLICT. La révision est vérifiée à l’admission. REVISION_CONFLICT crée un reçu REJECTED sans effet métier. Chaque fiche modifiée reçoit ensuite une comparaison-et-écriture atomique de ses champs modifiés et de son cycle de vie, limitée à l’organisation/identifiant/identité Mongo exacts, suivie d’une relecture. Ce n’est PAS une transaction atomique sur toute la sélection : un autre writer peut provoquer un CONFLICT sur une ligne alors que d’autres sont modifiées. Un verrou durable de lot par contact bloque un appel avec une nouvelle clé lorsqu’un effet antérieur est incertain ; aucun verrou n’est récupéré en fonction de son âge. Les états de ligne sont APPLIED, NO_CHANGE, CONFLICT, BLOCKED, UNKNOWN ou NOT_ATTEMPTED, avec PENDING/RUNNING pendant l’exécution. COMPLETED signifie que toutes les lignes ont été modifiées ou correspondaient déjà ; PARTIAL signifie au moins un conflit de comparaison-écriture ou un contact bloqué par une commande de lot antérieure ; UNKNOWN signifie qu’un effet ou sa relecture n’a pas pu être prouvé et les lignes suivantes sont arrêtées. ADMITTING/RUNNING peuvent indiquer un traitement en cours ou interrompu ; l’âge ou un délai dépassé ne prouvent jamais l’échec. success:true confirme un reçu enregistré, y compris REJECTED/PARTIAL/UNKNOWN, pas une réussite complète. Examiner chaque ligne. canRetry:false ; consulter get_contact_bulk_update après une incertitude. Ne jamais répéter un lot incertain avec une nouvelle clé ni omettre silencieusement des contacts en conflit ; décrire le résultat exact et obtenir une nouvelle décision avant un nouvel aperçu d’un conflit connu. Aucune reprise automatique, appel prestataire ou annulation automatique n’existe.

### Authentification

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

### Permissions requises

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

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat terminal durable du lot ; consulter l’état global et les états par contact.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "Le lot existant est ADMITTING ou RUNNING ; aucun effet n’a été rejoué.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_BULK_INPUT, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_CONTACT_IDS, INVALID_TAGS, INVALID_BULK_VALUE, CONFLICTING_TAG_CHANGES, EMPTY_CHANGES, INVALID_GENDER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY ou INVALID_UUID : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou COMMAND_NOT_FOUND : un contact est absent, supprimé, étranger ou hors de l’autorité exacte, ou le reçu de commande est inaccessible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_STORED_CONTACT ou IDEMPOTENCY_CONFLICT : revoir l’identité/les données source ou conserver le contenu d’idempotence d’origine ; aucun nouvel effet n’est tenté.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les détails d’erreur privés sont masqués.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "BULK_JOURNAL_UNAVAILABLE : l’admission de commande ou l’enregistrement du résultat n’a pas pu être prouvé. Conserver la même clé ; ne jamais répéter un effet incertain avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:bulk",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/bulk/{commandId}

Consulter l’état durable d’une mise à jour de contacts en lot

`get_contact_bulk_update`

Nécessite contacts:bulk ET contacts:read ET contacts:write explicitement attribués ; aucun droit de lot par défaut. Toutes les clés limitées à des collectes, même avec une restriction vide, sont refusées avec CAMPAIGN_RESTRICTED_KEY. Utilise uniquement des UUID de contacts explicites de la même organisation, 1–100 identifiants distincts. Les contacts supprimés sont refusés ; les contacts archivés peuvent être modifiés. Tous les paramètres de requête sont interdits. Utiliser le commandId UUID retourné par apply. Les droits courants sont revérifiés avant la lecture ; les anciens reçus n’accordent aucun droit. Aucun corps n’est accepté. Retourne les derniers états durables globaux/par contact, sans relire tous les contacts. La lecture ne reprend, ne réessaie et n’annule jamais un lot. APPLIED décrit une modification acquise et vérifiée, sans garantir l’absence de modification ultérieure. ADMITTING/RUNNING peuvent être interrompus ; UNKNOWN reste incertain et ne déclare jamais un échec ou une absence d’effet. L’absence de reçu ne prouve pas l’échec d’un POST. Conserver la clé d’origine et signaler les lignes non résolues ; aucun nouvel essai d’un effet inconnu avec une autre clé.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier reçu durable ; aucun nouvel essai ni continuation automatique.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactBulkReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_BULK_INPUT, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_CONTACT_IDS, INVALID_TAGS, INVALID_BULK_VALUE, CONFLICTING_TAG_CHANGES, EMPTY_CHANGES, INVALID_GENDER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY ou INVALID_UUID : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou COMMAND_NOT_FOUND : un contact est absent, supprimé, étranger ou hors de l’autorité exacte, ou le reçu de commande est inaccessible.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_STORED_CONTACT ou IDEMPOTENCY_CONFLICT : revoir l’identité/les données source ou conserver le contenu d’idempotence d’origine ; aucun nouvel effet n’est tenté.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les détails d’erreur privés sont masqués.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "BULK_JOURNAL_UNAVAILABLE : l’admission de commande ou l’enregistrement du résultat n’a pas pu être prouvé. Conserver la même clé ; ne jamais répéter un effet incertain avec une nouvelle clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:bulk",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/coordinates

Consulter les coordonnées principales et secondaires avec des sélecteurs stables

`get_contact_coordinates`

Nécessite contacts:read. Lit un UUID de contact exact de la même organisation ; les identités supprimées, étrangères ou sous forme de tableau sont refusées. Retourne e-mail, téléphone et adresse principale à plat ainsi que les coordonnées secondaires avec UUID stables et une révision pour les modifications. coordinateId:null sélectionne la principale, qui n’a pas d’UUID. Un sélecteur secondaire vient uniquement de ce résultat ; une chaîne téléphone/e-mail n’est jamais un UUID. Les valeurs scalaires absentes restent null, sans coordonnées inventées. Les chaînes historiques sont des valeurs enregistrées, sans prouver la délivrabilité ou le consentement. Des identifiants secondaires invalides/dupliqués, plus de 100 coordonnées par type ou des types enregistrés invalides refusent la lecture avec INVALID_COORDINATE_HISTORY. Aucun corps n’est accepté. Aucun message, appel prestataire, géocodage, recalcul de proximité, nouveau consentement, changement de compte membre ou de snapshot de facturation historique d’un paiement/justificatif n’a lieu. geographyRecomputed:false est explicite : ces commandes modifient uniquement les coordonnées enregistrées et ne certifient pas les résultats cartographiques/de proximité actuels. Tous les paramètres de requête sont interdits. 

### 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"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Coordonnées enregistrées et révision actuelle ; aucune mutation métier.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateStateResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COORDINATE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_COORDINATE_ID, INVALID_UUID, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, SECONDARY_COORDINATE_REQUIRED, UNEXPECTED_COORDINATE_VALUE, INVALID_ADDRESS, INVALID_LABEL, INVALID_PHONE_COUNTRY, INVALID_COORDINATE_VALUE, INVALID_EMAIL, INVALID_PHONE ou EMPTY_CHANGES : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et les autorisations déclarées sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, COORDINATE_NOT_FOUND ou COMMAND_NOT_FOUND : aucun contact courant autorisé, coordonnée secondaire ou reçu n’a été trouvé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_COORDINATE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir l’identité/les coordonnées enregistrées ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les diagnostics privés sont masqués.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COORDINATE_JOURNAL_UNAVAILABLE : l’admission de l’effet ou l’enregistrement du résultat est incertain. Conserver la même clé et consulter son reçu ; aucun nouvel essai avec une autre clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## PATCH /contacts/{id}/coordinates

Modifier, retirer ou choisir une coordonnée principale du contact

`edit_contact_coordinate`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites ; manage est opt-in. Toute clé limitée à des collectes, même avec une restriction vide, est refusée. Commencer par get_contact_coordinates et transmettre sa revision, une idempotencyKey stable (8–128 caractères ASCII lettres/chiffres/._:-), kind EMAIL/PHONE/ADDRESS, action EDIT/REMOVE/MAKE_PRIMARY et coordinateId (null pour la principale, un UUID exact retourné pour une secondaire). EDIT e-mail/téléphone accepte value et éventuellement un label secondaire ; une principale n’a pas de libellé. L’e-mail utilise la validation CRM canonique et les minuscules ; un téléphone local exige un phoneCountry ISO alpha-2 réel explicite, tandis qu’un téléphone international commence par + et est normalisé en E.164. Aucun pays ni genre n’est déduit. EDIT adresse accepte uniquement les champs address/postalCode/city/region/country/note fournis, plus label/type/companyId pour une secondaire ; aucune métadonnée d’entreprise principale n’existe. La rue ne peut pas être vidée avec EDIT : utiliser REMOVE. REMOVE n’accepte aucune value/label/address, retire uniquement la coordonnée sélectionnée et ne promeut jamais automatiquement une remplaçante. MAKE_PRIMARY exige un UUID secondaire, n’accepte aucune valeur, copie la coordonnée enregistrée vers la principale à plat et préserve sa fiche secondaire/UUID/métadonnées existants. L’ancienne principale est conservée en secondaire avec un nouvel UUID déterministe si elle n’y figure pas déjà ; une lecture suivante le fournit. Pour une adresse principale, seuls les champs physiques/la note sont copiés ; les métadonnées d’entreprise/type/libellé restent sur la secondaire préservée. Modifier/retirer une secondaire ne modifie/retire pas automatiquement une copie principale égale : sélectionner explicitement coordinateId:null pour cela. Au plus 100 coordonnées secondaires par type ; une promotion qui en nécessiterait une 101e est refusée. Modifier un téléphone/e-mail effectue une recherche de dédoublonnage via le propriétaire canonique avec exitDeleted:false ; COORDINATE_IN_USE ne divulgue aucune autre identité. Cette observation ne réserve pas l’unicité globale. La commande enregistre un reçu et un verrou externe par contact avant effet, vérifie la révision, applique une comparaison-écriture atomique BSON exacte des coordonnées/cycle de vie, puis relit le résultat. Même clé/contenu retourne le reçu ; un autre contenu renvoie IDEMPOTENCY_CONFLICT. APPLIED ou NO_CHANGE sont des résultats enregistrés vérifiés ; REJECTED n’a produit aucun effet, CONFLICT a perdu la concurrence sur la comparaison-écriture et UNKNOWN signifie que l’effet/la relecture n’a pas été prouvé et conserve le verrou externe. ADMITTING/RUNNING peuvent indiquer un appel en cours ou interrompu. success:true confirme un reçu, y compris les résultats refusés/inconnus ; consulter state. canRetry:false : lire get_contact_coordinate_command, ne jamais réessayer une incertitude avec une autre clé ni contourner par une édition individuelle. Aucune récupération automatique, annulation ou reprise d’un verrou ancien n’existe. Les writers internes restent actifs et peuvent provoquer des conflits ou modifications ultérieures. Aucun message, appel prestataire, géocodage, recalcul de proximité, nouveau consentement, changement de compte membre ou de snapshot de facturation historique d’un paiement/justificatif n’a lieu. geographyRecomputed:false est explicite : ces commandes modifient uniquement les coordonnées enregistrées et ne certifient pas les résultats cartographiques/de proximité actuels. Tous les paramètres de requête sont interdits. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat terminal enregistré ; success confirme le stockage du reçu, consulter state.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est ADMITTING ou RUNNING ; aucun nouvel appel propriétaire/effet n’a eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COORDINATE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_COORDINATE_ID, INVALID_UUID, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, SECONDARY_COORDINATE_REQUIRED, UNEXPECTED_COORDINATE_VALUE, INVALID_ADDRESS, INVALID_LABEL, INVALID_PHONE_COUNTRY, INVALID_COORDINATE_VALUE, INVALID_EMAIL, INVALID_PHONE ou EMPTY_CHANGES : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et les autorisations déclarées sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, COORDINATE_NOT_FOUND ou COMMAND_NOT_FOUND : aucun contact courant autorisé, coordonnée secondaire ou reçu n’a été trouvé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_COORDINATE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir l’identité/les coordonnées enregistrées ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les diagnostics privés sont masqués.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COORDINATE_JOURNAL_UNAVAILABLE : l’admission de l’effet ou l’enregistrement du résultat est incertain. Conserver la même clé et consulter son reçu ; aucun nouvel essai avec une autre clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/coordinate-commands/{commandId}

Consulter l’état durable d’une commande de coordonnées du contact

`get_contact_coordinate_command`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites et aucune restriction de collecte, revérifiés avant la lecture. Utiliser le commandId UUID retourné par edit_contact_coordinate ; l’UUID d’une coordonnée et celui d’une commande identifient des objets différents. Lit uniquement le dernier reçu durable sans réessayer une écriture, libérer un verrou ou actualiser un état client/prestataire. ADMITTING/RUNNING peuvent décrire un appel interrompu ; un ancien reçu, une réponse perdue ou un 404 ne prouvent jamais l’absence d’effet. UNKNOWN reste incertain et bloque tout autre appel externe de coordonnées pour ce contact, même avec une nouvelle clé ; demander une revue Unisoft autorisée. canRetry:false dans tous les états. Aucun corps n’est accepté. Aucun message, appel prestataire, géocodage, recalcul de proximité, nouveau consentement, changement de compte membre ou de snapshot de facturation historique d’un paiement/justificatif n’a lieu. geographyRecomputed:false est explicite : ces commandes modifient uniquement les coordonnées enregistrées et ne certifient pas les résultats cartographiques/de proximité actuels. Tous les paramètres de requête sont interdits. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier reçu durable de la commande de coordonnées ; aucun nouvel essai.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCoordinateReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COORDINATE_COMMAND, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_COORDINATE_ID, INVALID_UUID, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, SECONDARY_COORDINATE_REQUIRED, UNEXPECTED_COORDINATE_VALUE, INVALID_ADDRESS, INVALID_LABEL, INVALID_PHONE_COUNTRY, INVALID_COORDINATE_VALUE, INVALID_EMAIL, INVALID_PHONE ou EMPTY_CHANGES : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et les autorisations déclarées sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND, COORDINATE_NOT_FOUND ou COMMAND_NOT_FOUND : aucun contact courant autorisé, coordonnée secondaire ou reçu n’a été trouvé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_COORDINATE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir l’identité/les coordonnées enregistrées ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : les diagnostics privés sont masqués.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COORDINATE_JOURNAL_UNAVAILABLE : l’admission de l’effet ou l’enregistrement du résultat est incertain. Conserver la même clé et consulter son reçu ; aucun nouvel essai avec une autre clé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/{id}/lifecycle

Consulter le cycle de vie actif, archivé, à la corbeille ou fusionné d’un contact

`get_contact_lifecycle`

Nécessite contacts:read. Lit un UUID de contact exact de la même organisation, y compris une fiche à la corbeille, sans exposer son identité/coordonnées ni ses données métier liées. state vaut MERGED pour un pointeur mergedInto validé dans la même organisation, sinon TRASHED lorsque deleted:true, ARCHIVED lorsque archived:true, et ACTIVE sinon. Les marqueurs historiques deleted/archived absents/null signifient false comme dans le cycle de vie natif ; deceased/isNew inconnus restent null et ne sont jamais déduits. Corbeille et archivage sont indépendants : restaurer une fiche archivée à la corbeille la remet dans ARCHIVED. Un alias fusionné n’autorise aucune résurrection et ne fournit pas d’annulation de fusion ; une fiche absorbée physiquement retirée est 404. Les identités, marqueurs ou références de fusion invalides/sous forme de tableau sont refusés. Retourne une revision pour une transition volontaire et permanentDeletionAvailable:false. Aucun corps n’est accepté. Seuls les marqueurs du cycle de vie du contact et son horodatage d’édition peuvent changer. Aucun paiement, abonnement, promesse, foyer, compte, consentement, identité ou snapshot imprimé/fiscal historique lié n’est supprimé ou réécrit. Aucun prestataire, message, annulation de fusion, effacement définitif ou récupération automatique n’est déclenché. Tous les paramètres de requête sont interdits. 

### 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"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Marqueurs natifs actuels du cycle de vie et révision ; aucune mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleStateResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_LIFECYCLE_COMMAND, INVALID_LIFECYCLE_ACTION, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_UUID, INVALID_REVISION ou INVALID_IDEMPOTENCY_KEY : corriger la commande déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et les autorisations déclarées sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou COMMAND_NOT_FOUND : aucun contact exact autorisé ou reçu n’a été trouvé. Un contact fusionné physiquement retiré n’est pas recréé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_LIFECYCLE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir l’identité/le cycle de vie enregistrés ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun diagnostic privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "LIFECYCLE_JOURNAL_UNAVAILABLE : l’enregistrement de l’admission/du résultat n’a pas pu être prouvé ; conserver la même clé, consulter le reçu et ne jamais déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

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

## POST /contacts/{id}/lifecycle

Archiver, désarchiver, mettre à la corbeille ou restaurer un contact de manière sûre

`transition_contact_lifecycle`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites ; manage est opt-in. Toute clé limitée à des collectes, même avec une restriction vide, est refusée. Commencer par get_contact_lifecycle, puis fournir action ARCHIVE/UNARCHIVE/TRASH/RESTORE, sa revision et une idempotencyKey stable de 8–128 caractères ASCII lettres/chiffres/._:-. ARCHIVE pose archived:true et efface le marqueur nouveau ; UNARCHIVE pose archived:false. TRASH met à la corbeille avec deleted:true et efface le marqueur nouveau. RESTORE pose uniquement deleted:false et conserve archived, deceased et tous les liens ; il ne restaure pas une fiche fusionnée absorbée/physiquement retirée et n’annule aucune fusion. Archiver/désarchiver une fiche à la corbeille produit REJECTED/RESTORE_REQUIRED ; restaurer d’abord puis examiner le marqueur archived résultant. MERGED_CONTACT_PROTECTED refuse toute transition sur un alias fusionné. Un état déjà satisfait donne NO_CHANGE sauf si l’action native doit aussi effacer le marqueur nouveau. Le serveur enregistre un journal et prend un verrou externe par contact avant effet, vérifie la révision, compare atomiquement les identités exactes et les champs de cycle de vie, puis relit le résultat. Même clé/contenu retourne le reçu sans réécriture ; un autre contenu renvoie IDEMPOTENCY_CONFLICT. APPLIED/NO_CHANGE décrivent un lifecycleState natif vérifié ; CONFLICT indique qu’une modification concurrente du cycle de vie a gagné la comparaison-écriture. REJECTED n’a produit aucun effet ; UNKNOWN signifie que l’effet/la relecture n’a pas été prouvé et conserve le verrou. ADMITTING/RUNNING peuvent être en cours ou interrompus. success:true confirme le stockage du reçu, pas une transition réussie ; consulter state. canRetry:false ; utiliser get_contact_lifecycle_command après une incertitude. Ne jamais employer une autre clé pour répéter un effet inconnu, contourner le verrou par les anciens outils CRUD ou déduire un échec de l’âge/délai dépassé. Aucune prise de contrôle d’un verrou ancien n’existe et les writers internes restent actifs. Seuls les marqueurs du cycle de vie du contact et son horodatage d’édition peuvent changer. Aucun paiement, abonnement, promesse, foyer, compte, consentement, identité ou snapshot imprimé/fiscal historique lié n’est supprimé ou réécrit. Aucun prestataire, message, annulation de fusion, effacement définitif ou récupération automatique n’est déclenché. Tous les paramètres de requête sont interdits. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "ARCHIVE",
              "UNARCHIVE",
              "TRASH",
              "RESTORE"
            ]
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "action",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Reçu terminal enregistré ; consulter state et lifecycleState.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est ADMITTING ou RUNNING ; aucun effet n’a été rejoué.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_LIFECYCLE_COMMAND, INVALID_LIFECYCLE_ACTION, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_UUID, INVALID_REVISION ou INVALID_IDEMPOTENCY_KEY : corriger la commande déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et les autorisations déclarées sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou COMMAND_NOT_FOUND : aucun contact exact autorisé ou reçu n’a été trouvé. Un contact fusionné physiquement retiré n’est pas recréé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_LIFECYCLE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir l’identité/le cycle de vie enregistrés ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun diagnostic privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "LIFECYCLE_JOURNAL_UNAVAILABLE : l’enregistrement de l’admission/du résultat n’a pas pu être prouvé ; conserver la même clé, consulter le reçu et ne jamais déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/lifecycle-commands/{commandId}

Consulter l’état durable d’une transition du cycle de vie d’un contact

`get_contact_lifecycle_command`

Nécessite contacts:manage ET contacts:read ET contacts:write explicites sans restriction de collecte, revérifiés avant la lecture. Utiliser le commandId UUID retourné par transition_contact_lifecycle, pas un UUID de contact. Lit uniquement le dernier reçu durable ; aucune écriture, nouvelle tentative, restauration ou libération de verrou n’a lieu. ADMITTING/RUNNING peuvent être en cours ou interrompus ; UNKNOWN reste incertain et bloque une autre transition externe pour ce contact, même avec une nouvelle clé. Demander une revue Unisoft autorisée. Un reçu absent ou une réponse perdue ne prouve jamais l’absence d’effet. lifecycleState avec APPLIED décrit la vérification au moment de l’exécution, sans garantir l’absence d’écritures internes ultérieures. canRetry:false dans tous les états. Aucun corps n’est accepté. Seuls les marqueurs du cycle de vie du contact et son horodatage d’édition peuvent changer. Aucun paiement, abonnement, promesse, foyer, compte, consentement, identité ou snapshot imprimé/fiscal historique lié n’est supprimé ou réécrit. Aucun prestataire, message, annulation de fusion, effacement définitif ou récupération automatique n’est déclenché. Tous les paramètres de requête sont interdits. 

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier reçu durable de transition ; aucune continuation ni nouvel essai.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactLifecycleReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_LIFECYCLE_COMMAND, INVALID_LIFECYCLE_ACTION, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_UUID, INVALID_REVISION ou INVALID_IDEMPOTENCY_KEY : corriger la commande déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : l’organisation courante exacte et les autorisations déclarées sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CONTACT_NOT_FOUND ou COMMAND_NOT_FOUND : aucun contact exact autorisé ou reçu n’a été trouvé. Un contact fusionné physiquement retiré n’est pas recréé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "AMBIGUOUS_CONTACT_ID, INVALID_LIFECYCLE_HISTORY ou IDEMPOTENCY_CONFLICT : revoir l’identité/le cycle de vie enregistrés ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun diagnostic privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "LIFECYCLE_JOURNAL_UNAVAILABLE : l’enregistrement de l’admission/du résultat n’a pas pu être prouvé ; conserver la même clé, consulter le reçu et ne jamais déduire une absence d’effet.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "contacts:manage",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/exports/postal

Lire les étiquettes postales principales de contacts ou leur regroupement explicite en foyer

`export_contact_postal_addresses`

Nécessite contacts:read. Export en lecture seule de 1–2000 UUID explicites de contacts actuels non supprimés de l’organisation authentifiée, avec réadmission de chaque identité avant export. Les archives restent sélectionnables ; une fiche indisponible refuse la sélection entière avec 404. Noms et composants postaux absents restent null ; aucun pays, ville, genre ni coordonnée n’est inféré. Aucune note privée, code/porte d’accès, identifiant fiscal, token, URL de photo/document ou donnée de paiement n’est retourné. Seuls les propriétaires purs canoniques de présentation/adresse sont appelés ; aucun géocodeur, prestataire cartographique, itinéraire, recherche payante, écriture de contact ou synchronisation. L’authentification peut actualiser la télémétrie de clé. Contexte limité à 5000 contacts/lignes dérivées et 4 MiB projetés, avec 422 sans troncature partielle. Requêtes bornées à 10000 ms. limit 1–100 (défaut 50), curseur lié à l’organisation, clé/scopes, sélection, mode et instantané dérivé complet. Un changement d’adresse/foyer/coordonnées invalide le curseur ; recommencer avant d’utiliser un export supposé complet. readAt date l’observation et consistentSnapshot:false, sans garantie d’adresse historique. Propriétés query/body inconnues, projections arbitraires, IDs/modes invalides et mauvais types sont refusés. Une incohérence source/famille refuse l’export qualifié : ne pas omettre un membre pour contourner. CONTACT est le défaut et produit l’adresse principale de chaque fiche sélectionnée avec prénom/nom enregistrés seulement ; les fiches sans adresse sont comptées dans skippedNoAddress, sans adresse secondaire supposée. HOUSEHOLD doit être explicite. Il réutilise buildPostalExportRows, sa déduplication famille/adresse et son choix de représentant. Familles actuelles, membres, chefs et fermeture des liens de mariage sont réadmis dans l’organisation ; des membres actuels non sélectionnés peuvent fournir l’adresse du foyer. Des familles distinctes à une adresse gardent des étiquettes distinctes. Le destinataire retire toute civilité inférée par le propriétaire et emploie NAME_ONLY, sans fabriquer de fait démographique. representativeContactId est retourné seulement si la ligne se rattache de façon unique à un contact actuel admis ; une identité ambiguë reste null. familyLabel peut être inconnu. En HOUSEHOLD, skippedNoAddress compte les candidatures cible/famille sans adresse admissible, pas nécessairement des personnes distinctes. Aucune mutation de famille/fusion ni fichier d’étiquette persistant.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "mode": {
            "type": "string",
            "enum": [
              "CONTACT",
              "HOUSEHOLD"
            ],
            "default": "CONTACT"
          }
        },
        "required": [
          "contactIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de la sélection postale/cartographique autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Sélection, mode ou curseur d’instantané modifié invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Un contact sélectionné, membre du foyer ou famille actuelle est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Borne source, relation mal formée ou identité/adresse dupliquée empêchant l’export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée d’adresse n’a pas pu terminer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/exports/map

Lire les coordonnées enregistrées autorisées d’une sélection d’adresses

`get_contact_address_map`

Nécessite contacts:read. Export en lecture seule de 1–2000 UUID explicites de contacts actuels non supprimés de l’organisation authentifiée, avec réadmission de chaque identité avant export. Les archives restent sélectionnables ; une fiche indisponible refuse la sélection entière avec 404. Noms et composants postaux absents restent null ; aucun pays, ville, genre ni coordonnée n’est inféré. Aucune note privée, code/porte d’accès, identifiant fiscal, token, URL de photo/document ou donnée de paiement n’est retourné. Seuls les propriétaires purs canoniques de présentation/adresse sont appelés ; aucun géocodeur, prestataire cartographique, itinéraire, recherche payante, écriture de contact ou synchronisation. L’authentification peut actualiser la télémétrie de clé. Contexte limité à 5000 contacts/lignes dérivées et 4 MiB projetés, avec 422 sans troncature partielle. Requêtes bornées à 10000 ms. limit 1–100 (défaut 50), curseur lié à l’organisation, clé/scopes, sélection, mode et instantané dérivé complet. Un changement d’adresse/foyer/coordonnées invalide le curseur ; recommencer avant d’utiliser un export supposé complet. readAt date l’observation et consistentSnapshot:false, sans garantie d’adresse historique. Propriétés query/body inconnues, projections arbitraires, IDs/modes invalides et mauvais types sont refusés. Une incohérence source/famille refuse l’export qualifié : ne pas omettre un membre pour contourner. addressMode vaut PRIMARY par défaut (addressId MAIN) ; ALL inclut aussi les UUID d’adresses secondaires actuelles. Chaque adresse sélectionnée produit une ligne même sans coordonnées ; les contacts sans adresse choisie sont comptés dans contactsWithoutAddress. Les géos stockées exigent des nombres natifs finis dans les bornes géographiques et la vérification propriétaire de query encore concordante avec l’adresse actuelle normalisée. Un bon addressId seul ne suffit pas : anciennes coordonnées d’adresse et chaînes numériques/null sont exclus. Coordonnées non vérifiées toutes deux null avec NO_VERIFIED_STORED_COORDINATE, jamais 0/0 inventé ; les valeurs natives 0 restent valides si leur query d’adresse correspond. STORED_CURRENT_ADDRESS_MATCH ne certifie ni précision au bâtiment, ni fraîcheur prestataire, ni nouveau géocodage. Seules les adresses des contacts choisis sont utilisées ; aucun contexte familial étendu, placement de pin externe ou lecture de secret d’accès.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "addressMode": {
            "type": "string",
            "enum": [
              "PRIMARY",
              "ALL"
            ],
            "default": "PRIMARY"
          }
        },
        "required": [
          "contactIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de la sélection postale/cartographique autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactMapExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Sélection, mode ou curseur d’instantané modifié invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Un contact sélectionné, membre du foyer ou famille actuelle est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Borne source, relation mal formée ou identité/adresse dupliquée empêchant l’export.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée d’adresse n’a pas pu terminer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactPostalExportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/reconciliation

Rapprocher une projection bornée des contacts actuels avec un manifeste client

`reconcile_contact_directory`

Nécessite contacts:read. Réconciliation en lecture seule par le propriétaire des manifestes d’annuaire, sans journal horodaté ni curseur de changements reprenable. Premier appel avec {}. Une sélection facultative de 1–2000 contactIds explicites est possible, y compris des IDs connus devenus indisponibles ; ne jamais déduire leur existence de l’entrée. Aux appels suivants, fournir les data.scope et data.manifest complets précédents dans baseline, avec la même sélection. Chaque appel relit les contacts actuels non supprimés de cette organisation, archives comprises, puis compare les hashes des seuls champs de projection annoncés. Au maximum 10000 contacts actuels, entrées de baseline et entrées retournées de manifest/upserts/removed, avec 8 MiB de payload propriétaire. Une organisation complète de plus de 10000 renvoie 422 CONTACT_RECONCILIATION_LIMIT_EXCEEDED avant tout manifeste, sans troncature. Résoudre alors une sélection explicite fixe légitime de 2000 contactIds maximum, sans abandon silencieux de lignes ni réutilisation d’un manifeste incomplet. Employer une sélection explicite fixe légitime ou un autre parcours d’échange pris en charge quand l’annuaire dépasse la borne, sans abandon silencieux de contacts. Changer organisation/clé/scopes/restriction/sélection/projection change scope et donne reset:true sans retrait inféré. Remplacer le manifeste sauvegardé seulement après réception et application d’une réponse complète réussie. upserts fournit les nouvelles lignes projetées ou celles modifiées, avec null pour les valeurs inconnues. removed fournit les anciens IDs absents de l’observation actuelle et reason:UNKNOWN ; cela peut refléter suppression, fusion, perte de disponibilité, changement de sélection en conservant une ancienne baseline ou concurrence, sans prouver une suppression ni identifier une fiche conservée. Ne pas supprimer automatiquement une personne distante ni réattribuer un identifiant externe depuis removed. completeChangeJournal, mergeHistoryAvailable et hardDeleteReasonAvailable sont faux ; archiveCurrentStateIncluded décrit seulement le marqueur d’archive actuel, pas toutes les transitions archivage/restauration. Aucun changement transitoire annulé entre observations, champ de sous-ressource hors couverture, chaîne de fusion historique ou tombstone n’est garanti. Les versions de baseline sont des hashes de projection, sans autorisation ni séquence d’événement serveur. observedAt date l’observation et consistentSnapshot:false ; des modifications concurrentes restent possibles. Les dates historiques absentes restent null. Une identité mal formée ou dupliquée donne 422, sans manifeste faussement complet. Propriétés query/body inconnues, IDs de baseline invalides/dupliqués et mauvais types sont refusés. Exécution limitée à 10000 ms ; 503 CONTACT_RECONCILIATION_QUERY_LIMIT demande une sélection légitime plus petite. Aucune reconstruction, synchronisation, archive, restauration, fusion, suppression, écriture métier, facturation ni appel prestataire ; l’authentification peut actualiser la télémétrie de la clé. La sortie MCP dispose d’un quota explicite de 250000 nœuds JSON et 16 MiB, profondeur 40 inchangée, distinct de la borne métier inférieure de 8 MiB. Des tableaux de tags très denses peuvent encore dépasser ce quota de transport. Aucun résultat partiel n’est publié ; réduire seulement une sélection explicite légitime en préservant son sens. Ce contrat externe ne propose aucun aller-retour de 20000 contacts.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "baseline": {
            "type": "object",
            "properties": {
              "scope": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "manifest": {
                "type": "array",
                "maxItems": 10000,
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "version": {
                      "type": "string",
                      "pattern": "^[a-f0-9]{64}$"
                    }
                  },
                  "required": [
                    "id",
                    "version"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "scope",
              "manifest"
            ],
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Réponse complète bornée de rapprochement pour cette projection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Sélection ou manifeste de référence invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Taille de l’annuaire, borne de payload ou identité historique mal formée empêchant un rapprochement complet.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée de l’annuaire n’a pas pu terminer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactReconciliationError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp-output-limits": {
    "maxNodes": 250000,
    "maxBytes": 16777216
  },
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/quality/inspect

Lire les constats de qualité et candidats doublons bornés d’une sélection

`inspect_contact_quality`

Nécessite contacts:read. Diagnostics frais en lecture seule de 1–200 contacts explicitement sélectionnés, actuels et non supprimés dans l’organisation authentifiée, via le catalogue pur de qualité du produit. Chaque UUID est réadmis avant analyse ; une cible inaccessible donne 404 sans sélection partielle. Méthodes limitées à whitespace, email, phone, addresses, dates, customFields, categories, duplicates, completeness ; aucune règle libre, expression arbitraire, lecture de source d’activité, enrichissement externe ni appel IA/prestataire. phoneCountry est un code pays ISO alpha-2 majuscule connu facultatif pour les diagnostics téléphoniques ; ne pas le deviner. Sans pays, PHONE_REQUIRES_REVIEW peut remplacer la normalisation. Les groupes doublons sont des propositions heuristiques selon noms/coordonnées et correspondances téléphoniques historiques du propriétaire ; jamais une décision d’identité confirmée ou une inférence fiable de pays. Les contrôles génériques peuvent inclure les protections d’identité enfant du propriétaire, avec leurs propres codes de méthode/raison. Seuls ID de constat, méthode, reasonCode, contactIds réadmis, sévérité connue et indicateurs de revue sont retournés ; before/after, commandes, preuves sources, notes, analyses privées et valeurs de remplacement sont exclus. requiresHumanReview:true et canApply:false sont inconditionnels : aucune application, décision, fusion, suppression ou correction possible. La couverture SELECTED_CURRENT_CONTACTS_ONLY ne constitue ni un scan complet de doublons de l’organisation, ni un graphe familial, ni une analyse historique, ni une analyse privée sauvegardée d’un membre du personnel. Les contextes familiaux/sources manquants limitent les conclusions ; aucun constat ne prouve des données propres ou l’absence de doublon ailleurs. Les archives explicitement sélectionnées peuvent être analysées, mais le regroupement générique propriétaire exclut les archives/suppressions. limit 1–100, défaut 50, ordre fixe par ID de constat. Le curseur dépend de l’organisation, clé, scopes, contacts, méthodes, pays et empreinte observée ; un changement demande une nouvelle première page. readAt date l’observation, sans analyse persistée ni instantané transactionnel garanti. Au maximum 2 MiB de sources projetées et 10000 constats, sans troncature partielle ; 422 CONTACT_QUALITY_SOURCE_LIMIT demande une sélection plus petite. Requêtes de base limitées à 10000 ms ; 503 CONTACT_QUALITY_LIMIT_REACHED demande de réduire la sélection. Propriétés query/body inconnues, mauvais types et méthodes non prises en charge sont refusés. Aucune analyse, décision, mutation, fusion, géocodage, synchronisation ou facturation n’est persistée ni appel prestataire déclenché ; l’authentification peut actualiser la télémétrie de la clé.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "methods": {
            "type": "array",
            "minItems": 1,
            "maxItems": 9,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "whitespace",
                "email",
                "phone",
                "addresses",
                "dates",
                "customFields",
                "categories",
                "duplicates",
                "completeness"
              ]
            }
          },
          "phoneCountry": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "contactIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Diagnostics qualifiés en lecture seule pour la sélection autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Sélection, méthode, pays, limite ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Au moins un contact sélectionné est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "La taille source, une identité mal formée ou l’intégrité des constats empêche un résultat qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Le propriétaire de qualité borné n’a pas pu terminer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReadError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports/latest

Lire le dernier bilan préparé de qualité des contacts

`get_latest_contact_quality_report`

Nécessite contacts:read pour l’organisation authentifiée. Lit uniquement les bilans préparés : aucun calcul, parcours des sources historiques, appel IA, mise en file ni modification de contact. global inclut local ; local utilise le marquage favori existant. all inclut les contacts inactifs ; active exige une activité métier qualifiée depuis moins de 12 mois. L’activité est un classement dérivé global de l’organisation, indépendant des scopes de paiement ; aucun montant, date d’activité protégée, détail source ou trace technique n’est renvoyé. Les effectifs de KPI peuvent se recouper. score est null quand aucun contact n’est évaluable ; lire coverage et unknown avec la note. Les droits actuels sur les contacts sont appliqués avant agrégation et pagination. Un changement de périmètre historique donne scope_changed avec mesures et explication indisponibles ; ce résultat ne vaut jamais une note de zéro. Les explications restent liées à leur révision measuredAt réelle. Les curseurs sont opaques et liés à l’organisation, au principal, au bilan, aux droits actuels et aux filtres ; garder les filtres identiques et recommencer si les droits changent. Aucun webhook public de bilan n’est émis. Cette lecture est distincte de inspect_contact_quality, qui calcule des diagnostics bornés pour une sélection explicite.

Lire cette opération en premier pour connaître la disponibilité et les mesures préparées les plus récentes. Une première préparation en attente ou en échec renvoie metrics à null.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat préparé dans le périmètre actuellement autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Filtres, limite, KPI ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Bilan indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Le périmètre de contacts du bilan a changé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Bilan préparé temporairement indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports

Lister l’historique des bilans préparés de qualité des contacts

`list_contact_quality_reports`

Nécessite contacts:read pour l’organisation authentifiée. Lit uniquement les bilans préparés : aucun calcul, parcours des sources historiques, appel IA, mise en file ni modification de contact. global inclut local ; local utilise le marquage favori existant. all inclut les contacts inactifs ; active exige une activité métier qualifiée depuis moins de 12 mois. L’activité est un classement dérivé global de l’organisation, indépendant des scopes de paiement ; aucun montant, date d’activité protégée, détail source ou trace technique n’est renvoyé. Les effectifs de KPI peuvent se recouper. score est null quand aucun contact n’est évaluable ; lire coverage et unknown avec la note. Les droits actuels sur les contacts sont appliqués avant agrégation et pagination. Un changement de périmètre historique donne scope_changed avec mesures et explication indisponibles ; ce résultat ne vaut jamais une note de zéro. Les explications restent liées à leur révision measuredAt réelle. Les curseurs sont opaques et liés à l’organisation, au principal, au bilan, aux droits actuels et aux filtres ; garder les filtres identiques et recommencer si les droits changent. Aucun webhook public de bilan n’est émis. Cette lecture est distincte de inspect_contact_quality, qui calcule des diagnostics bornés pour une sélection explicite.

L’historique est conservé pendant 12 mois. Les éléments contiennent les résumés de mesures préparés ; utiliser get_contact_quality_report pour charger une explication. Ajouter ou retirer des contacts ne réécrit pas les mesures passées. Les résultats sont triés par date de mesure décroissante, puis par identifiant de bilan décroissant en cas de dates égales. limit vaut 1–100, avec 25 par défaut.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat préparé dans le périmètre actuellement autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportHistoryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Filtres, limite, KPI ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Bilan indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Le périmètre de contacts du bilan a changé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Bilan préparé temporairement indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports/{reportId}

Lire un bilan daté de qualité des contacts

`get_contact_quality_report`

Nécessite contacts:read pour l’organisation authentifiée. Lit uniquement les bilans préparés : aucun calcul, parcours des sources historiques, appel IA, mise en file ni modification de contact. global inclut local ; local utilise le marquage favori existant. all inclut les contacts inactifs ; active exige une activité métier qualifiée depuis moins de 12 mois. L’activité est un classement dérivé global de l’organisation, indépendant des scopes de paiement ; aucun montant, date d’activité protégée, détail source ou trace technique n’est renvoyé. Les effectifs de KPI peuvent se recouper. score est null quand aucun contact n’est évaluable ; lire coverage et unknown avec la note. Les droits actuels sur les contacts sont appliqués avant agrégation et pagination. Un changement de périmètre historique donne scope_changed avec mesures et explication indisponibles ; ce résultat ne vaut jamais une note de zéro. Les explications restent liées à leur révision measuredAt réelle. Les curseurs sont opaques et liés à l’organisation, au principal, au bilan, aux droits actuels et aux filtres ; garder les filtres identiques et recommencer si les droits changent. Aucun webhook public de bilan n’est émis. Cette lecture est distincte de inspect_contact_quality, qui calcule des diagnostics bornés pour une sélection explicite.

Utiliser un reportId renvoyé par le dernier bilan ou l’historique pour lire cette révision datée.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "reportId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_.:-]{1,200}$"
  }
}
```

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat préparé dans le périmètre actuellement autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Filtres, limite, KPI ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Bilan indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Le périmètre de contacts du bilan a changé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Bilan préparé temporairement indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/quality/reports/{reportId}/contacts

Lister les contacts actuels d’un KPI du bilan

`list_contact_quality_report_contacts`

Nécessite contacts:read pour l’organisation authentifiée. Lit uniquement les bilans préparés : aucun calcul, parcours des sources historiques, appel IA, mise en file ni modification de contact. global inclut local ; local utilise le marquage favori existant. all inclut les contacts inactifs ; active exige une activité métier qualifiée depuis moins de 12 mois. L’activité est un classement dérivé global de l’organisation, indépendant des scopes de paiement ; aucun montant, date d’activité protégée, détail source ou trace technique n’est renvoyé. Les effectifs de KPI peuvent se recouper. score est null quand aucun contact n’est évaluable ; lire coverage et unknown avec la note. Les droits actuels sur les contacts sont appliqués avant agrégation et pagination. Un changement de périmètre historique donne scope_changed avec mesures et explication indisponibles ; ce résultat ne vaut jamais une note de zéro. Les explications restent liées à leur révision measuredAt réelle. Les curseurs sont opaques et liés à l’organisation, au principal, au bilan, aux droits actuels et aux filtres ; garder les filtres identiques et recommencer si les droits changent. Aucun webhook public de bilan n’est émis. Cette lecture est distincte de inspect_contact_quality, qui calcule des diagnostics bornés pour une sélection explicite.

Utiliser un code kpi exact renvoyé dans metrics.kpis ; omettre kpi pour tous les membres de la vue choisie. search recherche facultativement les noms actuels des contacts, sur 150 caractères au maximum. Les identifiants de contact suivent un ordre croissant. limit vaut 1–100, avec 25 par défaut. Seuls les noms actuels minimaux et les identifiants des contacts sont renvoyés. measuredTotal est la population datée autorisée du KPI. unavailable compte ses membres qui ne sont plus consultables actuellement, avant recherche. total compte les contacts actuellement consultables correspondant à la recherche ; la pagination ne renvoie que ces contacts, jamais les identifiants indisponibles. Relire les droits et données actuels avant une action du Studio.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "reportId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_.:-]{1,200}$"
  }
}
```

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "global",
      "local"
    ],
    "default": "global"
  }
}
```

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "all",
      "active"
    ],
    "default": "all"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  }
}
```

```json
{
  "name": "search",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "maxLength": 150
  }
}
```

```json
{
  "name": "kpi",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "pattern": "^[a-zA-Z0-9_:-]{1,100}$"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat préparé dans le périmètre actuellement autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportContactsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Filtres, limite, KPI ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope de contact manquant ou organisation incohérente.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Bilan indisponible dans cette organisation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Le périmètre de contacts du bilan a changé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Bilan préparé temporairement indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactQualityReportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contact-suggestions

Lire les suggestions de contacts justifiées

`list_contact_suggestions`

Utilisez cette liste pour préparer un échange avec un contact existant. La lire ne contacte personne et ne demande aucun nouveau calcul. Les contacts suggérés incluent les situations à vérifier ; la vue de vérification en est un sous-ensemble. Un score de 80 indique une priorité d’action, pas 80 % de chances de don. Le regroupement retient le plus haut score des motifs actifs ou à vérifier admissibles, sans addition. Les widgets ne montrent que les priorités actives d’au moins 60 : un widget vide peut donc coexister avec des situations à vérifier. Le traitement en arrière-plan prépare et enregistre le rapport quotidien à partir de 04:00 dans le fuseau de l’organisation. Ouvrir la page, changer les filtres et suivre l’état lisent uniquement les résultats enregistrés. Une demande explicite met un calcul en file pendant que le rapport précédent reste lisible. Les droits sur les sources restent vérifiés à chaque lecture.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

local désigne les contacts effectivement marqués comme locaux (stared===true), jamais leur proximité géographique ; global reste limité à l’organisation courante et aux droits de l’utilisateur. view=motif liste chaque motif ; contacts regroupe par personne avec la priorité active maximale, jamais leur somme. La priorité de 0 à 100 mesure le moment d’agir, pas une probabilité. review demande une vérification ; unavailable, expired, paused ou resolved ne prouvent pas qu’un échange a eu lieu. state=paused renvoie les configurations de pause, pas un calcul IA. Un motif commun peut utiliser les réglages privés de cet utilisateur : ne le redistribuez pas comme résultat général de l’organisation. Une lecture ne lance aucune analyse. Une couverture partielle, des contacts non calculés ou une tâche absente ne signifient pas zéro possibilité. new désigne une première détection dans les sept derniers jours. widget limite aux priorités actives >=60 et regroupe par contact. Les références sont opaques et ne donnent aucun droit d’accès. Si evidence.datePrecision=day, utilisez occurredOn comme date civile ; at peut être un instant technique à midi et ne donne pas l’heure exacte d’un échange.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Paramètres

```json
{
  "name": "population",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "local",
      "global"
    ],
    "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

```json
{
  "name": "volet",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "finance",
      "social"
    ],
    "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
  }
}
```

```json
{
  "name": "view",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "motif",
      "contacts"
    ]
  }
}
```

```json
{
  "name": "state",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "active",
      "review",
      "paused",
      "expired",
      "unavailable",
      "resolved",
      "all"
    ]
  }
}
```

```json
{
  "name": "scope",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "common",
      "personal"
    ],
    "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
  }
}
```

```json
{
  "name": "family",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "enum": [
      "recognition",
      "restart_support",
      "relevant_project",
      "lasting_support",
      "commitment",
      "obstacle",
      "welcome",
      "develop_link",
      "reconnect",
      "life_event",
      "support",
      "followup",
      "involvement",
      "acknowledge_help"
    ]
  }
}
```

```json
{
  "name": "q",
  "in": "query",
  "required": false,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

```json
{
  "name": "min",
  "in": "query",
  "required": false,
  "schema": {
    "type": "number",
    "minimum": 0,
    "maximum": 100
  }
}
```

```json
{
  "name": "new",
  "in": "query",
  "required": false,
  "schema": {
    "type": "boolean"
  }
}
```

```json
{
  "name": "widget",
  "in": "query",
  "required": false,
  "schema": {
    "type": "boolean"
  }
}
```

```json
{
  "name": "page",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100000
  }
}
```

```json
{
  "name": "size",
  "in": "query",
  "required": false,
  "schema": {
    "type": "integer",
    "enum": [
      3,
      20,
      50
    ]
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contact-suggestions/settings

Lire les consignes communes et personnelles des suggestions

`get_contact_suggestion_settings`

Lisez les contacts et les consignes actuellement utilisés par cette personne avant de proposer un réglage. Les consignes de l’équipe sont partagées ; les consignes personnelles restent privées. Chaque combinaison Finance/Social et équipe/personnel possède son propre texte. Les critères standards restent utilisés dans tous les modes. Un brouillon de consigne n’est pas forcément actif.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Réglages de l’utilisateur délégué courant uniquement. Les expressions internes des règles compilées et les contextes d’audit/modèles sont exclus ; active.text/version désignent la consigne active et draft/status l’interprétation en cours.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contact-suggestions/settings

Modifier les consignes communes ou personnelles des suggestions

`update_contact_suggestion_settings`

Décrivez une situation concrète, l’échange utile et les cas où attendre. Par exemple : proposer de remercier après un premier soutien, mais vérifier d’abord les échanges récents. Enregistrer demande à l’IA d’interpréter le texte ; cela ne l’active pas immédiatement et n’envoie aucun message. La version active précédente reste utilisée jusqu’à l’acceptation de la nouvelle interprétation. Expliquez avant l’enregistrement si vous modifiez les consignes privées de la personne ou celles de l’équipe.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Les consignes communes exigent le rôle natif ADMIN actuel ; les consignes personnelles n’affectent que l’utilisateur ayant consenti. revision est la valeur de concurrence optimiste lue par get_contact_suggestion_settings, ou 0 pour une entrée absente. En cas de conflit, relisez et réconciliez explicitement ; n’incrémentez jamais à l’aveugle. Le texte est interprété de manière asynchrone et peut consommer du budget IA ; interpreting ne signifie pas actif. Aucune injection de règle ou expression brute.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:configure",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
          },
          "text": {
            "type": "string",
            "maxLength": 10000
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          }
        },
        "required": [
          "volet",
          "scope",
          "text",
          "revision"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:configure",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contact-suggestions/preferences

Modifier les préférences de suggestions de l’utilisateur connecté

`update_contact_suggestion_preferences`

Choisissez les contacts et les consignes supplémentaires à utiliser. Combiner utilise celles de l’équipe et les consignes privées, prioritaires en cas de contradiction tout en restant privées. Communes seules utilise uniquement celles de l’équipe ; personnelles seules utilise uniquement les consignes privées. Ces choix ne désactivent jamais les critères standards et ne rendent jamais public un texte privé. Changer de mode demande une analyse ; les nouveaux résultats ne sont pas forcément prêts immédiatement.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

La population et le mode de chaque volet appartiennent uniquement à cet utilisateur. volet et mode doivent apparaître ensemble. Un changement de mode met une analyse en attente, sans recalcul immédiat. Cette commande exige aussi contact_suggestions:analyse.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:configure",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ]
}
```

### Corps de la requête

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

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSettingsResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:configure",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /contact-suggestions/analyses

Demander une analyse des suggestions de contacts

`request_contact_suggestion_analysis`

Demandez une actualisation lorsque c’est utile. Elle peut utiliser le budget IA de l’organisation et prendre du temps. Queued signifie en attente, running en cours et completed que la tâche est terminée, éventuellement avec des manques. Vérifiez la couverture avant d’affirmer que tous les contacts ont été analysés. Une analyse inchangée et encore valable peut être réutilisée : une nouvelle demande ne garantit donc pas un score différent.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Met en attente une analyse native pour l’utilisateur ayant consenti, soumise à la déduplication, aux limites de fréquence, aux budgets et à la disponibilité du worker natifs. Peut consommer du budget IA. queued/running ne signifie pas terminé et ne garantit pas que le worker est activé. Ne démarre aucun worker et n’appelle aucun modèle dans la requête HTTP. Des demandes équivalentes répétées peuvent renvoyer la même tâche : conservez son ID et consultez son état avec la permission de lecture.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:analyse",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social",
              "both"
            ]
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "required": [
          "population",
          "volet"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:analyse",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /contact-suggestions/analyses/{id}

Lire l’état d’une analyse de l’utilisateur connecté

`get_contact_suggestion_analysis`

Utilisez l’identifiant de la tâche existante pour expliquer si le calcul demandé attend, est en cours ou est terminé. Ne créez pas une nouvelle tâche pour vérifier son avancement. Une tâche terminée peut contenir des contacts qui n’ont pas pu être analysés.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Uniquement les tâches de l’utilisateur ayant consenti dans cette organisation. Une tâche terminée peut conserver des contacts en échec : examinez failed et la couverture de la liste. L’identité d’une tâche ne donne aucun accès aux résultats d’un autre utilisateur.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionJobResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contact-suggestions/sources/{collection}/{id}

Lire une source citée dans une suggestion de contact

`get_contact_suggestion_source`

Lisez le contenu actuel d’une source citée dans une suggestion enregistrée. Utilisez la collection, l’identifiant de source et le contact renvoyés par la suggestion. Cette lecture vérifie les droits actuels, sans lancer d’analyse ni envoyer de message. La source peut différer de l’extrait enregistré à la date analyzedAt.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Paramètres

```json
{
  "name": "collection",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "enum": [
      "contact",
      "contact_activity",
      "paiements",
      "abonnements",
      "dettes_v2",
      "forms_submit",
      "rappel",
      "custom_rappels",
      "forms",
      "caisses",
      "campagnes"
    ]
  }
}
```

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionSourceResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contact-suggestions/pauses

Mettre en pause des motifs de suggestions de contacts

`pause_contact_suggestions`

Masquez temporairement les motifs choisis, sans les déclarer résolus. Expliquez avant la pause qui est concerné et pour combien de temps : une pause commune vaut pour l’équipe ; une pause privée ne vaut que pour cet utilisateur. Finance et Social sont indépendants : une pause Sociale ne doit pas masquer Finance. Une pause par contact couvre aussi ses nouveaux motifs correspondants ; une liste explicite de motifs ne couvre que ceux-ci. La personne choisit 7 jours, 30 jours ou une date dans le fuseau de l’organisation ; la page présélectionne 7 jours, mais un appel API doit faire ce choix explicitement.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Une pause personnelle est privée ; common/mixed exige aussi le droit natif contact.edit et affecte l’équipe. volets liste finance/social ; sans motifs, tous les motifs du contact dans les volets et portées sélectionnés sont mis en pause. Fournissez exactement days (7 ou 30) ou date (YYYY-MM-DD, jusqu’à la fin de ce jour local). Le fuseau de l’organisation côté serveur fait référence. operationKey est l’UUID client d’une intention exacte : conservez-le lors des reprises. partial=true avec des étapes failed ne signifie jamais que tout est enregistré. Une pause ne résout aucune interaction et n’envoie aucun message au contact.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:pause",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "operationKey": {
            "type": "string",
            "format": "uuid"
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "volets": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "finance",
                "social"
              ],
              "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
            }
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal",
              "mixed"
            ]
          },
          "motifs": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 160
            }
          },
          "days": {
            "type": "integer",
            "enum": [
              7,
              30
            ]
          },
          "date": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "operationKey",
          "contact",
          "volets",
          "scope"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "required": [
              "days"
            ],
            "not": {
              "required": [
                "date"
              ]
            }
          },
          {
            "required": [
              "date"
            ],
            "not": {
              "required": [
                "days"
              ]
            }
          }
        ]
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionPauseResultResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:pause",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /contact-suggestions/pauses/{id}/resume

Réactiver une pause de suggestions de contacts

`resume_contact_suggestion_pause`

Levez la pause choisie avant son terme et demandez une nouvelle analyse. Cela ne prouve pas à lui seul qu’une nouvelle suggestion est prête ni qu’un échange a eu lieu. Vérifiez le résultat courant après le calcul.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Une pause personnelle appartient à l’utilisateur ayant consenti ; une pause commune exige aussi le droit natif contact.edit. Met une analyse à jour en attente et exige aussi contact_suggestions:analyse ; expiration/réactivation ne prouve pas que les nouveaux résultats sont prêts. Aucun message au contact. Relisez l’état courant après une réponse incertaine avant toute reprise.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:pause",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ]
}
```

### Paramètres

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionResumeResultResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:pause",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read",
    "contact_suggestions:analyse"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /contact-suggestions/interactions/{key}

Vérifier le reçu d’une interaction liée aux suggestions

`get_contact_suggestion_interaction`

Vérifiez si cette commande précise d’enregistrement d’échange possède déjà un reçu. Cette opération lit un état : elle ne peut pas enregistrer un échange. Dans la page, une personne note un échange réel avec Ajouter une interaction et choisit les sujets abordés. N’inventez pas une action d’écriture MCP équivalente et ne traitez pas une pause comme la preuve d’un échange.

Connexion OAuth avec consentement utilisateur dédié obligatoire. Les clés manuelles, les jetons root/système et les anciens accords OAuth sans ce consentement sont refusés. Ne fournissez jamais actor, owner ou organisation : le serveur relie l’utilisateur authentifié ayant consenti à cette organisation et cette application. Toutes les permissions de lecture des sources sont requises : contacts:read, paiements:read, abonnements:read, promesses:read, forms_submit:read, forms:read, caisses:read, fundraising:read. Les droits actuels de l’utilisateur, ses attributions, catégories, pôles et associations restent déterminants. Seuls les contacts ni supprimés, ni archivés, ni marqués décédés, actuellement admis par le moteur, sont considérés. Les permissions API n’accordent aucun droit natif supplémentaire. Les identifiants limités à certaines campagnes sont refusés. Le consentement, le jeton, les permissions et les droits natifs sont revérifiés avant entrée et publication ; une révocation ne peut annuler une commande déjà admise. Seules les contributions personnelles de cet utilisateur et les suggestions communes actuellement autorisées sont accessibles. Les prompts, contextes exacts des modèles, journaux d’audit, caches et données chiffrées ne sont jamais renvoyés. Le résultat est une observation, pas un instantané transactionnel ni une prédiction de don. Les champs inconnus ou supplémentaires et les entrées mal formées sont refusés. 

Lit uniquement un reçu d’interaction canonique déjà existant de l’utilisateur ayant consenti, pour le contact sélectionné et la clé d’opération exacte. Ne crée aucune interaction et ne répare aucun lien. recorded=false signifie l’absence actuelle de ce reçu, pas la preuve qu’aucun échange n’a eu lieu.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contact_suggestions:read",
  "additional": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ]
}
```

### Paramètres

```json
{
  "name": "key",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 160
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat de l’opération pour l’utilisateur autorisé.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionInteractionResultResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Entrée refusée, consentement ou droits actuels manquants, conflit ou service indisponible. Aucune relance automatique après une commande incertaine.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactSuggestionError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contact_suggestions:read",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "paiements:read",
    "abonnements:read",
    "promesses:read",
    "forms_submit:read",
    "forms:read",
    "caisses:read",
    "fundraising:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PUT /contacts/external-identifiers

Rattacher un identifiant de système externe à un contact résolu

`attach_contact_external_identifier`

Les identifiants externes de contacts sont des namespaces explicites organisation/system gérés par l’API d’intégrations, sans champ canonique de contact, nom de ressource Google, identifiant fiscal, rapprochement d’identité ni lien de compte. system est un namespace en minuscules (2–64 caractères, a-z puis a-z/0-9/._-) ; externalId est une chaîne exacte sensible à la casse (1–200 caractères), sans espace extérieur ni caractère de contrôle, sans normalisation. Une paire (organisation,system,externalId) référence au maximum un contact. Les namespaces sont partagés par les clés autorisées de l’organisation : utiliser son système légitime, sans sonder d’autres systèmes. Les IDs de clé auteur et identifiants de base restent privés. Chaque contact lié doit être un UUID scalaire exact actuel, non supprimé, dans cette organisation ; une archive reste lisible. Lectures et vérifications de cible sont bornées à 10000 ms chacune ; 503 demande une sélection plus petite ou une reprise vérifiée ultérieure, jamais une réattribution supposée réussie. Propriétés query/body inconnues, filtres arbitraires et mauvais types sont refusés. Aucun prestataire, synchronisation Google, fusion, upsert canonique d’ID externe, changement de contact, producteur de webhook, paiement métier ni facturation n’est déclenché ; l’authentification peut actualiser la télémétrie de la clé. Nécessite contacts:write AND contacts:read. Fournir le contactId déjà résolu ; aucune création ou déduplication de contact. Le premier rattachement réussi retourne created:true. Une répétition namespace/identifiant/contact identique retourne created:false sans changer le mapping. Une autre cible pour un identifiant existant donne 409 CONTACT_EXTERNAL_ID_CONFLICT ; ne pas réessayer avec une fiche devinée ni écraser. La clé unique déterministe arbitre les demandes concurrentes. Seul un enregistrement de mapping est inséré ; aucun champ de contact ni index de base n’est modifié ou créé, sans migration nécessaire pour l’unicité. Admission du contact et insertion sont distinctes : une suppression concurrente peut rendre un mapping acquitté indisponible ensuite. Une insertion acquittée retourne son résultat connu sans relecture accessoire risquée. Après un timeout incertain, rechercher le même identifiant exact et comparer contactId avant d’envisager une répétition identique ; conflit ou indisponibilité n’autorise aucune réattribution. La création du mapping exige explicitement writeConcern majority+j:true, acknowledged===true et insertedId déterministe exact avant succès. Un acquittement absent/incohérent donne CONTACT_EXTERNAL_ID_RESULT_UNCONFIRMED, sans seconde insertion automatique. La relecture du mapping utilise readConcern majority. Avant une nouvelle insertion, la garde passive contrôle le contact exact contre les travaux de cycle de vie/référence non résolus. Un mapping identique déjà enregistré est relu avant cette garde. CONTACT_MUTATION_BLOCKED renvoie 409 sans insertion ; CONTACT_MUTATION_FENCE_UNAVAILABLE renvoie 503 sans insertion. Ne pas changer de cible ou namespace pour contourner l’incertitude.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "system",
          "externalId",
          "contactId"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat qualifié du mapping d’identifiant externe.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdAttachResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Namespace, identifiant, UUID de contact ou enveloppe de requête invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scopes de contact requis manquants ou contexte d’organisation incohérent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Le contact choisi pour le rattachement est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "L’identifiant est déjà rattaché à un autre contact, ou un mapping existant est mal formé. Aucun écrasement.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une identité historique mal formée ou ambiguë empêche une résolution qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "L’opération n’a pas terminé ; vérifier par lookup avant de réessayer un rattachement incertain.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:write",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## POST /contacts/external-identifiers/lookup

Résoudre un lot borné d’identifiants externes vers les contacts actuels

`lookup_contact_external_identifiers`

Les identifiants externes de contacts sont des namespaces explicites organisation/system gérés par l’API d’intégrations, sans champ canonique de contact, nom de ressource Google, identifiant fiscal, rapprochement d’identité ni lien de compte. system est un namespace en minuscules (2–64 caractères, a-z puis a-z/0-9/._-) ; externalId est une chaîne exacte sensible à la casse (1–200 caractères), sans espace extérieur ni caractère de contrôle, sans normalisation. Une paire (organisation,system,externalId) référence au maximum un contact. Les namespaces sont partagés par les clés autorisées de l’organisation : utiliser son système légitime, sans sonder d’autres systèmes. Les IDs de clé auteur et identifiants de base restent privés. Chaque contact lié doit être un UUID scalaire exact actuel, non supprimé, dans cette organisation ; une archive reste lisible. Lectures et vérifications de cible sont bornées à 10000 ms chacune ; 503 demande une sélection plus petite ou une reprise vérifiée ultérieure, jamais une réattribution supposée réussie. Propriétés query/body inconnues, filtres arbitraires et mauvais types sont refusés. Aucun prestataire, synchronisation Google, fusion, upsert canonique d’ID externe, changement de contact, producteur de webhook, paiement métier ni facturation n’est déclenché ; l’authentification peut actualiser la télémétrie de la clé. Nécessite contacts:read. Fournir 1–200 externalIds exacts distincts dans un seul namespace system. L’ordre d’entrée est conservé. RESOLVED signifie qu’un mapping d’intégration réadmis référence actuellement une fiche réadmise de cette organisation ; seuls son UUID et la date connue de création du mapping sont retournés. UNRESOLVED avec contactId:null peut signifier absence de mapping, mapping mal formé ou cible absente/supprimée/étrangère/indisponible ; cela ne prouve ni absence globale, ni suppression ni fusion. Ne jamais suivre un ancien mergedInto ni inférer une fiche conservée. Les dates invalides restent null. Les lectures mapping/cible ne sont pas un instantané cohérent, donc consistentSnapshot:false. Aucune recherche arbitraire entre systèmes, rapprochement approximatif, création automatique, réattribution ou prise de contrôle de namespace. La création du mapping exige explicitement writeConcern majority+j:true, acknowledged===true et insertedId déterministe exact avant succès. Un acquittement absent/incohérent donne CONTACT_EXTERNAL_ID_RESULT_UNCONFIRMED, sans seconde insertion automatique. La relecture du mapping utilise readConcern majority.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "externalIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
            }
          }
        },
        "required": [
          "system",
          "externalIds"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat qualifié du mapping d’identifiant externe.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdLookupResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Namespace, identifiant, UUID de contact ou enveloppe de requête invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scopes de contact requis manquants ou contexte d’organisation incohérent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Le contact choisi pour le rattachement est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "L’identifiant est déjà rattaché à un autre contact, ou un mapping existant est mal formé. Aucun écrasement.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une identité historique mal formée ou ambiguë empêche une résolution qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "L’opération n’a pas terminé ; vérifier par lookup avant de réessayer un rattachement incertain.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExternalIdError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/exports

Lire une sélection de colonnes de contacts en export paginé

`export_contacts`

Nécessite contacts:read. Export JSON en lecture seule de 1–2000 UUID distincts de contacts actuels, résolus dans l’organisation authentifiée avant pagination ; toute fiche indisponible/supprimée/étrangère refuse la sélection entière avec 404 CONTACT_EXPORT_SELECTION_UNAVAILABLE. Résoudre d’abord une sélection légitime par search_contacts_advanced et ses catalogues ; ne pas énumérer des contacts sans rapport. Les archives explicitement sélectionnées restent exportables, sans action d’archivage/restauration ni inférence d’adhésion actuelle. Choisir 1–40 champs standards dans l’enum d’entrée et, éventuellement, des paires exactes customFields clé/type, au maximum 40 colonnes au total. Les paires viennent de list_contact_custom_fields ; les valeurs absentes, inconnues ou mal formées restent null, jamais une chaîne vide, false, zéro ou date inventée. Les entrées personnalisées historiques multiples sous une même paire produisent un tableau de valeurs natives, y compris null pour les entrées invalides, sans écrasement ni concaténation arbitraire. TEXT reste texte ; NUMBER conserve des nombres finis dans leur unité native sans inférence de devise ; BOOL conserve le sens natif/historique Oui/Non ; DATE est une date civile UTC ISO et DATETIME un instant ISO explicite. Gender vaut M/F seulement si enregistré, sinon null. Coordonnées secondaires et catégories sont des tableaux sans séparateur implicite. L’adresse postale principale peut être choisie, mais pas les codes d’accès, notes privées, identifiants fiscaux, totaux de paiement, tokens ou instruments réutilisables. Les projections arbitraires, chemins de base, expressions et propriétés query/body inconnues sont refusés. Seules les colonnes sélectionnées, contactId et cellules ordonnées columnId/value sont livrés. Conserver les vrais IDs ; les colonnes ne prouvent ni règlement bancaire, ni consentement, ni statut de compte. limit 1–100, défaut 50. Le curseur opaque suit ID_ASC binaire fixe et dépend de l’organisation, clé, scopes, IDs et colonnes exacts ; poursuivre avec la même sélection jusqu’à hasMore:false. readAt date l’observation ; les modifications concurrentes restent possibles entre admission et page, donc consistentSnapshot:false. Ce n’est pas un flux chronologique de changements, suppressions ou fusions, et une absence n’autorise aucune suppression ailleurs. Requêtes limitées à 10000 ms ; 503 CONTACT_EXPORT_LIMIT_REACHED demande une sélection plus petite. 422 CONTACT_EXPORT_INVALID_SOURCE/CONTACT_EXPORT_AMBIGUOUS_ID signale une identité incohérente, jamais une autorisation d’inventer ou fusionner une personne. Aucun fichier conservé, appel prestataire/géocodeur, écriture métier, synchronisation, facturation ni livraison de téléchargement ; l’authentification peut actualiser la télémétrie de la clé. La sortie MCP dispose d’un quota explicite de 50000 nœuds JSON et 16 MiB, profondeur 40 inchangée ; l’export réel de 100 lignes/40 colonnes scalaires est qualifié sous cette borne. Des tableaux volumineux de coordonnées secondaires, tags ou valeurs personnalisées répétées peuvent encore la dépasser. Aucune page partielle n’est publiée après un dépassement ; réduire la taille de page ou les colonnes en préservant la sélection légitime de contacts.

### 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/UnisoftRequest_4f53ab7a631d002ee822"
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée des colonnes explicitement sélectionnées de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Sélection, champ, type, limite ou curseur invalide ou inconnu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "contacts:read manquant ou contexte d’organisation incohérent.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Au moins un contact sélectionné est indisponible ; aucune sélection partielle n’est renvoyée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une identité historique mal formée ou dupliquée empêche un export qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La requête d’export bornée n’a pas terminé. Réduire la sélection.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactExportError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp-output-limits": {
    "maxNodes": 50000,
    "maxBytes": 16777216
  },
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/search-advanced

Rechercher des contacts par liste calculée, pôle vivant, catégorie, champ typé et marqueurs

`search_contacts_advanced`

Recherche structurée en lecture seule dans l’organisation authentifiée, avec contacts:read. Elle est distincte de search_contacts (recherche email/téléphone de zéro ou une fiche) et list_contacts (liste simple historique). Les filtres s’intersectent ; tags/listIds emploient any par défaut, all exige toutes les valeurs et none les exclut toutes. tags contient des chaînes exactes observées, avec leur # ; ce ne sont pas des UUID et elles ne sont jamais normalisées silencieusement. listIds contient les identifiants opaques des listes calculées, tels que form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID>, fundraising:<UUID> ; les UUID sources seuls sont invalides. Sources actuelles, organisation, génération active, complétude et relations de chaque appartenance sont réadmises avant utilisation. Ces listes calculées décrivent des participations/contributions ; elles ne sont ni des listes manuelles éditables ni une preuve de consentement actuel, règlement bancaire ou appartenance à un compte. Scopes conditionnels nécessaires : form/product= forms:read AND forms_submit:read ; cagnotte= caisses:read AND paiements:read ; event= events:read AND forms:read AND forms_submit:read AND caisses:read AND paiements:read ; fundraising= fundraising:read AND paiements:read AND abonnements:read AND promesses:read. La restriction de campagne de la clé s’applique à chaque source fundraising. poleIds exige les scopes event et utilise les rattachements vivants depuis inscriptions/paiements/catégories sans réparer la projection ; les clés restreintes par campagne ne peuvent pas utiliser poleIds (403 CONTACT_POLE_CAMPAIGN_SCOPE_UNSUPPORTED). Les UUID de pôles sélectionnent l’un des pôles ; null est le pôle principal. archived/deceased/isNew sont des marqueurs enregistrés indépendants, jamais un statut global inventé. Les archives sont exclues sauf avec archived:true ; deceased et new restent libres si omis. false signifie non marqué true et inclut les anciens marqueurs absents, renvoyés null. customFields exige la paire exacte clé/type observée ; les valeurs TEXT doivent exister dans cette paire, avec casse/accents exacts ; BOOL accepte les booléens natifs et le format propriétaire Oui/Non ; NUMBER utilise des bornes JSON numériques finies dans l’unité native du champ sans inférence de devise ; DATE couvre des jours UTC inclusifs ; DATETIME inclut from et exclut to avec fuseau explicite. Chaque filtre numérique/date exige au moins une borne ; les doublons clé/type, dates/types invalides et champs/valeurs inconnus sont refusés. Les nombres/dates enregistrés sous TEXT ou d’un type non pris en charge ne sont pas convertis. Au maximum 10 filtres personnalisés, 20 valeurs par ensemble, limit 1–100 (défaut 50). Les résultats sont des résumés minimaux, avec null pour les valeurs inconnues, sans notes privées, documents, codes d’accès d’adresse, tokens ni instruments de paiement. Le curseur opaque suit ID_ASC binaire fixe et dépend de l’organisation, la clé, ses scopes, les filtres et la génération active ; le réutiliser avec les mêmes filtres. Une nouvelle génération impose de repartir sans curseur. readAt date l’observation ; listComputedAt date seulement la dernière réussite connue de la projection active. Des changements concurrents restent possibles : ce n’est ni un instantané cohérent ni un flux fiable de changements/suppressions/fusions. Aucun import, fusion, synchronisation, écriture métier, appel prestataire ni facturation n’a lieu ; l’authentification peut actualiser la télémétrie de la clé. Les paramètres query/body inconnus, mauvais types et conditions Mongo arbitraires sont refusés. 403 INSUFFICIENT_SCOPE impose d’arrêter cette sélection, sans contourner par une autre source. 404 CONTACT_LIST_UNAVAILABLE/CONTACT_TAG_UNAVAILABLE/CONTACT_FIELD_UNAVAILABLE/CONTACT_POLE_UNAVAILABLE demande une valeur exacte actuellement disponible dans le catalogue. 409 CONTACT_LIST_NOT_READY ou CONTACT_LIST_HISTORY_INCOMPLETE exige la complétion de projection/historique par le propriétaire produit ordinaire, sans réessai aveugle. Les lectures propriétaires sont limitées à 20000 lignes et chaque requête à 10000 ms : 422 CONTACT_SEARCH_SOURCE_LIMIT ou 503 CONTACT_SEARCH_LIMIT_REACHED demande une sélection plus étroite ; aucune page tronquée n’est livrée. 422 CONTACT_SEARCH_INVALID_SOURCE/CONTACT_SEARCH_AMBIGUOUS_ID signale une identité historique incohérente, jamais une autorisation d’inventer ou fusionner une personne. INVALID_CONTACT_SEARCH_CURSOR demande de recommencer cette sélection ; l’absence d’un résultat n’autorise pas sa suppression ailleurs.

### Authentification

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

### Permissions requises

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

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/UnisoftRequest_169b8464c56f9629f796"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de résumés de contacts autorisés.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Entrée, type, plage de champ, identifiant de liste ou curseur invalide ou inconnu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Scope contact/source manquant, organisation invalide ou restriction de campagne non prise en charge pour les pôles.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Une source/liste/pôle/catégorie/champ sélectionné est indisponible dans cette organisation et ce périmètre.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "La projection de listes calculées n’est pas prête ou son historique d’appartenance est incomplet.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "La taille source, une identité historique mal formée ou un identifiant logique dupliqué empêche une page qualifiée.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture propriétaire bornée n’a pas pu terminer. Réduire la sélection avant de réessayer.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactDiscoveryError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "filters.listIds contains a form: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a product: list",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a cagnotte: list",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a event: list",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.listIds contains a fundraising: list",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    },
    {
      "condition": "filters.poleIds is present",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/tags

Lire les catégories exactes observées des contacts

`list_contact_tags`

Nécessite contacts:read. Métadonnées autorisées en lecture seule dans l’organisation authentifiée. Aucun changement de contact, reconstruction de liste, synchronisation, appel prestataire ni facturation ; l’authentification peut actualiser la télémétrie de la clé. Les paramètres query inconnus/répétés, types invalides et tout corps HTTP non vide sont refusés. Pagination binaire croissante par valeur exacte (clé/type pour les champs, ID pour listes/pôles), limit 1–100, défaut 50. Le curseur dépend de cette organisation, clé, scopes/restriction, catalogue et sélection, dont la génération active des listes. readAt date l’observation, sans instantané cohérent. Requêtes limitées à 10000 ms ; sources propriétaires des listes/pôles limitées à 20000 lignes, avec 422 au dépassement sans catalogue tronqué. 503 CONTACT_CATALOG_LIMIT_REACHED demande une sélection légitime plus petite ; un curseur invalide demande une première page neuve. Ne jamais retirer un filtre d’autorisation ni sonder une autre organisation pour contourner le refus. Retourne les chaînes valides de catégories observées sur les contacts non supprimés, archives comprises. Conserver casse, accents et # initial ; ce sont des libellés, pas des UUID. Ce n’est ni une enum configurée, ni un consentement, ni un statut de donateur, ni une garantie de présence lors d’une recherche ultérieure. Aucune catégorie de RDV historique ni configuration privée de personnel n’est lue. Employer le tag exact dans search_contacts_advanced ou une modification autorisée de catégorie.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille maximale de page, 1–100 ; défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque du même catalogue, organisation, clé, scopes et sélection. Une nouvelle génération active de listes impose de repartir sans curseur."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de métadonnées autorisées de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogTagResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Requête de catalogue ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contact/source manquants ou restriction de campagne non prise en charge pour les pôles.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "La génération de listes calculées n’est pas prête.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une borne source ou des métadonnées historiques incohérentes empêchent un résultat qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée du catalogue est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/custom-fields

Découvrir les clés et types natifs de champs personnalisés enregistrés

`list_contact_custom_fields`

Nécessite contacts:read. Métadonnées autorisées en lecture seule dans l’organisation authentifiée. Aucun changement de contact, reconstruction de liste, synchronisation, appel prestataire ni facturation ; l’authentification peut actualiser la télémétrie de la clé. Les paramètres query inconnus/répétés, types invalides et tout corps HTTP non vide sont refusés. Pagination binaire croissante par valeur exacte (clé/type pour les champs, ID pour listes/pôles), limit 1–100, défaut 50. Le curseur dépend de cette organisation, clé, scopes/restriction, catalogue et sélection, dont la génération active des listes. readAt date l’observation, sans instantané cohérent. Requêtes limitées à 10000 ms ; sources propriétaires des listes/pôles limitées à 20000 lignes, avec 422 au dépassement sans catalogue tronqué. 503 CONTACT_CATALOG_LIMIT_REACHED demande une sélection légitime plus petite ; un curseur invalide demande une première page neuve. Ne jamais retirer un filtre d’autorisation ni sonder une autre organisation pour contourner le refus. Retourne les paires exactes observées (key,type) avec au moins une valeur native prise en charge sur un contact non supprimé. Une clé peut porter plusieurs types ; conserver la paire. TEXT propose any/all/none, BOOL value, NUMBER min/max en unité native inconnue, DATE/DATETIME from/to. DATE couvre des jours UTC inclusifs ; DATETIME inclut le début et exclut la fin avec fuseau explicite. NUMBER n’est pas un montant en devise. hasObservedValues:true permet d’énumérer les observations TEXT par list_contact_custom_field_values, sans enum éditable. Les nombres/dates stockés en TEXT ne deviennent pas des champs numériques/date. Aucune conversion ni inférence ; les champs dont toutes les valeurs sont mal formées, vides ou non prises en charge sont omis.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille maximale de page, 1–100 ; défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque du même catalogue, organisation, clé, scopes et sélection. Une nouvelle génération active de listes impose de repartir sans curseur."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de métadonnées autorisées de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogFieldResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Requête de catalogue ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contact/source manquants ou restriction de campagne non prise en charge pour les pôles.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "La génération de listes calculées n’est pas prête.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une borne source ou des métadonnées historiques incohérentes empêchent un résultat qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée du catalogue est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/custom-fields/values

Lire les valeurs textuelles observées pour un champ exact de contact

`list_contact_custom_field_values`

Nécessite contacts:read. Métadonnées autorisées en lecture seule dans l’organisation authentifiée. Aucun changement de contact, reconstruction de liste, synchronisation, appel prestataire ni facturation ; l’authentification peut actualiser la télémétrie de la clé. Les paramètres query inconnus/répétés, types invalides et tout corps HTTP non vide sont refusés. Pagination binaire croissante par valeur exacte (clé/type pour les champs, ID pour listes/pôles), limit 1–100, défaut 50. Le curseur dépend de cette organisation, clé, scopes/restriction, catalogue et sélection, dont la génération active des listes. readAt date l’observation, sans instantané cohérent. Requêtes limitées à 10000 ms ; sources propriétaires des listes/pôles limitées à 20000 lignes, avec 422 au dépassement sans catalogue tronqué. 503 CONTACT_CATALOG_LIMIT_REACHED demande une sélection légitime plus petite ; un curseur invalide demande une première page neuve. Ne jamais retirer un filtre d’autorisation ni sonder une autre organisation pour contourner le refus. Nécessite key d’une paire TEXT de list_contact_custom_fields. Retourne les chaînes TEXT distinctes, exactes et non vides observées pour cette clé ; jamais des règles de valeurs autorisées configurées. Casse/accents sont conservés. Une chaîne ressemblant à un nombre reste du texte. Un résultat vide peut signaler aucune valeur prise en charge actuelle ou une clé indisponible ; il ne prouve pas que le champ n’a jamais existé. N’employer que les chaînes value renvoyées dans une recherche TEXT exacte. Le curseur dépend aussi de key.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille maximale de page, 1–100 ; défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque du même catalogue, organisation, clé, scopes et sélection. Une nouvelle génération active de listes impose de repartir sans curseur."
}
```

```json
{
  "name": "key",
  "in": "query",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 120
  },
  "description": "Clé exacte d’une paire TEXT du catalogue de champs autorisé ; pas un chemin de base."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de métadonnées autorisées de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogValueResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Requête de catalogue ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contact/source manquants ou restriction de campagne non prise en charge pour les pôles.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "La génération de listes calculées n’est pas prête.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une borne source ou des métadonnées historiques incohérentes empêchent un résultat qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée du catalogue est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/catalog/lists

Découvrir les identifiants autorisés des listes calculées de contacts

`list_contact_lists`

Nécessite contacts:read. Métadonnées autorisées en lecture seule dans l’organisation authentifiée. Aucun changement de contact, reconstruction de liste, synchronisation, appel prestataire ni facturation ; l’authentification peut actualiser la télémétrie de la clé. Les paramètres query inconnus/répétés, types invalides et tout corps HTTP non vide sont refusés. Pagination binaire croissante par valeur exacte (clé/type pour les champs, ID pour listes/pôles), limit 1–100, défaut 50. Le curseur dépend de cette organisation, clé, scopes/restriction, catalogue et sélection, dont la génération active des listes. readAt date l’observation, sans instantané cohérent. Requêtes limitées à 10000 ms ; sources propriétaires des listes/pôles limitées à 20000 lignes, avec 422 au dépassement sans catalogue tronqué. 503 CONTACT_CATALOG_LIMIT_REACHED demande une sélection légitime plus petite ; un curseur invalide demande une première page neuve. Ne jamais retirer un filtre d’autorisation ni sonder une autre organisation pour contourner le refus. Retourne seulement les listes calculées de génération active dont les sources actuelles et tous les droits sont accessibles. Les IDs sont form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID>, fundraising:<UUID> ; sourceId seul n’est pas un identifiant de liste. requiredScopes énumère les droits conditionnels réellement vérifiés par search_contacts_advanced. Form/product exige forms:read et forms_submit:read ; caisse caisses:read et paiements:read ; event tous ceux-ci et events:read ; fundraising fundraising:read, paiements:read, abonnements:read et promesses:read. Les restrictions de campagne, même vides, bornent les sources fundraising. Aucune liste événement/fundraising partielle n’est annoncée si un droit manque. historyIncomplete:true donne availableForSearch:false : arrêter et résoudre l’historique par le parcours propriétaire ordinaire. computedAt date seulement la dernière réussite connue de projection ; les listes sont des observations différées de participation/contribution, sans preuve de règlement bancaire, consentement ni approbation actuelle de compte. Les libellés inconnus restent null. Aucun compteur n’est inventé ; aucune reconstruction ni actualisation source n’est déclenchée.

### Authentification

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

### Permissions requises

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

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille maximale de page, 1–100 ; défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque du même catalogue, organisation, clé, scopes et sélection. Une nouvelle génération active de listes impose de repartir sans curseur."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de métadonnées autorisées de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Requête de catalogue ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contact/source manquants ou restriction de campagne non prise en charge pour les pôles.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "La génération de listes calculées n’est pas prête.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une borne source ou des métadonnées historiques incohérentes empêchent un résultat qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée du catalogue est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-conditional-scopes": [
    {
      "condition": "advertise form: lists",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise product: lists",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise cagnotte: lists",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise event: lists",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "advertise fundraising: lists",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ]
}
```

## GET /contacts/catalog/poles

Lire les identifiants actuels des pôles de contacts

`list_contact_poles`

Nécessite contacts:read. Métadonnées autorisées en lecture seule dans l’organisation authentifiée. Aucun changement de contact, reconstruction de liste, synchronisation, appel prestataire ni facturation ; l’authentification peut actualiser la télémétrie de la clé. Les paramètres query inconnus/répétés, types invalides et tout corps HTTP non vide sont refusés. Pagination binaire croissante par valeur exacte (clé/type pour les champs, ID pour listes/pôles), limit 1–100, défaut 50. Le curseur dépend de cette organisation, clé, scopes/restriction, catalogue et sélection, dont la génération active des listes. readAt date l’observation, sans instantané cohérent. Requêtes limitées à 10000 ms ; sources propriétaires des listes/pôles limitées à 20000 lignes, avec 422 au dépassement sans catalogue tronqué. 503 CONTACT_CATALOG_LIMIT_REACHED demande une sélection légitime plus petite ; un curseur invalide demande une première page neuve. Ne jamais retirer un filtre d’autorisation ni sonder une autre organisation pour contourner le refus. Nécessite contacts:read et events:read, forms:read, forms_submit:read, caisses:read, paiements:read, comme la recherche vivante. Les clés restreintes par campagne, même avec une liste vide, sont refusées. Retourne les UUID des pôles actuels et le principal avec id:null, main:true ; son libellé absent reste null. Ces identifiants servent à poleIds dans search_contacts_advanced, sans représenter une projection de rattachement des contacts ni une liste de droits du personnel. Aucun rattachement, configuration de catégories ou whitelist d’accès n’est retourné ou recalculé.

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:read",
  "additional": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ]
}
```

### Paramètres

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 50
  },
  "description": "Taille maximale de page, 1–100 ; défaut 50."
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 2000
  },
  "description": "Curseur opaque du même catalogue, organisation, clé, scopes et sélection. Une nouvelle génération active de listes impose de repartir sans curseur."
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Page bornée de métadonnées autorisées de contacts.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogPoleResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Requête de catalogue ou curseur invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Droits contact/source manquants ou restriction de campagne non prise en charge pour les pôles.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "La génération de listes calculées n’est pas prête.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "Une borne source ou des métadonnées historiques incohérentes empêchent un résultat qualifié.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "La lecture bornée du catalogue est indisponible.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactCatalogError"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:read",
  "x-unisoft-additional-scopes": [
    "events:read",
    "forms:read",
    "forms_submit:read",
    "caisses:read",
    "paiements:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /contacts/tag-commands/capabilities

Vérifier les capacités de gestion des tags de l’organisation

`get_contact_tag_command_capabilities`

Nécessite les autorisations explicitement attribuées contacts:manage-tags ET contacts:read ET contacts:write. Aucun droit par défaut. Toute clé limitée à des collectes est refusée avec CAMPAIGN_RESTRICTED_KEY. Ces droits autorisent la gestion des tags à l’échelle de l’organisation, y compris les fiches archivées/supprimées et les anciens rendez-vous enregistrés ; aucune API de rendez-vous n’est ouverte. Un tag est un libellé enregistré exact, jamais un UUID, un identifiant de liste, de pôle ou une clé de champ personnalisé. Tous les paramètres de requête sont interdits. Découvre la disponibilité de l’aperçu/application et la limite d’observation sans lire de données métier ni démarrer de commande. Aucun corps n’est accepté. La propagation native du CRM couvre les contacts, les anciens rendez-vous, les ensembles de tags partagés et les restrictions de pôles ; le renommage/la fusion modifie aussi les restrictions d’accès par catégorie. REMOVE conserve volontairement les restrictions d’accès par catégorie mais retire le libellé des restrictions de pôles : poleRestrictionsEmptied avertit lorsqu’un pôle perd son dernier filtre de catégorie, ce qui peut élargir l’accès à ce pôle. Les audiences de campagne, recherches enregistrées et générateurs automatiques de tags système restent inchangés : un tag système peut réapparaître lors d’une prochaine action métier. Aucun contact n’est supprimé. Il ne s’agit pas d’un snapshot global atomique : les writers internes ne sont pas verrouillés et l’intention à l’échelle de l’organisation peut inclure des fiches créées pendant la commande. Les compteurs et la révision décrivent uniquement les documents portant les tags observés, avec au plus 5000 documents par observation. Aucun prestataire n’est appelé. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Capacités disponibles pour les commandes de tags ; aucune mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandCapabilitiesResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou LIMITS_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND ou COMMAND_NOT_FOUND : utiliser un libellé exact existant ou l’UUID d’une commande autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE ou IDEMPOTENCY_CONFLICT : aucun nouvel appel du propriétaire ; revoir les données source, réduire l’opération ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun détail d’erreur privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission du résultat n’a pas pu être prouvée. Consulter l’état de la commande d’origine ; ne jamais inventer une nouvelle clé pour réessayer un effet incertain.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/tag-commands/preview

Prévisualiser le renommage, la fusion ou le retrait d’un tag à l’échelle de l’organisation

`preview_contact_tag_command`

Nécessite les autorisations explicitement attribuées contacts:manage-tags ET contacts:read ET contacts:write. Aucun droit par défaut. Toute clé limitée à des collectes est refusée avec CAMPAIGN_RESTRICTED_KEY. Ces droits autorisent la gestion des tags à l’échelle de l’organisation, y compris les fiches archivées/supprimées et les anciens rendez-vous enregistrés ; aucune API de rendez-vous n’est ouverte. Un tag est un libellé enregistré exact, jamais un UUID, un identifiant de liste, de pôle ou une clé de champ personnalisé. Tous les paramètres de requête sont interdits. Observation d’impact en lecture seule. Fournir action RENAME, MERGE ou REMOVE et sourceTag. RENAME exige targetTag et applique le formatage canonique du CRM (majuscules, accents retirés, espaces remplacés par des tirets bas) ; MERGE exige targetTag comme libellé exact d’un tag existant. REMOVE interdit targetTag. Le résultat fournit la commande canonique, une révision et les compteurs observés ; reprendre ces valeurs de commande et cette révision dans apply. accessRestrictions vaut null avec REMOVE, car ces restrictions sont conservées et ne sont pas parcourues. Aucune identité de contact ni configuration privée n’est retournée. L’absence de la source/cible de fusion renvoie 404. Une propriété scalaire, un tableau ou une référence de pôle parent invalide refuse l’aperçu entier. L’aperçu ne réserve aucune fiche et ne persiste jamais de commande. La propagation native du CRM couvre les contacts, les anciens rendez-vous, les ensembles de tags partagés et les restrictions de pôles ; le renommage/la fusion modifie aussi les restrictions d’accès par catégorie. REMOVE conserve volontairement les restrictions d’accès par catégorie mais retire le libellé des restrictions de pôles : poleRestrictionsEmptied avertit lorsqu’un pôle perd son dernier filtre de catégorie, ce qui peut élargir l’accès à ce pôle. Les audiences de campagne, recherches enregistrées et générateurs automatiques de tags système restent inchangés : un tag système peut réapparaître lors d’une prochaine action métier. Aucun contact n’est supprimé. Il ne s’agit pas d’un snapshot global atomique : les writers internes ne sont pas verrouillés et l’intention à l’échelle de l’organisation peut inclure des fiches créées pendant la commande. Les compteurs et la révision décrivent uniquement les documents portant les tags observés, avec au plus 5000 documents par observation. Aucun prestataire n’est appelé. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "RENAME",
              "MERGE",
              "REMOVE"
            ]
          },
          "sourceTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "targetTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          }
        },
        "required": [
          "action",
          "sourceTag"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Impact et révision observés ; aucune réservation de snapshot ni mutation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou LIMITS_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND ou COMMAND_NOT_FOUND : utiliser un libellé exact existant ou l’UUID d’une commande autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE ou IDEMPOTENCY_CONFLICT : aucun nouvel appel du propriétaire ; revoir les données source, réduire l’opération ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun détail d’erreur privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission du résultat n’a pas pu être prouvée. Consulter l’état de la commande d’origine ; ne jamais inventer une nouvelle clé pour réessayer un effet incertain.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /contacts/tag-commands/apply

Appliquer une commande de tag prévisualisée avec un reçu durable

`apply_contact_tag_command`

Nécessite les autorisations explicitement attribuées contacts:manage-tags ET contacts:read ET contacts:write. Aucun droit par défaut. Toute clé limitée à des collectes est refusée avec CAMPAIGN_RESTRICTED_KEY. Ces droits autorisent la gestion des tags à l’échelle de l’organisation, y compris les fiches archivées/supprimées et les anciens rendez-vous enregistrés ; aucune API de rendez-vous n’est ouverte. Un tag est un libellé enregistré exact, jamais un UUID, un identifiant de liste, de pôle ou une clé de champ personnalisé. Tous les paramètres de requête sont interdits. Obtenir d’abord un aperçu. Fournir ses valeurs canoniques action/sourceTag/targetTag, revision, une idempotencyKey stable de 8–128 caractères ASCII lettres/chiffres/._:- et acknowledgeLimits:true après avoir expliqué les limites. L’acquittement couvre les audiences enregistrées inchangées, l’élargissement possible de l’accès aux pôles et les ajouts concurrents à l’échelle de l’organisation ; ne pas annoncer une migration complète des références. Le serveur enregistre un reçu avant tout effet métier, sérialise les commandes externes de tags de l’organisation, valide chaque référence propriétaire observée et vérifie la révision à l’admission, puis appelle une seule fois le propriétaire canonique CRM. Une même clé/contenu retourne le reçu existant ; une commande/révision différente renvoie IDEMPOTENCY_CONFLICT. REJECTED signifie que cet appel n’a produit aucun effet métier ; consulter error, notamment REVISION_CONFLICT ou TAG_COMMAND_BUSY. ADMITTING/RUNNING indiquent une attente ou une interruption, jamais une preuve d’échec. COMPLETED signifie que le retrait de la source observée et la conservation de la cible sur les fiches d’origine ont été vérifiés ; ce n’est pas une garantie contre des écritures internes ultérieures. PARTIAL signifie que la vérification a trouvé des fiches d’origine manquantes/non terminées ; UNKNOWN signifie qu’un effet ou sa vérification n’a pas pu être prouvé. Les deux états conservent le verrou externe de l’organisation dans l’attente d’une revue. canRetry vaut toujours false. Ne jamais réessayer une commande incertaine/partielle avec une nouvelle clé ni la simuler par des boucles sur les contacts ; consulter get_contact_tag_command et demander une revue via le parcours Unisoft autorisé. Aucune récupération automatique ni reprise d’un verrou ancien n’existe. HTTP 200 avec success:true confirme uniquement le stockage d’un reçu, y compris REJECTED ; consulter data.state avant d’annoncer une mutation. La propagation native du CRM couvre les contacts, les anciens rendez-vous, les ensembles de tags partagés et les restrictions de pôles ; le renommage/la fusion modifie aussi les restrictions d’accès par catégorie. REMOVE conserve volontairement les restrictions d’accès par catégorie mais retire le libellé des restrictions de pôles : poleRestrictionsEmptied avertit lorsqu’un pôle perd son dernier filtre de catégorie, ce qui peut élargir l’accès à ce pôle. Les audiences de campagne, recherches enregistrées et générateurs automatiques de tags système restent inchangés : un tag système peut réapparaître lors d’une prochaine action métier. Aucun contact n’est supprimé. Il ne s’agit pas d’un snapshot global atomique : les writers internes ne sont pas verrouillés et l’intention à l’échelle de l’organisation peut inclure des fiches créées pendant la commande. Les compteurs et la révision décrivent uniquement les documents portant les tags observés, avec au plus 5000 documents par observation. Aucun prestataire n’est appelé. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Corps de la requête

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "RENAME",
              "MERGE",
              "REMOVE"
            ]
          },
          "sourceTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "targetTag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          },
          "acknowledgeLimits": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "action",
          "sourceTag",
          "revision",
          "idempotencyKey",
          "acknowledgeLimits"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Résultat COMPLETED, REJECTED, PARTIAL ou UNKNOWN enregistré ; consulter state avant d’annoncer un effet.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandReceiptResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "La commande existante est ADMITTING ou RUNNING ; aucun nouvel appel du propriétaire n’a eu lieu.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou LIMITS_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND ou COMMAND_NOT_FOUND : utiliser un libellé exact existant ou l’UUID d’une commande autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE ou IDEMPOTENCY_CONFLICT : aucun nouvel appel du propriétaire ; revoir les données source, réduire l’opération ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun détail d’erreur privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission du résultat n’a pas pu être prouvée. Consulter l’état de la commande d’origine ; ne jamais inventer une nouvelle clé pour réessayer un effet incertain.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /contacts/tag-commands/{commandId}

Consulter l’état durable d’une commande de tag de l’organisation

`get_contact_tag_command`

Nécessite les autorisations explicitement attribuées contacts:manage-tags ET contacts:read ET contacts:write. Aucun droit par défaut. Toute clé limitée à des collectes est refusée avec CAMPAIGN_RESTRICTED_KEY. Ces droits autorisent la gestion des tags à l’échelle de l’organisation, y compris les fiches archivées/supprimées et les anciens rendez-vous enregistrés ; aucune API de rendez-vous n’est ouverte. Un tag est un libellé enregistré exact, jamais un UUID, un identifiant de liste, de pôle ou une clé de champ personnalisé. Tous les paramètres de requête sont interdits. Lecture uniquement par commandId UUID retourné par apply. Les trois autorisations et l’organisation courante sont vérifiées de nouveau ; les références et anciens reçus n’accordent aucun droit. Aucun corps n’est accepté. Retourne la dernière phase et le dernier état durables sans appeler le propriétaire, réessayer ni récupérer un verrou. ADMITTING/RUNNING peuvent décrire un appel en cours ou interrompu ; son ancienneté ne prouve pas l’échec. PARTIAL et UNKNOWN conservent le verrou externe dans l’attente d’une revue autorisée et n’autorisent jamais un nouvel essai avec une autre clé. Un 404 prouve uniquement qu’aucun reçu accessible n’a été lu, pas qu’un autre POST a échoué. canRetry:false dans tous les états. La propagation native du CRM couvre les contacts, les anciens rendez-vous, les ensembles de tags partagés et les restrictions de pôles ; le renommage/la fusion modifie aussi les restrictions d’accès par catégorie. REMOVE conserve volontairement les restrictions d’accès par catégorie mais retire le libellé des restrictions de pôles : poleRestrictionsEmptied avertit lorsqu’un pôle perd son dernier filtre de catégorie, ce qui peut élargir l’accès à ce pôle. Les audiences de campagne, recherches enregistrées et générateurs automatiques de tags système restent inchangés : un tag système peut réapparaître lors d’une prochaine action métier. Aucun contact n’est supprimé. Il ne s’agit pas d’un snapshot global atomique : les writers internes ne sont pas verrouillés et l’intention à l’échelle de l’organisation peut inclure des fiches créées pendant la commande. Les compteurs et la révision décrivent uniquement les documents portant les tags observés, avec au plus 5000 documents par observation. Aucun prestataire n’est appelé. 

### Authentification

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

### Permissions requises

```json
{
  "accepted": "contacts:manage-tags",
  "additional": [
    "contacts:read",
    "contacts:write"
  ]
}
```

### Paramètres

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Réponses

#### HTTP 200

```json
{
  "description": "Dernier état durable de la commande ; aucun nouvel essai.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContactTagCommandReceiptResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_COMMAND, INVALID_ACTION, INVALID_TAG, IDENTICAL_TAGS, UNEXPECTED_TARGET_TAG, UNKNOWN_BODY_PARAMETER, UNKNOWN_QUERY_PARAMETER, INVALID_REVISION, INVALID_IDEMPOTENCY_KEY, INVALID_UUID ou LIMITS_NOT_ACKNOWLEDGED : corriger l’entrée déclarée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Authentification absente ou invalide.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_ORGANISATION_CONTEXT ou CAMPAIGN_RESTRICTED_KEY : les trois autorisations explicites et une clé sans restriction de collecte de la même organisation sont nécessaires.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "TAG_NOT_FOUND, TARGET_TAG_NOT_FOUND ou COMMAND_NOT_FOUND : utiliser un libellé exact existant ou l’UUID d’une commande autorisée.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "INVALID_STORED_TAG_REFERENCE, TAG_COMMAND_TOO_LARGE ou IDEMPOTENCY_CONFLICT : aucun nouvel appel du propriétaire ; revoir les données source, réduire l’opération ou conserver le contenu d’idempotence d’origine.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR : aucun détail d’erreur privé n’est exposé.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE : l’admission du résultat n’a pas pu être prouvée. Consulter l’état de la commande d’origine ; ne jamais inventer une nouvelle clé pour réessayer un effet incertain.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "contacts:manage-tags",
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "contacts:write"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## Schémas

```json
{
  "components": {
    "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"
          }
        }
      },
      "UnisoftRequest_e4688e4bc822e21f91a3": {
        "type": "object",
        "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",
              null
            ],
            "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",
            "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"
                }
              },
              "additionalProperties": false
            },
            "description": "Adresses SECONDAIRES supplémentaires à ajouter."
          },
          "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": {
              "type": "object",
              "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)."
                }
              },
              "required": [
                "key"
              ],
              "additionalProperties": false,
              "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)."
            },
            "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[]`."
          }
        },
        "additionalProperties": false,
        "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."
      },
      "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": "Métadonnées des options d’import fournies par le service métier. Seules les options déclarées dans ContactImportInput peuvent être utilisées via cette API ; les métadonnées seules n’autorisent pas d’arguments supplémentaires.",
            "additionalProperties": true
          }
        }
      },
      "UnisoftRequest_f3635fecc6f75b85ba0f": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "array",
            "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."
                }
              },
              "additionalProperties": false
            },
            "description": "Chaque objet contient les valeurs brutes des cellules d’une ligne du tableur."
          },
          "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."
          }
        },
        "required": [
          "rows"
        ],
        "additionalProperties": false,
        "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."
      },
      "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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "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"
              }
            }
          }
        }
      },
      "UnisoftRequest_7ef2b58154210ab6fbbe": {
        "type": "object",
        "properties": {
          "contacts": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/UnisoftRequest_7e027332669117995c44"
            },
            "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)."
          },
          "options": {
            "type": "object",
            "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\")."
              }
            },
            "additionalProperties": false,
            "description": "Options d’importation."
          },
          "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
          }
        },
        "required": [
          "contacts"
        ],
        "additionalProperties": false,
        "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."
      },
      "UnisoftRequest_7e027332669117995c44": {
        "type": "object",
        "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",
              null
            ],
            "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",
            "maxLength": 100,
            "nullable": true
          },
          "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 principale fournie au service métier d’import en masse. Pour les contacts correspondants, elle peut remplacer l’adresse principale actuelle ; comparez-la avant dryRun et avant l’application. Ce comportement diffère de create_contact, qui complète les champs vides."
          },
          "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",
            "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"
                }
              },
              "additionalProperties": false
            },
            "description": "Adresses SECONDAIRES supplémentaires à ajouter."
          },
          "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": {
              "type": "object",
              "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)."
                }
              },
              "required": [
                "key"
              ],
              "additionalProperties": false,
              "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)."
            },
            "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[]`."
          },
          "__row": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            ]
          }
        },
        "additionalProperties": false,
        "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."
      },
      "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."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "UnisoftRequest_731434cf8427fd36cfcb": {
        "type": "object",
        "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",
              null
            ],
            "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"
          }
        },
        "additionalProperties": false,
        "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."
      },
      "UnisoftRequest_b743641a58b8fd5cb226": {
        "type": "object",
        "properties": {
          "customFields": {
            "type": "array",
            "items": {
              "type": "object",
              "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)."
                }
              },
              "required": [
                "key"
              ],
              "additionalProperties": false,
              "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)."
            },
            "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
          }
        },
        "required": [
          "customFields"
        ],
        "additionalProperties": false,
        "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."
      },
      "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
          }
        }
      },
      "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
          }
        }
      },
      "ChlihoutSettingsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ChlihoutSettings"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ChlihoutSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740990
          },
          "types": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 80,
                  "pattern": "^[A-Z][A-Z0-9_-]*$"
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "label",
                "enabled"
              ]
            }
          },
          "levels": {
            "type": "array",
            "minItems": 2,
            "maxItems": 30,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "value": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "label": {
                  "type": "string",
                  "maxLength": 100
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "value",
                "label",
                "enabled"
              ]
            }
          }
        },
        "required": [
          "revision",
          "types",
          "levels"
        ]
      },
      "ContactMergePreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactMergePreview"
          }
        }
      },
      "ContactMergePreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "survivor",
          "absorbed",
          "merged",
          "revision",
          "effects",
          "physicalDeletionOfAbsorbed",
          "financialAmountsChanged",
          "historicalSnapshotsRewritten",
          "precedence",
          "effectsDeferred",
          "choicesAvailable",
          "atomicAcrossInternalWriters"
        ],
        "properties": {
          "survivor": {
            "$ref": "#/components/schemas/ContactMergeProfile"
          },
          "absorbed": {
            "$ref": "#/components/schemas/ContactMergeProfile"
          },
          "merged": {
            "$ref": "#/components/schemas/ContactMergeProfile"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "effects": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "domain",
                "records",
                "action"
              ],
              "properties": {
                "domain": {
                  "type": "string",
                  "enum": [
                    "paiements",
                    "dettes_v2",
                    "rappel",
                    "forms_submit"
                  ]
                },
                "records": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 2000
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "REASSIGN_CONTACT"
                  ]
                }
              }
            }
          },
          "physicalDeletionOfAbsorbed": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "financialAmountsChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "historicalSnapshotsRewritten": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "precedence": {
            "type": "string",
            "enum": [
              "SURVIVOR_PRESENT_SCALARS_SOURCE_OBJECT_OVERLAY_ARRAY_UNION_NATIVE"
            ]
          },
          "effectsDeferred": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "choicesAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "atomicAcrossInternalWriters": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactMergeProfile": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "firstName",
          "lastName",
          "email",
          "phone",
          "gender",
          "categories",
          "secondaryEmails",
          "secondaryPhones",
          "primaryAddress"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "email": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "phone": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true
          },
          "gender": {
            "type": "string",
            "nullable": true,
            "enum": [
              "M",
              "F",
              null
            ]
          },
          "categories": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "type": "string",
              "maxLength": 1000
            }
          },
          "secondaryEmails": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "value",
                "label"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "maxLength": 1000
                },
                "label": {
                  "type": "string",
                  "maxLength": 1000,
                  "nullable": true
                }
              }
            }
          },
          "secondaryPhones": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "value",
                "label"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "maxLength": 1000
                },
                "label": {
                  "type": "string",
                  "maxLength": 1000,
                  "nullable": true
                }
              }
            }
          },
          "primaryAddress": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "line",
              "postalCode",
              "city",
              "state",
              "country"
            ],
            "properties": {
              "line": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "postalCode": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "city": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "state": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "country": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            }
          }
        }
      },
      "ContactMergeError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ContactMergeReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactMergeReceipt"
          }
        }
      },
      "ContactMergeReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "survivorId",
          "absorbedId",
          "nativeOperationId",
          "state",
          "effects",
          "effectsDeferred",
          "canRetry",
          "error",
          "lockCleanup",
          "atomicAcrossInternalWriters"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "survivorId": {
            "type": "string",
            "format": "uuid"
          },
          "absorbedId": {
            "type": "string",
            "format": "uuid"
          },
          "nativeOperationId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED_PENDING_EFFECTS",
              "REJECTED",
              "UNKNOWN"
            ]
          },
          "effects": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "domain",
                "records",
                "action"
              ],
              "properties": {
                "domain": {
                  "type": "string",
                  "enum": [
                    "paiements",
                    "dettes_v2",
                    "rappel",
                    "forms_submit"
                  ]
                },
                "records": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 2000
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "REASSIGN_CONTACT"
                  ]
                }
              }
            }
          },
          "effectsDeferred": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "lockCleanup": {
            "type": "string",
            "enum": [
              "NOT_ATTEMPTED",
              "RELEASED",
              "RETAINED",
              "UNKNOWN"
            ]
          },
          "atomicAcrossInternalWriters": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactNotesReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactNotesRead"
          }
        }
      },
      "ContactNotesRead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "content",
          "present"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "content": {
            "type": "string",
            "nullable": true,
            "maxLength": 20000
          },
          "present": {
            "type": "boolean"
          }
        }
      },
      "ContactInteractionsError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      },
      "ContactInteractionCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactInteractionCommandReceipt"
          }
        }
      },
      "ContactInteractionCommandReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "kind",
          "resourceId",
          "state",
          "canRetry",
          "error",
          "revision",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "NOTE",
              "INTERACTION",
              "ATTACHMENT"
            ]
          },
          "resourceId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "startedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "ContactInteractionReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactInteractionRead"
          }
        }
      },
      "ContactInteractionRead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "id",
          "revision",
          "type",
          "content",
          "actions",
          "address",
          "time"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "content": {
            "type": "string",
            "nullable": true,
            "maxLength": 20000
          },
          "actions": {
            "type": "array",
            "nullable": true,
            "maxItems": 50,
            "items": {
              "type": "string",
              "maxLength": 100
            }
          },
          "address": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          },
          "time": {
            "$ref": "#/components/schemas/ContactInteractionTime"
          }
        }
      },
      "ContactInteractionTime": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "precision",
          "occurredOn",
          "datetime"
        ],
        "properties": {
          "precision": {
            "type": "string",
            "enum": [
              "DAY",
              "INSTANT",
              "UNKNOWN"
            ]
          },
          "occurredOn": {
            "type": "string",
            "nullable": true,
            "format": "date"
          },
          "datetime": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          }
        }
      },
      "UnisoftRequest_4b1a347f28ed132dbea4": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "changes": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "type": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "content": {
                "type": "string",
                "maxLength": 20000
              },
              "actions": {
                "type": "array",
                "maxItems": 50,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                }
              },
              "address": {
                "type": "string",
                "maxLength": 2000
              },
              "occurredOn": {
                "type": "string",
                "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}$",
                "format": "date"
              },
              "datetime": {
                "type": "string",
                "pattern": "^(?!0000)\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
                "format": "date-time"
              }
            },
            "additionalProperties": false,
            "not": {
              "required": [
                "occurredOn",
                "datetime"
              ]
            }
          }
        },
        "required": [
          "expectedRevision",
          "idempotencyKey",
          "changes"
        ],
        "additionalProperties": false
      },
      "ContactAttachmentsReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactAttachmentList"
          }
        }
      },
      "ContactAttachmentList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "scope",
          "data"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "scope": {
            "type": "string",
            "enum": [
              "CONTACT"
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactAttachmentRead"
            }
          }
        }
      },
      "ContactAttachmentRead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "filename",
          "recordedAt",
          "availability"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "filename": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "recordedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "availability": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE"
            ]
          }
        }
      },
      "UnisoftRequest_891c98c82ce4abde0764": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "ADD"
                ]
              },
              "filename": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "^(?!.*\\.\\.)[A-Za-z0-9][A-Za-z0-9._-]*\\.[A-Za-z0-9]+$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "expectedRevision",
              "idempotencyKey",
              "action",
              "filename"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "EDIT"
                ]
              },
              "documentId": {
                "type": "string",
                "format": "uuid"
              },
              "filename": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "pattern": "^(?!.*\\.\\.)[A-Za-z0-9][A-Za-z0-9._-]*\\.[A-Za-z0-9]+$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "expectedRevision",
              "idempotencyKey",
              "action",
              "documentId"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "filename"
                ]
              },
              {
                "required": [
                  "name"
                ]
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "idempotencyKey": {
                "type": "string",
                "minLength": 8,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "DETACH"
                ]
              },
              "documentId": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "expectedRevision",
              "idempotencyKey",
              "action",
              "documentId"
            ],
            "additionalProperties": false
          }
        ]
      },
      "ContactSyncConnectionResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactSyncConnection"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactSyncMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactSyncConnection": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "CONNECTED",
              "NEEDS_REAUTH",
              "DISCONNECTED",
              null
            ],
            "nullable": true
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "configuration": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "fields": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "enum": [
                    "name",
                    "email",
                    "phone",
                    "address",
                    "birthday",
                    "otherNames",
                    "company",
                    "jobTitle",
                    "department",
                    "occupation",
                    "websites",
                    "notes",
                    "photo",
                    "events",
                    "relations",
                    "labels",
                    "custom"
                  ]
                }
              },
              "groupIds": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "pattern": "^contactGroups/[\\w-]+$"
                }
              },
              "coordinates": {
                "type": "string",
                "enum": [
                  "primary",
                  "all"
                ]
              },
              "policy": {
                "type": "string",
                "enum": [
                  "fill",
                  "replace"
                ]
              },
              "country": {
                "type": "string",
                "pattern": "^[A-Z]{2}$"
              },
              "fieldPolicies": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "field": {
                      "type": "string",
                      "enum": [
                        "name",
                        "email",
                        "phone",
                        "address",
                        "birthday",
                        "otherNames",
                        "company",
                        "jobTitle",
                        "department",
                        "occupation",
                        "websites",
                        "notes",
                        "photo",
                        "events",
                        "relations",
                        "labels",
                        "custom"
                      ]
                    },
                    "policy": {
                      "type": "string",
                      "enum": [
                        "fill",
                        "replace"
                      ]
                    }
                  },
                  "required": [
                    "field",
                    "policy"
                  ]
                }
              },
              "valueModes": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "field": {
                      "type": "string",
                      "enum": [
                        "email",
                        "phone",
                        "address"
                      ]
                    },
                    "mode": {
                      "type": "string",
                      "enum": [
                        "primary",
                        "all"
                      ]
                    }
                  },
                  "required": [
                    "field",
                    "mode"
                  ]
                }
              },
              "destinations": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "field": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  },
                  "required": [
                    "field",
                    "key"
                  ]
                }
              },
              "labels": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "groupId": {
                      "type": "string"
                    },
                    "tag": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  },
                  "required": [
                    "groupId",
                    "tag"
                  ]
                }
              },
              "customFields": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "source": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "key": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "TEXT",
                        "NUMBER",
                        "BOOL",
                        "DATE"
                      ]
                    }
                  },
                  "required": [
                    "source",
                    "key",
                    "type"
                  ]
                }
              }
            },
            "required": [
              "fields",
              "groupIds",
              "coordinates",
              "policy",
              "country",
              "fieldPolicies",
              "valueModes",
              "destinations",
              "labels",
              "customFields"
            ],
            "nullable": true
          },
          "configurationState": {
            "type": "string",
            "enum": [
              "VALID_STORED_CONFIGURATION",
              "UNAVAILABLE_OR_INVALID"
            ]
          },
          "scheduleEnabled": {
            "type": "boolean",
            "nullable": true
          },
          "hasImported": {
            "type": "boolean",
            "nullable": true
          },
          "lastRunAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "lastRunState": {
            "type": "string",
            "enum": [
              "QUEUED",
              "PREPARING",
              "REVIEW_READY",
              "RUNNING",
              "SUCCEEDED",
              "PARTIAL",
              "FAILED",
              "STOPPED",
              null
            ],
            "nullable": true
          },
          "lastRunStats": {
            "$ref": "#/components/schemas/ContactSyncStats"
          }
        },
        "required": [
          "id",
          "status",
          "revision",
          "configuration",
          "configurationState",
          "scheduleEnabled",
          "hasImported",
          "lastRunAt",
          "lastRunState",
          "lastRunStats"
        ]
      },
      "ContactSyncStats": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "loaded": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "created": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "updated": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "skipped": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "review": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "failed": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "pending": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          }
        },
        "required": [
          "loaded",
          "created",
          "updated",
          "skipped",
          "review",
          "failed",
          "pending"
        ]
      },
      "ContactSyncMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5000
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "workerReadiness": {
            "type": "boolean",
            "enum": [
              null
            ],
            "nullable": true
          },
          "completeHistory": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "order": {
            "type": "string",
            "enum": [
              "ID_ASC",
              "CREATED_AT_DESC_UNDATED_LAST_ID_ASC",
              "ROW_INDEX_ASC_ID_ASC"
            ]
          }
        },
        "required": [
          "count",
          "total",
          "hasMore",
          "nextCursor",
          "readAt",
          "consistentSnapshot",
          "providerChecked",
          "workerReadiness",
          "completeHistory",
          "order"
        ]
      },
      "ContactSyncError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactSyncRunResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactSyncRun"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactSyncMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactSyncRun": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "connectionId": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "PREVIEW",
              "IMPORT",
              null
            ],
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "QUEUED",
              "PREPARING",
              "REVIEW_READY",
              "RUNNING",
              "SUCCEEDED",
              "PARTIAL",
              "FAILED",
              "STOPPED",
              null
            ],
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "automatic": {
            "type": "boolean",
            "nullable": true
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "nullable": true
          },
          "stats": {
            "$ref": "#/components/schemas/ContactSyncStats"
          },
          "errorCode": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "connectionId",
          "kind",
          "state",
          "createdAt",
          "finishedAt",
          "automatic",
          "revision",
          "stats",
          "errorCode"
        ]
      },
      "ContactSyncConflictResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactSyncConflict"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactSyncMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactSyncConflict": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rowId": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "REVIEW",
              "CREATED",
              "UPDATED",
              "SKIPPED",
              "FAILED",
              null
            ],
            "nullable": true
          },
          "resolutionKind": {
            "type": "string",
            "enum": [
              "CREATE",
              "LINK",
              "REVIEW",
              null
            ],
            "nullable": true
          },
          "reasonCode": {
            "type": "string",
            "nullable": true
          },
          "decisionAction": {
            "type": "string",
            "enum": [
              "CREATE",
              "LINK",
              "IGNORE",
              null
            ],
            "nullable": true
          },
          "errorCode": {
            "type": "string",
            "nullable": true
          },
          "requiresHumanReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "canDecide": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "rowId",
          "index",
          "state",
          "resolutionKind",
          "reasonCode",
          "decisionAction",
          "errorCode",
          "requiresHumanReview",
          "canDecide"
        ]
      },
      "ContactCommunicationPreferencesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCommunicationPreferences"
          }
        }
      },
      "ContactCommunicationPreferences": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "observedAt",
          "snapshotGuaranteed",
          "email",
          "sms",
          "whatsapp",
          "optInAvailable"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "snapshotGuaranteed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "email": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "address",
              "optOut",
              "sharedPolicyOptOut",
              "historicalEmailRefusal",
              "legacyOptOut",
              "optOutAvailable",
              "affects"
            ],
            "properties": {
              "address": {
                "type": "string",
                "format": "email",
                "maxLength": 320,
                "nullable": true
              },
              "optOut": {
                "type": "string",
                "enum": [
                  "RECORDED",
                  "NOT_RECORDED",
                  "ADDRESS_UNAVAILABLE"
                ]
              },
              "sharedPolicyOptOut": {
                "type": "boolean",
                "nullable": true
              },
              "historicalEmailRefusal": {
                "type": "boolean",
                "nullable": true
              },
              "legacyOptOut": {
                "type": "boolean",
                "nullable": true
              },
              "optOutAvailable": {
                "type": "boolean"
              },
              "affects": {
                "type": "string",
                "enum": [
                  "ORGANISATION_EMAIL_ADDRESS"
                ]
              }
            }
          },
          "sms": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "optOut",
              "optOutAvailable",
              "reason"
            ],
            "properties": {
              "optOut": {
                "type": "string",
                "enum": [
                  "UNKNOWN"
                ]
              },
              "optOutAvailable": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "NO_CANONICAL_OPTOUT_OWNER"
                ]
              }
            }
          },
          "whatsapp": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "optOut",
              "optOutAvailable",
              "reason"
            ],
            "properties": {
              "optOut": {
                "type": "string",
                "enum": [
                  "UNKNOWN"
                ]
              },
              "optOutAvailable": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "NO_CANONICAL_OPTOUT_OWNER"
                ]
              }
            }
          },
          "optInAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactCommunicationPreferenceReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCommunicationPreferenceReceipt"
          }
        }
      },
      "ContactCommunicationPreferenceReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "channel",
          "address",
          "state",
          "ownerInvocationPossible",
          "sharedPolicyVerified",
          "legacyVerified",
          "canRetry",
          "error",
          "startedAt",
          "finishedAt",
          "affects",
          "queuedMessagesCancelled",
          "providerChecked"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "address": {
            "type": "string",
            "format": "email",
            "maxLength": 320
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "REJECTED",
              "PARTIAL",
              "UNKNOWN"
            ]
          },
          "ownerInvocationPossible": {
            "type": "boolean"
          },
          "sharedPolicyVerified": {
            "type": "boolean",
            "nullable": true
          },
          "legacyVerified": {
            "type": "boolean",
            "nullable": true
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true,
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "affects": {
            "type": "string",
            "enum": [
              "ORGANISATION_EMAIL_ADDRESS"
            ]
          },
          "queuedMessagesCancelled": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactDiscoveryResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactDiscoveryContact"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactDiscoveryMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactDiscoveryContact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            }
          },
          "archived": {
            "type": "boolean",
            "nullable": true
          },
          "deceased": {
            "type": "boolean",
            "nullable": true
          },
          "isNew": {
            "type": "boolean",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "email",
          "phone",
          "tags",
          "archived",
          "deceased",
          "isNew",
          "updatedAt"
        ]
      },
      "ContactDiscoveryMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "order": {
            "type": "string",
            "enum": [
              "ID_ASC"
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "listComputedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "order",
          "readAt",
          "listComputedAt",
          "consistentSnapshot"
        ]
      },
      "ContactPoleRuleStateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactPoleCategoryRules"
          }
        }
      },
      "ContactPoleCategoryRules": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "poleId",
          "label",
          "tags",
          "configured",
          "revision",
          "membershipMode",
          "manualMembershipEditable",
          "projectionRefreshed"
        ],
        "properties": {
          "poleId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "label": {
            "type": "string",
            "maxLength": 2000,
            "nullable": true
          },
          "tags": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          "configured": {
            "type": "boolean"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "membershipMode": {
            "type": "string",
            "enum": [
              "DERIVED_ANY_TAG_PLUS_BUSINESS_SOURCES"
            ]
          },
          "manualMembershipEditable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "projectionRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactPoleRuleReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactPoleRuleReceipt"
          }
        }
      },
      "ContactPoleRuleReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "poleId",
          "state",
          "canRetry",
          "error",
          "appliedTags",
          "projectionRefreshed",
          "staffWhitelistChanged",
          "manualMembershipWritten",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "poleId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "appliedTags": {
            "type": "array",
            "maxItems": 500,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "nullable": true
          },
          "projectionRefreshed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "staffWhitelistChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "manualMembershipWritten": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactHouseholdCapabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource",
          "actions",
          "roles",
          "relationshipScope",
          "accountAccessGranted",
          "financialEffects"
        ],
        "properties": {
          "resource": {
            "type": "string",
            "enum": [
              "CRM_HOUSEHOLD"
            ]
          },
          "actions": {
            "type": "array",
            "minItems": 6,
            "maxItems": 6,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "ADD_MEMBER",
                "REMOVE_MEMBER",
                "SET_HEAD",
                "RENAME",
                "ADD_RELATION",
                "REMOVE_RELATION"
              ]
            }
          },
          "roles": {
            "type": "array",
            "minItems": 2,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "HEAD",
                "MEMBER"
              ]
            }
          },
          "relationshipScope": {
            "type": "string",
            "enum": [
              "CURRENT_HOUSEHOLD_MEMBERS_ONLY"
            ]
          },
          "accountAccessGranted": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "financialEffects": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactHouseholdSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ContactHousehold": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name",
          "displayName",
          "revision",
          "recordedHeadContactId",
          "headContactId",
          "headState",
          "members",
          "relationshipScope",
          "relationships"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "displayName": {
            "type": "string"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "recordedHeadContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "headContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "headState": {
            "type": "string",
            "enum": [
              "UNASSIGNED",
              "MEMBER",
              "NOT_A_MEMBER"
            ]
          },
          "members": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ContactHouseholdMember"
            }
          },
          "relationshipScope": {
            "type": "string",
            "enum": [
              "CURRENT_HOUSEHOLD_MEMBERS_ONLY"
            ]
          },
          "relationships": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "sourceContactId",
                "relatedContactId",
                "relationship"
              ],
              "properties": {
                "sourceContactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "relatedContactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "relationship": {
                  "type": "string",
                  "enum": [
                    "SPOUSE",
                    "PARENT",
                    "CHILD",
                    "SIBLING",
                    "GRANDPARENT",
                    "GRANDCHILD",
                    "IN_LAW",
                    "EX",
                    "COUSIN",
                    "FRIEND"
                  ]
                }
              }
            }
          }
        }
      },
      "ContactHouseholdMember": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "firstName",
          "lastName",
          "revision",
          "isGlobalFamilyHead",
          "role",
          "legacyParentContactIds"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "isGlobalFamilyHead": {
            "type": "boolean",
            "nullable": true
          },
          "role": {
            "type": "string",
            "enum": [
              "HEAD",
              "MEMBER"
            ]
          },
          "legacyParentContactIds": {
            "type": "array",
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        }
      },
      "ContactHouseholdContactMemberships": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "contactRevision",
          "households"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "contactRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "households": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ContactHouseholdSummary"
            }
          }
        }
      },
      "UnisoftRequest_f10a365c7bd580a11747": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "ADD_MEMBER"
                ]
              },
              "contactId": {
                "type": "string",
                "format": "uuid"
              },
              "expectedContactRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "contactId",
              "expectedContactRevision"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "REMOVE_MEMBER"
                ]
              },
              "contactId": {
                "type": "string",
                "format": "uuid"
              },
              "expectedContactRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "contactId",
              "expectedContactRevision"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "SET_HEAD"
                ]
              },
              "contactId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "contactId"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "RENAME"
                ]
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 250
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "name"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "ADD_RELATION"
                ]
              },
              "sourceContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relatedContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relationship": {
                "type": "string",
                "enum": [
                  "SPOUSE",
                  "PARENT",
                  "CHILD",
                  "SIBLING",
                  "GRANDPARENT",
                  "GRANDCHILD",
                  "IN_LAW",
                  "EX",
                  "COUSIN",
                  "FRIEND"
                ]
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "sourceContactId",
              "relatedContactId",
              "relationship"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "format": "uuid"
              },
              "expectedRevision": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "action": {
                "type": "string",
                "enum": [
                  "REMOVE_RELATION"
                ]
              },
              "sourceContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relatedContactId": {
                "type": "string",
                "format": "uuid"
              },
              "relationship": {
                "type": "string",
                "enum": [
                  "SPOUSE",
                  "PARENT",
                  "CHILD",
                  "SIBLING",
                  "GRANDPARENT",
                  "GRANDCHILD",
                  "IN_LAW",
                  "EX",
                  "COUSIN",
                  "FRIEND"
                ]
              }
            },
            "required": [
              "idempotencyKey",
              "expectedRevision",
              "action",
              "sourceContactId",
              "relatedContactId",
              "relationship"
            ],
            "additionalProperties": false
          }
        ]
      },
      "ContactHouseholdCommandResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "householdId",
          "action",
          "status",
          "reason",
          "resultRevision",
          "concurrentInternalChangesPossible",
          "nativeHouseholdIds",
          "household"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "householdId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "ADD_MEMBER",
              "REMOVE_MEMBER",
              "SET_HEAD",
              "RENAME",
              "ADD_RELATION",
              "REMOVE_RELATION"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "APPLIED",
              "NOT_APPLIED",
              "UNKNOWN"
            ]
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "resultRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "concurrentInternalChangesPossible": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "nativeHouseholdIds": {
            "type": "array",
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "household": {
            "$ref": "#/components/schemas/ContactHousehold"
          }
        }
      },
      "UnisoftRequest_16f9ab52d2cb23a5f8eb": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "contacts": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "items": {
              "$ref": "#/components/schemas/UnisoftRequest_7e027332669117995c44"
            }
          },
          "options": {
            "type": "object",
            "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\")."
              }
            },
            "additionalProperties": false,
            "description": "Options d’importation."
          }
        },
        "required": [
          "idempotencyKey",
          "contacts"
        ],
        "additionalProperties": false
      },
      "ContactImportJobResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactImportJob"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactImportJob": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "DRAFT",
              "PREVIEWING",
              "READY",
              "RUNNING",
              "COMPLETED",
              "ATTENTION_REQUIRED"
            ]
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "previewFingerprint": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "counts": {
            "$ref": "#/components/schemas/ContactImportJobCounts"
          },
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactImportJobRow"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactImportJobMeta"
          }
        },
        "required": [
          "id",
          "state",
          "revision",
          "createdAt",
          "updatedAt",
          "previewFingerprint",
          "counts",
          "rows",
          "meta"
        ]
      },
      "ContactImportJobCounts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "previewed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "notStarted": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "running": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "succeeded": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "skipped": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "rejected": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          },
          "unknown": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000
          }
        },
        "required": [
          "total",
          "previewed",
          "notStarted",
          "running",
          "succeeded",
          "skipped",
          "rejected",
          "unknown"
        ]
      },
      "ContactImportJobRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1999
          },
          "sourceRow": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "string",
                "nullable": true
              }
            ]
          },
          "preview": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "create",
                  "update",
                  "skip",
                  "error"
                ]
              },
              "matchedContactId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "matchedContactAvailable": {
                "type": "boolean",
                "nullable": true
              },
              "issues": {
                "type": "array",
                "maxItems": 10,
                "items": {
                  "$ref": "#/components/schemas/ContactImportJobIssue"
                }
              },
              "issueCount": {
                "type": "integer",
                "minimum": 0
              },
              "issuesTruncated": {
                "type": "boolean"
              }
            },
            "required": [
              "action",
              "matchedContactId",
              "matchedContactAvailable",
              "issues",
              "issueCount",
              "issuesTruncated"
            ],
            "nullable": true
          },
          "execution": {
            "$ref": "#/components/schemas/ContactImportJobExecution"
          }
        },
        "required": [
          "index",
          "sourceRow",
          "preview",
          "execution"
        ]
      },
      "ContactImportJobIssue": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "field": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "severity": {
            "type": "string",
            "enum": [
              "error",
              "warning",
              null
            ],
            "nullable": true
          }
        },
        "required": [
          "field",
          "reason",
          "severity"
        ]
      },
      "ContactImportJobExecution": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "NOT_STARTED",
              "RUNNING",
              "SUCCEEDED",
              "SKIPPED",
              "REJECTED",
              "UNKNOWN"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "create",
              "update",
              "skip",
              null
            ],
            "nullable": true
          },
          "matchedContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "matchedContactAvailable": {
            "type": "boolean",
            "nullable": true
          },
          "reasonCode": {
            "type": "string",
            "nullable": true
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "state",
          "action",
          "matchedContactId",
          "matchedContactAvailable",
          "reasonCode",
          "startedAt",
          "finishedAt"
        ]
      },
      "ContactImportJobMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "sourceRowsReturned": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "targetReferencesChecked": {
            "type": "boolean"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "sourceRowsReturned",
          "targetReferencesChecked",
          "consistentSnapshot"
        ]
      },
      "ContactImportJobError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactTimelineResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTimelineResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactTimelineResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "period": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              },
              "endExclusive": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "from",
              "to",
              "endExclusive"
            ]
          },
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactTimelineItem"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactTimelineMeta"
          }
        },
        "required": [
          "contactId",
          "period",
          "items",
          "meta"
        ]
      },
      "ContactTimelineItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "INTERACTION",
              "REGISTRATION",
              "PAYMENT",
              "SUBSCRIPTION"
            ]
          },
          "recordId": {
            "type": "string",
            "format": "uuid"
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time"
          },
          "datePrecision": {
            "type": "string",
            "enum": [
              "DAY",
              "RECORDED_TIMESTAMP",
              "UNKNOWN"
            ]
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "relation": {
            "type": "string",
            "enum": [
              "CURRENT_CONTACT",
              "LEGACY_PAYLOAD_CONTACT"
            ]
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true
          },
          "amountMeaning": {
            "type": "string",
            "enum": [
              "PAYMENT_ATTEMPT_NOMINAL",
              "SUBSCRIPTION_CONTRACT_NOMINAL",
              null
            ],
            "nullable": true
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "nullable": true
          },
          "instrument": {
            "type": "string",
            "enum": [
              "MONETARY",
              "IN_KIND",
              "UNKNOWN",
              null
            ],
            "nullable": true
          },
          "imported": {
            "type": "boolean",
            "nullable": true
          },
          "paymentPhase": {
            "type": "string",
            "nullable": true
          },
          "active": {
            "type": "boolean",
            "nullable": true
          },
          "target": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "FORM",
                  "SUBMISSION",
                  "CAMPAIGN",
                  "PLEDGE",
                  "CAISSE"
                ]
              },
              "id": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "kind",
              "id"
            ],
            "nullable": true
          }
        },
        "required": [
          "source",
          "recordId",
          "recordedAt",
          "datePrecision",
          "occurredOn",
          "relation",
          "label",
          "state",
          "amountMinor",
          "amountMeaning",
          "currency",
          "instrument",
          "imported",
          "paymentPhase",
          "active",
          "target"
        ]
      },
      "ContactTimelineMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "sources": {
            "type": "array",
            "minItems": 1,
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ContactTimelineSourceCoverage"
            }
          },
          "completeContactHistory": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "sourceFailurePolicy": {
            "type": "string",
            "enum": [
              "FAIL_CLOSED"
            ]
          },
          "settlementVerification": {
            "type": "string",
            "enum": [
              "NOT_PERFORMED"
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "readAt",
          "sources",
          "completeContactHistory",
          "consistentSnapshot",
          "sourceFailurePolicy",
          "settlementVerification"
        ]
      },
      "ContactTimelineSourceCoverage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "INTERACTION",
              "REGISTRATION",
              "PAYMENT",
              "SUBSCRIPTION"
            ]
          },
          "unsupportedDateCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "scope": {
            "type": "string",
            "enum": [
              "KEY_CAMPAIGNS_ONLY",
              "ORGANISATION_CONTACT"
            ]
          },
          "unsupportedFinancialTypesExcluded": {
            "type": "boolean"
          }
        },
        "required": [
          "source",
          "unsupportedDateCount",
          "scope",
          "unsupportedFinancialTypesExcluded"
        ]
      },
      "ContactTimelineError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactBulkPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactBulkPreview"
          }
        }
      },
      "ContactBulkPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactIds",
          "changes",
          "revision",
          "observedAt",
          "snapshotGuaranteed",
          "rows"
        ],
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes": {
            "type": "object",
            "additionalProperties": false,
            "minProperties": 1,
            "properties": {
              "addTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "removeTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "identity": {
                "type": "object",
                "additionalProperties": false,
                "minProperties": 1,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "gender": {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      "M",
                      "F",
                      null
                    ]
                  },
                  "hebrewFirstName": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "snapshotGuaranteed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "rows": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "contactId",
                "state"
              ],
              "properties": {
                "contactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "WILL_CHANGE",
                    "NO_CHANGE"
                  ]
                }
              }
            }
          }
        }
      },
      "UnisoftRequest_835aa2faff08c42df4c5": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "changes": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "addTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "removeTags": {
                "type": "array",
                "minItems": 1,
                "maxItems": 50,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                }
              },
              "identity": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "M",
                      "F",
                      null
                    ],
                    "nullable": true
                  },
                  "hebrewFirstName": {
                    "type": "string",
                    "maxLength": 200
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "contactIds",
          "changes",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      },
      "ContactBulkReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactBulkReceipt"
          }
        }
      },
      "ContactBulkReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "state",
          "canRetry",
          "error",
          "rows",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "REJECTED",
              "PARTIAL",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "rows": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "contactId",
                "state"
              ],
              "properties": {
                "contactId": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "PENDING",
                    "RUNNING",
                    "APPLIED",
                    "NO_CHANGE",
                    "CONFLICT",
                    "BLOCKED",
                    "UNKNOWN",
                    "NOT_ATTEMPTED"
                  ]
                }
              }
            }
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactCoordinateStateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCoordinates"
          }
        }
      },
      "ContactCoordinates": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "revision",
          "primary",
          "secondaryEmails",
          "secondaryPhones",
          "secondaryAddresses",
          "geographyRecomputed"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "primary": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "email",
              "phone",
              "address"
            ],
            "properties": {
              "email": {
                "type": "string",
                "nullable": true,
                "maxLength": 2000
              },
              "phone": {
                "type": "string",
                "nullable": true,
                "maxLength": 2000
              },
              "address": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "address",
                  "postalCode",
                  "city",
                  "region",
                  "country",
                  "note"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "postalCode": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "city": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "region": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "country": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  },
                  "note": {
                    "type": "string",
                    "nullable": true,
                    "maxLength": 2000
                  }
                }
              }
            }
          },
          "secondaryEmails": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "email",
                "label"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "email": {
                  "type": "string",
                  "maxLength": 2000
                },
                "label": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 200
                }
              }
            }
          },
          "secondaryPhones": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "phone",
                "label"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "phone": {
                  "type": "string",
                  "maxLength": 2000
                },
                "label": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 200
                }
              }
            }
          },
          "secondaryAddresses": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "address",
                "postalCode",
                "city",
                "region",
                "country",
                "note",
                "label",
                "type",
                "companyId"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "address": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "region": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "note": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "label": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "type": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                },
                "companyId": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 2000
                }
              }
            }
          },
          "geographyRecomputed": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "UnisoftRequest_3eb894b2a1f27c208752": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "EMAIL",
              "PHONE",
              "ADDRESS"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "EDIT",
              "REMOVE",
              "MAKE_PRIMARY"
            ]
          },
          "coordinateId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 320
          },
          "phoneCountry": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "label": {
            "type": "string",
            "maxLength": 200
          },
          "address": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "address": {
                "type": "string",
                "maxLength": 2000
              },
              "postalCode": {
                "type": "string",
                "maxLength": 2000
              },
              "city": {
                "type": "string",
                "maxLength": 2000
              },
              "region": {
                "type": "string",
                "maxLength": 2000
              },
              "country": {
                "type": "string",
                "maxLength": 2000
              },
              "note": {
                "type": "string",
                "maxLength": 2000
              },
              "label": {
                "type": "string",
                "maxLength": 2000
              },
              "type": {
                "type": "string",
                "maxLength": 2000
              },
              "companyId": {
                "type": "string",
                "maxLength": 2000
              }
            },
            "additionalProperties": false
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[a-zA-Z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "kind",
          "action",
          "coordinateId",
          "revision",
          "idempotencyKey"
        ],
        "additionalProperties": false
      },
      "ContactCoordinateReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactCoordinateReceipt"
          }
        }
      },
      "ContactCoordinateReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "state",
          "canRetry",
          "error",
          "geographyRecomputed",
          "consentChanged",
          "fiscalHistoryChanged",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "geographyRecomputed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "consentChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "fiscalHistoryChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactLifecycleStateResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactLifecycle"
          }
        }
      },
      "ContactLifecycle": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "state",
          "archived",
          "trashed",
          "deceased",
          "isNew",
          "mergedIntoContactId",
          "revision",
          "permanentDeletionAvailable"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED",
              "TRASHED",
              "MERGED"
            ]
          },
          "archived": {
            "type": "boolean"
          },
          "trashed": {
            "type": "boolean"
          },
          "deceased": {
            "type": "boolean",
            "nullable": true
          },
          "isNew": {
            "type": "boolean",
            "nullable": true
          },
          "mergedIntoContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "permanentDeletionAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "ContactLifecycleReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactLifecycleReceipt"
          }
        }
      },
      "ContactLifecycleReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "contactId",
          "action",
          "state",
          "lifecycleState",
          "canRetry",
          "error",
          "linkedRecordsDeleted",
          "fiscalHistoryChanged",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "ARCHIVE",
              "UNARCHIVE",
              "TRASH",
              "RESTORE"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "APPLIED",
              "NO_CHANGE",
              "REJECTED",
              "CONFLICT",
              "UNKNOWN"
            ]
          },
          "lifecycleState": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED",
              "TRASHED",
              "MERGED",
              null
            ],
            "nullable": true
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "linkedRecordsDeleted": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "fiscalHistoryChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactPostalExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactPostalExportResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactPostalExportResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactPostalExportRow"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "selectedCount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2000
              },
              "totalRows": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              },
              "readAt": {
                "type": "string",
                "format": "date-time"
              },
              "consistentSnapshot": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "skippedNoAddress": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000
              },
              "householdContextUsed": {
                "type": "boolean"
              },
              "genderInferencePublished": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "required": [
              "selectedCount",
              "totalRows",
              "count",
              "hasMore",
              "nextCursor",
              "readAt",
              "consistentSnapshot",
              "skippedNoAddress",
              "householdContextUsed",
              "genderInferencePublished"
            ]
          }
        },
        "required": [
          "rows",
          "meta"
        ]
      },
      "ContactPostalExportRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rowId": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "representativeContactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "formattedRecipient": {
            "type": "string",
            "nullable": true
          },
          "familyLabel": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "postalCode": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "grouping": {
            "type": "string",
            "enum": [
              "CONTACT",
              "HOUSEHOLD"
            ]
          },
          "recipientFormat": {
            "type": "string",
            "enum": [
              "NAME_ONLY"
            ]
          },
          "addressSource": {
            "type": "string",
            "enum": [
              "PRIMARY"
            ]
          }
        },
        "required": [
          "rowId",
          "representativeContactId",
          "formattedRecipient",
          "familyLabel",
          "address",
          "postalCode",
          "city",
          "region",
          "country",
          "grouping",
          "recipientFormat",
          "addressSource"
        ]
      },
      "ContactPostalExportError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactMapExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactMapExportResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactMapExportResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactMapExportRow"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "selectedCount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 2000
              },
              "totalRows": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5000
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "hasMore": {
                "type": "boolean"
              },
              "nextCursor": {
                "type": "string",
                "nullable": true
              },
              "readAt": {
                "type": "string",
                "format": "date-time"
              },
              "consistentSnapshot": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "contactsWithoutAddress": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "geocodingPerformed": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "required": [
              "selectedCount",
              "totalRows",
              "count",
              "hasMore",
              "nextCursor",
              "readAt",
              "consistentSnapshot",
              "contactsWithoutAddress",
              "geocodingPerformed"
            ]
          }
        },
        "required": [
          "rows",
          "meta"
        ]
      },
      "ContactMapExportRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "addressId": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "MAIN"
                ]
              },
              {
                "type": "string",
                "format": "uuid"
              }
            ]
          },
          "displayName": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "postalCode": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "nullable": true
          },
          "coordinateStatus": {
            "type": "string",
            "enum": [
              "STORED_CURRENT_ADDRESS_MATCH",
              "NO_VERIFIED_STORED_COORDINATE"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "STORED_ONLY_NO_GEOCODER"
            ]
          }
        },
        "required": [
          "contactId",
          "addressId",
          "displayName",
          "address",
          "postalCode",
          "city",
          "region",
          "country",
          "latitude",
          "longitude",
          "coordinateStatus",
          "source"
        ]
      },
      "ContactReconciliationResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactReconciliationResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactReconciliationResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "protocol": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "RECONCILE"
            ]
          },
          "scope": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "reset": {
            "type": "boolean"
          },
          "manifest": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/ContactReconciliationManifestEntry"
            }
          },
          "upserts": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/ContactReconciliationContact"
            }
          },
          "removed": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/ContactReconciliationRemoved"
            }
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "coverage": {
            "$ref": "#/components/schemas/ContactReconciliationCoverage"
          }
        },
        "required": [
          "protocol",
          "mode",
          "scope",
          "reset",
          "manifest",
          "upserts",
          "removed",
          "observedAt",
          "coverage"
        ]
      },
      "ContactReconciliationManifestEntry": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "id",
          "version"
        ]
      },
      "ContactReconciliationContact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "firstName": {
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            }
          },
          "archived": {
            "type": "boolean",
            "nullable": true
          },
          "deceased": {
            "type": "boolean",
            "nullable": true
          },
          "isNew": {
            "type": "boolean",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "email",
          "phone",
          "tags",
          "archived",
          "deceased",
          "isNew",
          "updatedAt",
          "createdAt"
        ]
      },
      "ContactReconciliationRemoved": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "reason": {
            "type": "string",
            "enum": [
              "UNKNOWN"
            ]
          }
        },
        "required": [
          "id",
          "reason"
        ]
      },
      "ContactReconciliationCoverage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "id",
                "firstName",
                "lastName",
                "email",
                "phone",
                "tags",
                "archived",
                "deceased",
                "isNew",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "selection": {
            "type": "string",
            "enum": [
              "EXPLICIT_IDS",
              "ORGANISATION"
            ]
          },
          "completeChangeJournal": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "archiveCurrentStateIncluded": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "mergeHistoryAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "hardDeleteReasonAvailable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "fields",
          "selection",
          "completeChangeJournal",
          "archiveCurrentStateIncluded",
          "mergeHistoryAvailable",
          "hardDeleteReasonAvailable",
          "consistentSnapshot"
        ]
      },
      "ContactReconciliationError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactQualityReadResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReadResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReadResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "findings": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReadFinding"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactQualityReadMeta"
          }
        },
        "required": [
          "findings",
          "meta"
        ]
      },
      "ContactQualityReadFinding": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "reasonCode": {
            "type": "string"
          },
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "severity": {
            "type": "string",
            "enum": [
              "info",
              "warning",
              "error",
              "critical",
              null
            ],
            "nullable": true
          },
          "proposedDuplicate": {
            "type": "boolean"
          },
          "requiresHumanReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "canApply": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "id",
          "method",
          "reasonCode",
          "contactIds",
          "severity",
          "proposedDuplicate",
          "requiresHumanReview",
          "canApply"
        ]
      },
      "ContactQualityReadMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "selectedCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "coverage": {
            "type": "string",
            "enum": [
              "SELECTED_CURRENT_CONTACTS_ONLY"
            ]
          },
          "storedAnalysisRead": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "completeOrganisationScan": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "sourceHistoryIncluded": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "familyContextComplete": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "duplicateCandidatesRequireReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "selectedCount",
          "count",
          "hasMore",
          "nextCursor",
          "readAt",
          "coverage",
          "storedAnalysisRead",
          "completeOrganisationScan",
          "sourceHistoryIncluded",
          "familyContextComplete",
          "duplicateCandidatesRequireReview"
        ]
      },
      "ContactQualityReadError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactQualityReportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReport"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReport": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,200}$",
            "nullable": true
          },
          "measuredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 100,
            "description": "Fuseau enregistré de l’organisation pour les dates civiles et les critères de 12/24 mois calendaires ; null si aucun fuseau n’a été enregistré. Les nouveaux bilans utilisent timeZone ou timezone de l’organisation, avec Europe/Paris par défaut. La fenêtre nocturne d’admission IA reste séparément définie en Europe/Paris. Aucun remplacement par paramètre de requête n’est accepté."
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "scope_changed",
              "not_prepared",
              "pending",
              "failed"
            ]
          },
          "stale": {
            "type": "boolean"
          },
          "view": {
            "$ref": "#/components/schemas/ContactQualityReportView"
          },
          "versions": {
            "$ref": "#/components/schemas/ContactQualityReportVersions"
          },
          "observation": {
            "$ref": "#/components/schemas/ContactQualityReportObservation"
          },
          "metrics": {
            "$ref": "#/components/schemas/ContactQualityReportMetrics"
          },
          "ai": {
            "$ref": "#/components/schemas/ContactQualityReportAi"
          },
          "warning": {
            "type": "string",
            "enum": [
              "calculation_failed"
            ]
          }
        },
        "required": [
          "id",
          "measuredAt",
          "timeZone",
          "status",
          "stale",
          "view",
          "versions",
          "observation",
          "metrics",
          "ai"
        ]
      },
      "ContactQualityReportView": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "scope": {
            "type": "string",
            "enum": [
              "global",
              "local"
            ],
            "default": "global"
          },
          "population": {
            "type": "string",
            "enum": [
              "all",
              "active"
            ],
            "default": "all"
          }
        },
        "required": [
          "scope",
          "population"
        ]
      },
      "ContactQualityReportVersions": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "criteria": {
            "type": "string",
            "maxLength": 100
          },
          "activity": {
            "type": "string",
            "maxLength": 100
          }
        },
        "required": [
          "criteria",
          "activity"
        ],
        "nullable": true
      },
      "ContactQualityReportObservation": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "transactional": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "startedAt",
          "finishedAt",
          "transactional"
        ],
        "nullable": true
      },
      "ContactQualityReportMetrics": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "evaluable": {
            "type": "integer",
            "minimum": 0
          },
          "clean": {
            "type": "integer",
            "minimum": 0
          },
          "affected": {
            "type": "integer",
            "minimum": 0
          },
          "unknown": {
            "type": "integer",
            "minimum": 0
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "nullable": true
          },
          "coverage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true
          },
          "activitySelectionUnknown": {
            "type": "integer",
            "minimum": 0
          },
          "kpis": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportKpi"
            }
          }
        },
        "required": [
          "total",
          "evaluable",
          "clean",
          "affected",
          "unknown",
          "score",
          "coverage",
          "activitySelectionUnknown",
          "kpis"
        ],
        "nullable": true
      },
      "ContactQualityReportKpi": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "penalizes": {
            "type": "boolean"
          }
        },
        "required": [
          "code",
          "count",
          "penalizes"
        ]
      },
      "ContactQualityReportAi": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "not_requested",
              "pending",
              "running",
              "partial",
              "complete",
              "interrupted",
              "superseded",
              "failed",
              "unavailable",
              "scope_unavailable"
            ]
          },
          "covered": {
            "type": "integer",
            "minimum": 0
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "sections": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportSection"
            }
          }
        },
        "required": [
          "status",
          "covered",
          "total",
          "generatedAt",
          "sections"
        ]
      },
      "ContactQualityReportSection": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "kind": {
            "type": "string",
            "enum": [
              "priority",
              "coincidence",
              "coverage"
            ]
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "relatedCode": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "denominator": {
            "type": "integer",
            "minimum": 0
          },
          "scope": {
            "type": "string",
            "enum": [
              "global",
              "local"
            ],
            "default": "global"
          },
          "population": {
            "type": "string",
            "enum": [
              "all",
              "active"
            ],
            "default": "all"
          },
          "action": {
            "type": "string",
            "enum": [
              "review",
              "improve"
            ]
          }
        },
        "required": [
          "id",
          "kind",
          "code",
          "relatedCode",
          "count",
          "denominator",
          "scope",
          "population",
          "action"
        ]
      },
      "ContactQualityReportError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactQualityReportHistoryResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReportHistory"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReportHistory": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportSummary"
            }
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "items",
          "nextCursor"
        ]
      },
      "ContactQualityReportSummary": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,200}$",
            "nullable": true
          },
          "measuredAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true,
            "minLength": 1,
            "maxLength": 100,
            "description": "Fuseau enregistré de l’organisation pour les dates civiles et les critères de 12/24 mois calendaires ; null si aucun fuseau n’a été enregistré. Les nouveaux bilans utilisent timeZone ou timezone de l’organisation, avec Europe/Paris par défaut. La fenêtre nocturne d’admission IA reste séparément définie en Europe/Paris. Aucun remplacement par paramètre de requête n’est accepté."
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "scope_changed",
              "not_prepared",
              "pending",
              "failed"
            ]
          },
          "stale": {
            "type": "boolean"
          },
          "view": {
            "$ref": "#/components/schemas/ContactQualityReportView"
          },
          "versions": {
            "$ref": "#/components/schemas/ContactQualityReportVersions"
          },
          "observation": {
            "$ref": "#/components/schemas/ContactQualityReportObservation"
          },
          "metrics": {
            "$ref": "#/components/schemas/ContactQualityReportMetrics"
          },
          "warning": {
            "type": "string",
            "enum": [
              "calculation_failed"
            ]
          }
        },
        "required": [
          "id",
          "measuredAt",
          "timeZone",
          "status",
          "stale",
          "view",
          "versions",
          "observation",
          "metrics"
        ]
      },
      "ContactQualityReportContactsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactQualityReportContacts"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactQualityReportContacts": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactQualityReportContact"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Contacts actuellement consultables correspondant à la recherche facultative sur leur nom actuel."
          },
          "measuredTotal": {
            "type": "integer",
            "minimum": 0,
            "description": "Membres datés du KPI autorisés pour le lecteur, avant disponibilité actuelle et recherche sur le nom."
          },
          "unavailable": {
            "type": "integer",
            "minimum": 0,
            "description": "Membres datés autorisés qui ne sont plus actuellement consultables, comptés avant la recherche sur le nom."
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "items",
          "total",
          "measuredTotal",
          "unavailable",
          "nextCursor"
        ]
      },
      "ContactQualityReportContact": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z0-9_.:-]{1,200}$"
          },
          "firstName": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          },
          "lastName": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          },
          "name": {
            "type": "string",
            "nullable": true,
            "maxLength": 2000
          }
        },
        "required": [
          "id"
        ]
      },
      "ContactSuggestionListResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionList"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ContactSuggestionMotif"
                },
                {
                  "$ref": "#/components/schemas/ContactSuggestionGroup"
                },
                {
                  "$ref": "#/components/schemas/ContactSuggestionPaused"
                }
              ]
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "size": {
            "type": "integer",
            "enum": [
              3,
              20,
              50
            ]
          },
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
          },
          "timeZone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "coverage": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "partial",
                  "calculated",
                  "pause_configuration"
                ]
              },
              "checked": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000,
                "nullable": true
              },
              "uncalculated": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000,
                "nullable": true
              },
              "limits": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                }
              },
              "population": {
                "type": "string",
                "enum": [
                  "local",
                  "global"
                ],
                "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
              }
            },
            "required": [
              "status",
              "checked",
              "uncalculated",
              "limits",
              "population"
            ]
          },
          "job": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "kind": {
                "type": "string",
                "enum": [
                  "analysis"
                ]
              },
              "state": {
                "type": "string",
                "enum": [
                  "queued",
                  "running",
                  "completed",
                  "partial",
                  "failed",
                  "canceled"
                ]
              },
              "population": {
                "type": "string",
                "enum": [
                  "local",
                  "global"
                ],
                "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
              },
              "volet": {
                "type": "string",
                "enum": [
                  "finance",
                  "social",
                  "both"
                ]
              },
              "contact": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "processed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000
              },
              "failed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "completedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "throttled": {
                "type": "boolean"
              }
            },
            "required": [
              "id",
              "kind",
              "state",
              "population",
              "volet",
              "contact",
              "processed",
              "failed",
              "createdAt",
              "completedAt",
              "code",
              "throttled"
            ],
            "nullable": true
          }
        },
        "required": [
          "items",
          "total",
          "page",
          "size",
          "population",
          "timeZone",
          "coverage",
          "job"
        ]
      },
      "ContactSuggestionMotif": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "motif"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "identity": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "firstName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "lastName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            },
            "required": [
              "id",
              "firstName",
              "lastName"
            ]
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
          },
          "family": {
            "type": "string",
            "enum": [
              "recognition",
              "restart_support",
              "relevant_project",
              "lasting_support",
              "commitment",
              "obstacle",
              "welcome",
              "develop_link",
              "reconnect",
              "life_event",
              "support",
              "followup",
              "involvement",
              "acknowledge_help"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
          },
          "state": {
            "type": "string",
            "enum": [
              "active",
              "review",
              "paused",
              "expired",
              "unavailable",
              "resolved"
            ]
          },
          "priority": {
            "$ref": "#/components/schemas/ContactSuggestionPriority"
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "evidence": {
            "type": "array",
            "maxItems": 250,
            "items": {
              "$ref": "#/components/schemas/ContactSuggestionEvidence"
            }
          },
          "firstDetectedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "analyzedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "nextReviewAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "dueAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "partial": {
            "type": "boolean"
          },
          "pauses": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160
                },
                "until": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true
                },
                "scope": {
                  "type": "string",
                  "enum": [
                    "common",
                    "personal"
                  ],
                  "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
                },
                "volet": {
                  "type": "string",
                  "enum": [
                    "finance",
                    "social"
                  ],
                  "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
                },
                "motif": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 160,
                  "nullable": true
                }
              },
              "required": [
                "id",
                "until",
                "scope",
                "volet",
                "motif"
              ]
            }
          }
        },
        "required": [
          "kind",
          "id",
          "contact",
          "identity",
          "volet",
          "family",
          "scope",
          "state",
          "priority",
          "reason",
          "evidence",
          "firstDetectedAt",
          "analyzedAt",
          "nextReviewAt",
          "dueAt",
          "partial",
          "pauses"
        ]
      },
      "ContactSuggestionPriority": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "nullable": true,
            "description": "Priorité d’action, pas une probabilité ni un jugement sur une personne. Quatre contributions arrondies (35/30/20/15), un ajustement de consignes et un éventuel plafond de vérification expliquent la valeur renvoyée. Par exemple, 66 points bruts peuvent devenir 49 parce que l’actualité du sujet doit être vérifiée. Utilisez le score et la version renvoyés, sans recalculer une version future."
          },
          "cap": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "criteria": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "P": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "T": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "A": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "E": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "P",
              "T",
              "A",
              "E"
            ]
          },
          "contributions": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "P": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              },
              "T": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              },
              "A": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              },
              "E": {
                "type": "integer",
                "minimum": 0,
                "maximum": 35
              }
            },
            "required": [
              "P",
              "T",
              "A",
              "E"
            ]
          },
          "adjustment": {
            "type": "integer",
            "minimum": -20,
            "maximum": 20
          },
          "version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          }
        },
        "required": [
          "value",
          "cap",
          "criteria",
          "contributions",
          "adjustment",
          "version"
        ]
      },
      "ContactSuggestionEvidence": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "collection": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "quote": {
            "type": "string",
            "maxLength": 10000,
            "nullable": true
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "nullable": true
          },
          "datePrecision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              null
            ],
            "nullable": true
          }
        },
        "required": [
          "collection",
          "id",
          "quote",
          "at",
          "occurredOn",
          "datePrecision"
        ]
      },
      "ContactSuggestionGroup": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "contact"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "identity": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "firstName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "lastName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            },
            "required": [
              "id",
              "firstName",
              "lastName"
            ]
          },
          "priority": {
            "$ref": "#/components/schemas/ContactSuggestionPriority"
          },
          "mainId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "motifs": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/ContactSuggestionMotif"
            }
          }
        },
        "required": [
          "kind",
          "id",
          "contact",
          "identity",
          "priority",
          "mainId",
          "motifs"
        ]
      },
      "ContactSuggestionPaused": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "pause"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
          },
          "motif": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "identity": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "firstName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              },
              "lastName": {
                "type": "string",
                "maxLength": 1000,
                "nullable": true
              }
            },
            "required": [
              "id",
              "firstName",
              "lastName"
            ]
          }
        },
        "required": [
          "kind",
          "id",
          "until",
          "scope",
          "volet",
          "motif",
          "contact",
          "identity"
        ]
      },
      "ContactSuggestionError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "required": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "location": {
                "type": "string",
                "enum": [
                  "query",
                  "path",
                  "body"
                ]
              }
            },
            "required": [
              "code"
            ]
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactSuggestionSettingsResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionSettings"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionSettings": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
          },
          "modes": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "finance": {
                "type": "string",
                "enum": [
                  "combined",
                  "common",
                  "personal"
                ]
              },
              "social": {
                "type": "string",
                "enum": [
                  "combined",
                  "common",
                  "personal"
                ]
              }
            },
            "required": [
              "finance",
              "social"
            ]
          },
          "isAdmin": {
            "type": "boolean"
          },
          "entries": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "$ref": "#/components/schemas/ContactSuggestionSetting"
            }
          }
        },
        "required": [
          "population",
          "modes",
          "isAdmin",
          "entries"
        ]
      },
      "ContactSuggestionSetting": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
          },
          "scope": {
            "type": "string",
            "enum": [
              "common",
              "personal"
            ],
            "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
          },
          "revision": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "draft": {
            "type": "string",
            "maxLength": 10000
          },
          "status": {
            "type": "string",
            "enum": [
              "interpreting",
              "active",
              "review",
              "error"
            ]
          },
          "active": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "version": {
                "type": "integer",
                "minimum": 0,
                "maximum": 10000000
              },
              "text": {
                "type": "string",
                "maxLength": 10000
              }
            },
            "required": [
              "version",
              "text"
            ],
            "nullable": true
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          }
        },
        "required": [
          "volet",
          "scope",
          "revision",
          "draft",
          "status",
          "active",
          "code"
        ]
      },
      "UnisoftRequest_0c53887249a3fdc8ad93": {
        "type": "object",
        "properties": {
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social"
            ],
            "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
          },
          "mode": {
            "type": "string",
            "enum": [
              "combined",
              "common",
              "personal"
            ],
            "description": "Combined combine les consignes de l’équipe et les consignes privées ; common utilise seulement celles de l’équipe ; personal utilise seulement les consignes privées. Les critères standards restent actifs dans les trois modes. Les consignes privées sont prioritaires en cas de contradiction dans la vue combinée et ne deviennent jamais un texte d’équipe."
          }
        },
        "additionalProperties": false,
        "allOf": [
          {
            "anyOf": [
              {
                "not": {
                  "required": [
                    "mode"
                  ]
                }
              },
              {
                "required": [
                  "volet"
                ]
              }
            ]
          },
          {
            "anyOf": [
              {
                "not": {
                  "required": [
                    "volet"
                  ]
                }
              },
              {
                "required": [
                  "mode"
                ]
              }
            ]
          }
        ],
        "anyOf": [
          {
            "required": [
              "population"
            ]
          },
          {
            "required": [
              "volet",
              "mode"
            ]
          }
        ]
      },
      "ContactSuggestionJobResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionJob"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionJob": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "kind": {
            "type": "string",
            "enum": [
              "analysis"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "partial",
              "failed",
              "canceled"
            ]
          },
          "population": {
            "type": "string",
            "enum": [
              "local",
              "global"
            ],
            "description": "Local désigne les contacts marqués locaux (favoris), pas des personnes situées à proximité. Global désigne tous les contacts autorisés dans l’organisation courante, jamais ceux d’autres organisations."
          },
          "volet": {
            "type": "string",
            "enum": [
              "finance",
              "social",
              "both"
            ]
          },
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          },
          "processed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "failed": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "nullable": true
          },
          "throttled": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "kind",
          "state",
          "population",
          "volet",
          "contact",
          "processed",
          "failed",
          "createdAt",
          "completedAt",
          "code",
          "throttled"
        ]
      },
      "ContactSuggestionSourceResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionSource"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionSource": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "collection": {
            "type": "string",
            "enum": [
              "contact",
              "contact_activity",
              "paiements",
              "abonnements",
              "dettes_v2",
              "forms_submit",
              "rappel",
              "custom_rappels",
              "forms",
              "caisses",
              "campagnes"
            ]
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "title": {
            "type": "string",
            "maxLength": 10000,
            "nullable": true
          },
          "text": {
            "type": "string",
            "maxLength": 10000,
            "nullable": true
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "occurredOn": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "datePrecision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              null
            ],
            "nullable": true
          },
          "details": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "amount": {
                "type": "number",
                "nullable": true
              },
              "currency": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "state": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "type": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160,
                "nullable": true
              },
              "dueAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "dueOn": {
                "type": "string",
                "format": "date",
                "nullable": true
              }
            },
            "required": [
              "amount",
              "currency",
              "state",
              "type",
              "dueAt",
              "dueOn"
            ]
          }
        },
        "required": [
          "contact",
          "collection",
          "id",
          "title",
          "text",
          "at",
          "occurredOn",
          "datePrecision",
          "details"
        ]
      },
      "ContactSuggestionPauseResultResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionPauseResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionPauseResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "partial": {
            "type": "boolean"
          },
          "results": {
            "type": "array",
            "maxItems": 400,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "scope": {
                  "type": "string",
                  "enum": [
                    "common",
                    "personal"
                  ],
                  "description": "Common désigne les consignes ou pauses de l’équipe ; personal désigne ce qui reste privé à l’utilisateur ayant consenti. Un résultat marqué commun peut encore utiliser des ajustements privés et ne doit pas être redistribué comme un résultat public d’équipe."
                },
                "volet": {
                  "type": "string",
                  "enum": [
                    "finance",
                    "social"
                  ],
                  "description": "Finance et Social classent le sujet de l’échange. Une personne peut avoir des motifs dans les deux volets."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "saved",
                    "failed"
                  ]
                }
              },
              "required": [
                "scope",
                "volet",
                "status"
              ]
            }
          }
        },
        "required": [
          "until",
          "timeZone",
          "partial",
          "results"
        ]
      },
      "ContactSuggestionResumeResultResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionResumeResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionResumeResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "resumed": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "resumed"
        ]
      },
      "ContactSuggestionInteractionResultResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactSuggestionInteractionResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactSuggestionInteractionResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "recorded": {
            "type": "boolean"
          },
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "nullable": true
          }
        },
        "required": [
          "recorded",
          "id"
        ]
      },
      "ContactExternalIdAttachResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactExternalIdMapping"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactExternalIdMapping": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "created": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "provenance": {
            "type": "string",
            "enum": [
              "INTEGRATIONS_API"
            ]
          },
          "canonicalContactField": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "system",
          "externalId",
          "contactId",
          "created",
          "createdAt",
          "provenance",
          "canonicalContactField"
        ]
      },
      "ContactExternalIdError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactExternalIdLookupResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactExternalIdLookup"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactExternalIdLookup": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "system": {
            "type": "string",
            "minLength": 2,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9._-]{1,63}$"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/ContactExternalIdLookupItem"
            }
          },
          "provenance": {
            "type": "string",
            "enum": [
              "INTEGRATIONS_API"
            ]
          },
          "canonicalContactField": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "system",
          "items",
          "provenance",
          "canonicalContactField",
          "readAt",
          "consistentSnapshot"
        ]
      },
      "ContactExternalIdLookupItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "externalId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
          },
          "state": {
            "type": "string",
            "enum": [
              "RESOLVED",
              "UNRESOLVED"
            ]
          },
          "contactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "externalId",
          "state",
          "contactId",
          "createdAt"
        ]
      },
      "UnisoftRequest_4f53ab7a631d002ee822": {
        "type": "object",
        "properties": {
          "contactIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "fields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "firstName",
                "lastName",
                "gender",
                "birthDate",
                "email",
                "phone",
                "secondaryEmails",
                "secondaryPhones",
                "tags",
                "address",
                "postalCode",
                "city",
                "region",
                "country",
                "archived",
                "deceased",
                "isNew",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "customFields": {
            "type": "array",
            "maxItems": 40,
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 120
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "TEXT",
                    "NUMBER",
                    "DATE",
                    "DATETIME",
                    "BOOL"
                  ]
                }
              },
              "required": [
                "key",
                "type"
              ],
              "additionalProperties": false
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "contactIds",
          "fields"
        ],
        "additionalProperties": false
      },
      "ContactExportResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactExportResult"
          }
        },
        "required": [
          "success",
          "data"
        ]
      },
      "ContactExportResult": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "columns": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "items": {
              "$ref": "#/components/schemas/ContactExportColumn"
            }
          },
          "rows": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactExportRow"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactExportMeta"
          }
        },
        "required": [
          "columns",
          "rows",
          "meta"
        ]
      },
      "ContactExportColumn": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "GENDER",
              "DATE",
              "EMAILS",
              "PHONES",
              "TEXT_ARRAY",
              "BOOL",
              "DATETIME",
              "NUMBER"
            ]
          }
        },
        "required": [
          "id",
          "type"
        ]
      },
      "ContactExportRow": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "cells": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "items": {
              "$ref": "#/components/schemas/ContactExportCell"
            }
          }
        },
        "required": [
          "contactId",
          "cells"
        ]
      },
      "ContactExportCell": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "columnId": {
            "type": "string"
          },
          "value": {
            "oneOf": [
              {
                "oneOf": [
                  {
                    "type": "string",
                    "nullable": true
                  },
                  {
                    "type": "number"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              },
              {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "string",
                      "nullable": true
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    }
                  ]
                }
              }
            ]
          }
        },
        "required": [
          "columnId",
          "value"
        ]
      },
      "ContactExportMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "selectedCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "order": {
            "type": "string",
            "enum": [
              "ID_ASC"
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "consistentSnapshot": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "selectedCount",
          "count",
          "hasMore",
          "nextCursor",
          "order",
          "readAt",
          "consistentSnapshot"
        ]
      },
      "ContactExportError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "UnisoftRequest_169b8464c56f9629f796": {
        "type": "object",
        "properties": {
          "tags": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            },
            "description": "Chaînes exactes de catégories observées, avec le # initial lorsqu’il existe. Ce sont des libellés, jamais des UUID de catégorie."
          },
          "tagMode": {
            "type": "string",
            "enum": [
              "any",
              "all",
              "none"
            ]
          },
          "listIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400,
              "pattern": "^[^\\u0000]+$"
            },
            "description": "Identifiants exacts des listes calculées actuelles : form:<UUID>, product:<formUUID>:<productUUID>, cagnotte:<UUID>, event:<UUID>, fundraising:<UUID>. Un UUID d’objet seul n’est pas un identifiant de liste."
          },
          "listMode": {
            "type": "string",
            "enum": [
              "any",
              "all",
              "none"
            ]
          },
          "poleIds": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid",
              "nullable": true
            },
            "description": "UUID des pôles actuels ; null désigne le pôle principal de l’organisation. Sélectionne un rattachement vivant à l’un des pôles choisis, jamais une projection enregistrée utilisée comme droit d’accès."
          },
          "customFields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/UnisoftRequest_302e8df769b310d93b74"
            }
          },
          "archived": {
            "type": "boolean",
            "description": "L’absence du filtre ou false sélectionne les contacts non marqués archivés ; true sélectionne les archivés. Ce filtre est indépendant de deceased/isNew. Un marqueur source absent reste null dans les résultats."
          },
          "deceased": {
            "type": "boolean",
            "description": "true sélectionne les contacts marqués décédés ; false ceux non marqués décédés, y compris les anciens marqueurs absents. L’omission n’impose aucun filtre deceased."
          },
          "isNew": {
            "type": "boolean",
            "description": "true sélectionne les contacts marqués nouveaux ; false ceux non marqués nouveaux, y compris les anciens marqueurs absents. Ce n’est ni un filtre de date de création ni un statut d’adhésion."
          }
        },
        "additionalProperties": false
      },
      "UnisoftRequest_302e8df769b310d93b74": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Clé exacte de champ personnalisé observée, associée à son type enregistré. La reprendre dans le catalogue de contacts autorisé ; aucune normalisation, chemin de base ou expression n’est accepté."
              },
              "type": {
                "type": "string",
                "enum": [
                  "TEXT"
                ]
              },
              "values": {
                "type": "array",
                "minItems": 1,
                "maxItems": 20,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 400,
                  "pattern": "^[^\\u0000]+$"
                }
              },
              "mode": {
                "type": "string",
                "enum": [
                  "any",
                  "all",
                  "none"
                ]
              }
            },
            "required": [
              "key",
              "type",
              "values"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Clé exacte de champ personnalisé observée, associée à son type enregistré. La reprendre dans le catalogue de contacts autorisé ; aucune normalisation, chemin de base ou expression n’est accepté."
              },
              "type": {
                "type": "string",
                "enum": [
                  "BOOL"
                ]
              },
              "value": {
                "type": "boolean"
              }
            },
            "required": [
              "key",
              "type",
              "value"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Clé exacte de champ personnalisé observée, associée à son type enregistré. La reprendre dans le catalogue de contacts autorisé ; aucune normalisation, chemin de base ou expression n’est accepté."
              },
              "type": {
                "type": "string",
                "enum": [
                  "NUMBER"
                ]
              },
              "min": {
                "type": "number",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "max": {
                "type": "number",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "key",
              "type"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "min"
                ]
              },
              {
                "required": [
                  "max"
                ]
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Clé exacte de champ personnalisé observée, associée à son type enregistré. La reprendre dans le catalogue de contacts autorisé ; aucune normalisation, chemin de base ou expression n’est accepté."
              },
              "type": {
                "type": "string",
                "enum": [
                  "DATE"
                ]
              },
              "from": {
                "type": "string",
                "format": "date"
              },
              "to": {
                "type": "string",
                "format": "date"
              }
            },
            "required": [
              "key",
              "type"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "from"
                ]
              },
              {
                "required": [
                  "to"
                ]
              }
            ]
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120,
                "pattern": "^[^\\u0000]+$",
                "description": "Clé exacte de champ personnalisé observée, associée à son type enregistré. La reprendre dans le catalogue de contacts autorisé ; aucune normalisation, chemin de base ou expression n’est accepté."
              },
              "type": {
                "type": "string",
                "enum": [
                  "DATETIME"
                ]
              },
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "key",
              "type"
            ],
            "additionalProperties": false,
            "anyOf": [
              {
                "required": [
                  "from"
                ]
              },
              {
                "required": [
                  "to"
                ]
              }
            ]
          }
        ]
      },
      "ContactDiscoveryError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          },
          "field": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactCatalogTagResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogTag"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogTag": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "tag": {
            "type": "string",
            "minLength": 1,
            "maxLength": 400
          }
        },
        "required": [
          "tag"
        ]
      },
      "ContactCatalogMeta": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "generation": {
            "type": "string",
            "nullable": true
          },
          "computedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "meaning": {
            "type": "string",
            "enum": [
              "VALID_OBSERVED_VALUES_NOT_VALIDATION_RULES",
              "CURRENT_AUTHORISED_CALCULATED_LISTS",
              "CURRENT_POLE_IDENTIFIERS"
            ]
          }
        },
        "required": [
          "count",
          "hasMore",
          "nextCursor",
          "readAt",
          "generation",
          "computedAt",
          "meaning"
        ]
      },
      "ContactCatalogError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "ContactCatalogFieldResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogField"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogField": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "NUMBER",
              "DATE",
              "DATETIME",
              "BOOL"
            ]
          },
          "operators": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hasObservedValues": {
            "type": "boolean"
          },
          "unit": {
            "type": "string",
            "enum": [
              "NATIVE_UNSPECIFIED",
              null
            ],
            "nullable": true
          }
        },
        "required": [
          "key",
          "type",
          "operators",
          "hasObservedValues",
          "unit"
        ]
      },
      "ContactCatalogValueResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogValue"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogValue": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "type": {
            "type": "string",
            "enum": [
              "TEXT"
            ]
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 400
          }
        },
        "required": [
          "key",
          "type",
          "value"
        ]
      },
      "ContactCatalogListResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogList"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "form",
              "product",
              "cagnotte",
              "event",
              "fundraising"
            ]
          },
          "sourceId": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "historyIncomplete": {
            "type": "boolean"
          },
          "availableForSearch": {
            "type": "boolean"
          },
          "requiredScopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "kind",
          "sourceId",
          "label",
          "historyIncomplete",
          "availableForSearch",
          "requiredScopes"
        ]
      },
      "ContactCatalogPoleResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ContactCatalogPole"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/ContactCatalogMeta"
          }
        },
        "required": [
          "success",
          "data",
          "meta"
        ]
      },
      "ContactCatalogPole": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "main": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "label",
          "main"
        ]
      },
      "ContactTagCommandCapabilitiesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTagCommandCapabilities"
          }
        }
      },
      "ContactTagCommandCapabilities": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resource",
          "identity",
          "supported",
          "actions",
          "previewAvailable",
          "applyAvailable",
          "maximumObservedRecords"
        ],
        "properties": {
          "resource": {
            "type": "string",
            "enum": [
              "ORGANISATION_TAG"
            ]
          },
          "identity": {
            "type": "string",
            "enum": [
              "EXACT_LABEL"
            ]
          },
          "supported": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "actions": {
            "type": "array",
            "minItems": 3,
            "maxItems": 3,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "RENAME",
                "MERGE",
                "REMOVE"
              ]
            }
          },
          "previewAvailable": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "applyAvailable": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "maximumObservedRecords": {
            "type": "integer",
            "enum": [
              5000
            ]
          }
        }
      },
      "ContactTagCommandPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTagCommandPreview"
          }
        }
      },
      "ContactTagCommandPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "command",
          "revision",
          "observedAt",
          "counts",
          "affectedRecords",
          "savedAudiencesUpdated",
          "accessRestrictionsPreservedOnRemoval",
          "snapshotGuaranteed",
          "poleRestrictionsEmptied"
        ],
        "properties": {
          "command": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "action",
              "sourceTag",
              "targetTag"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "RENAME",
                  "MERGE",
                  "REMOVE"
                ]
              },
              "sourceTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "targetTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500,
                "nullable": true
              }
            }
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "counts": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "contacts",
              "legacyAppointments",
              "sharedTagSets",
              "accessRestrictions",
              "poleRestrictions"
            ],
            "properties": {
              "contacts": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "legacyAppointments": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "sharedTagSets": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "accessRestrictions": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              },
              "poleRestrictions": {
                "type": "object",
                "nullable": true,
                "additionalProperties": false,
                "required": [
                  "sourceRecords",
                  "targetRecords"
                ],
                "properties": {
                  "sourceRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  },
                  "targetRecords": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5000
                  }
                }
              }
            }
          },
          "affectedRecords": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5000
          },
          "savedAudiencesUpdated": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "accessRestrictionsPreservedOnRemoval": {
            "type": "boolean"
          },
          "snapshotGuaranteed": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "poleRestrictionsEmptied": {
            "type": "integer",
            "minimum": 0,
            "maximum": 5000
          }
        }
      },
      "ContactTagCommandReceiptResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ContactTagCommandReceipt"
          }
        }
      },
      "ContactTagCommandReceipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "command",
          "state",
          "phase",
          "canRetry",
          "error",
          "remainingSourceRecords",
          "verifiedRecords",
          "startedAt",
          "finishedAt"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "command": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "action",
              "sourceTag",
              "targetTag"
            ],
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "RENAME",
                  "MERGE",
                  "REMOVE"
                ]
              },
              "sourceTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              },
              "targetTag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500,
                "nullable": true
              }
            }
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "REJECTED",
              "PARTIAL",
              "UNKNOWN"
            ]
          },
          "phase": {
            "type": "string"
          },
          "canRetry": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "remainingSourceRecords": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 5000
          },
          "verifiedRecords": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "maximum": 5000
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format : `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
