Rôle de contact (contact_role)

Rôle

Un même contact peut détenir plusieurs rôles sur une même company — par exemple être à la fois legal_representative et beneficial_owner. Chaque rôle est un objet distinct avec son propre cycle de vie : certification progressive, fenêtre de validité, révocation.

Les rôles sont l'entrée d'interrogation clé pour la résolution de contacts dans les processus : le node resolve_contact et l'endpoint GET /v1/companies/:id/contacts/resolve filtrent sur les rôles actifs pour identifier le bon interlocuteur au bon moment.

Identifiant et structure

Chaque rôle porte un identifiant stable préfixé par ctr_. Il référence à la fois la company parente et le contact détenteur.

{
  "object": "contact_role",
  "id": "ctr_9b4c2a7e1f3d8c5b",
  "company_id": "cmp_3a8f1d9c2b4e7f6a",
  "contact_id": "ctc_d12e3f4a5b6c7d8e",
  "role_type": "legal_representative",
  "certification_level": "verified",
  "max_power_amount": null,
  "authorized_acts": null,
  "valid_from": null,
  "valid_until": null,
  "revoked_at": null,
  "source_reference": null,
  "metadata": {},
  "created_at": "2026-01-12T10:30:00.000Z",
  "updated_at": "2026-03-01T09:00:00.000Z"
}

Exemple avec un rôle proxy portant une délégation de pouvoir bornée :

{
  "object": "contact_role",
  "id": "ctr_1c2d3e4f5a6b7c8d",
  "company_id": "cmp_3a8f1d9c2b4e7f6a",
  "contact_id": "ctc_e5f6a7b8c9d0e1f2",
  "role_type": "proxy",
  "certification_level": "certified",
  "max_power_amount": 5000000,
  "authorized_acts": ["sign_invoices", "approve_payments"],
  "valid_from": "2026-01-01",
  "valid_until": "2026-12-31",
  "revoked_at": null,
  "source_reference": "PROC-2026-001",
  "metadata": {},
  "created_at": "2026-01-05T08:00:00.000Z",
  "updated_at": "2026-01-05T08:00:00.000Z"
}

Champs

Types de rôles

Les onze types de rôles se divisent en deux catégories selon qu'ils peuvent être attestés par une source tierce.

Rôles certifiables

Ces rôles peuvent atteindre le niveau certified via un registre officiel ou un document légal. Ils sont prioritaires dans les processus KYB et de conformité.

Rôles opérationnels

Ces rôles qualifient la fonction d'un contact pour le routing interne des notifications et des accès. Ils ne sont pas certifiables par un tiers et restent au niveau declarative.

Niveau de certification

Le champ certification_level indique avec quelle rigueur le rôle a été attesté. Il progresse de declarative vers certified à mesure que les vérifications avancent ; il ne régresse pas.

Le node resolve_contact accepte un paramètre certification_levels pour ne retenir que les rôles atteignant un niveau minimum, et la stratégie most_certified sélectionne automatiquement le contact au niveau le plus élevé parmi les candidats.

Fenêtre de validité

Les champs valid_from et valid_until délimitent la période pendant laquelle un rôle est actif. Les deux sont optionnels et indépendants :

• valid_from: null — le rôle est actif dès sa création.
• valid_until: null — le rôle n'a pas de date d'expiration.
• valid_until doit être supérieure ou égale à valid_from si les deux sont renseignées.

La résolution de contacts (node resolve_contact et endpointGET /v1/companies/:id/contacts/resolve) prend un paramètre at (date de référence, par défaut maintenant) et n'inclut que les rôles dont la fenêtre couvre cette date. Cela permet par exemple d'interroger qui était payment_authorizer à la date d'une transaction passée.

GET /v1/companies/cmp_3a8f/contacts/resolve
  ?role_types=payment_authorizer
  &at=2026-03-15T12:00:00Z

{
  "object": "list",
  "data": [
    {
      "contact": {
        "id": "ctc_d12e",
        "email": "marie.dupont@example.com"
      },
      "contact_role": {
        "id": "ctr_9b4c",
        "role_type": "payment_authorizer",
        "certification_level": "declarative",
        "valid_from": "2026-01-01",
        "valid_until": "2026-12-31"
      },
      "matched_role_type": "payment_authorizer"
    }
  ],
  "has_more": false
}

Révocation

Un rôle se révoque en passant { "revoke": true } dans la mise à jour. La plateforme horodate revoked_at et exclut immédiatement le rôle de toute résolution future.

POST /v1/contact-roles/ctr_9b4c

{
  "revoke": true
}

{
  "id": "ctr_9b4c",
  "revoked_at": "2026-06-17T10:00:00.000Z"
}

Un rôle révoqué ne peut plus être mis à jour. Si le même contact doit retrouver un rôle identique, il faut créer un nouveau contact_role.

La révocation émet l'événement contact_role.revoked que vos processus peuvent écouter pour réagir (retrait d'accès portail, notification de fin de mandat…).

Dans les processus

Événements

Contrairement à contact_role.created et contact_role.revoked qui se déclenchent à chaque opération, contact_role.certified n'est émis qu'une seule fois — lors du premier passage à certified. Les mises à jour ultérieures à ce niveau ne le redéclenchent pas.

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