Contact (contact)

Rôle

Le contact sépare le contact professionnel de l'entité légale. Une company (société, entreprise) peut avoir plusieurs contacts — représentant légal, autorisateur de paiement, contact de facturation — chacun avec ses propres informations et son propre niveau de vérification.

Les vérifications KYC, AML, PEP, sanctions ou liveness sont enregistrées dans des compliance_check liés au contact, jamais recopiées sur celui-ci. Un contact peut être recherché par email et résolu par rôle dans les processus d'orchestration.

Identifiant et structure

Chaque contact porte un identifiant stable préfixé par ctc_. Il référence sa company parente via company_id.

{
  "object": "contact",
  "id": "ctc_d12e3f4a5b6c7d8e",
  "company_id": "cmp_3a8f1d9c2b4e7f6a",
  "full_name": "Marie Dupont",
  "first_name": "Marie",
  "last_name": "Dupont",
  "email": "marie.dupont@dupont-industries.fr",
  "phone": "+33612345678",
  "job_title": "Directrice financière",
  "preferred_locale": "fr-FR",
  "suspended": false,
  "suspended_at": null,
  "suspension_reason": null,
  "source_reference": "RH-00421",
  "metadata": {},
  "created_at": "2026-01-12T10:00:00.000Z",
  "updated_at": "2026-03-05T14:20:00.000Z"
}

Champs

Identité et conformité

Les résultats réglementaires ne sont pas des propriétés intrinsèques du contact. Chaque vérification produit un compliance_check avec subject_type=contact, l'ID du contact dans subject_id, une nature dans check_type et un résultat normalisé dans result.

Suspension

Une personne peut devoir cesser d'agir pour une company sans pour autant disparaître de la base : alerte sanctions, soupçon de fraude, accès compromis, départ des effectifs. Supprimer le contact ferait perdre l'historique de ses actes passés — commandes, factures, dossiers d'entrée en relation, contrôles de conformité. La suspension répond à ce besoin : elle neutralise le contact sans rien effacer.

POST /v1/contacts/ctc_d12e3f4a5b6c7d8e/suspend
Content-Type: application/json

{
  "reason": "sanctions_match"
}

Un contact suspendu :

• n'est plus retourné par GET /v1/companies/:id/contacts/resolve, sauf include_suspended=true — les nodes de résolution basculent donc sur la route not_found ;
• ne peut plus recevoir de nouveau contact_role : la création répond 409 ;
• reste lisible et modifiable, pour pouvoir corriger ses données et lever la suspension.

POST /v1/contacts/:id/reactivate lève la suspension et efface suspended_at et suspension_reason.

Les événements contact.suspended et contact.reactivated permettent de déclencher un processus, par exemple pour repartir en collecte d'un nouveau signataire quand un dossier en cours perd le sien.

Mode brouillon

Pendant un parcours d'entrée en relation, les données du contact sont collectées progressivement par l'utilisateur final avant qu'une company n'existe encore. La plateforme prend en charge ce cas via le mode brouillon : un contact en brouillon porte le même payload métier, sans identifiant, et n'est pas encore rattaché à une company définitive.

Dans les processus, le brouillon circule avec le type platform.contact (draft). Le node submit_contact le convertit en contact engagé dès qu'une company est disponible :

[Collecte contact (draft)] → [Créer company] → [Submit contact]
                                                         ↓
                                               contact (engagé, ctc_…)

Les nodes KYC (vérification d'identité, liveness, SIRENE) acceptent également les drafts en entrée — la vérification peut donc démarrer avant la soumission finale.

Relations

La résolution d'un contact par rôle et niveau de certification est documentée dans la section Dans les processus ci-dessous et dans la page company (endpoint GET /v1/companies/:id/contacts/resolve).

Dans les processus

Résolution par rôle

Le node resolve_contact identifie le meilleur contact d'une company parmi ses rôles actifs (non révoqués, dans la fenêtre valid_from / valid_until). La stratégie de sélection détermine lequel retenir quand plusieurs candidats correspondent :

En cas de succès, la route found produit selected_contact, selected_contact_role, selected_role_type et other_candidates.

Recherche par email

GET /v1/contacts/search
  ?merchant_id=mrc_1a2b
  &email=marie.dupont@dupont-industries.fr

{
  "object": "contact_search_result",
  "contact": {
    "id": "ctc_d12e",
    "email": "marie.dupont@dupont-industries.fr"
  }
}

Si deux contacts partagent le même email, la recherche retourne une erreur 409 duplicate_contact_match. L'ajout du paramètre company_id restreint la recherche à une company donnée et évite ce conflit.

Événements

Les changements du contact et les décisions de conformité utilisent des familles d'événements distinctes. Les décisions sont émises par compliance_check.*.

Chaque événement inclut l'objet contact complet dans son payload. La configuration des webhooks est décrite dans Recevoir des webhooks.