Contact role ( contact_role )

Role

The same contact may hold several roles for the same company — for example both legal_representative and beneficial_owner. Each role is a separate object with its own lifecycle: progressive certification, validity window, revocation.

Roles are the key query entry point for resolving contacts in processes: the resolve_contact node and the GET /v1/companies/:id/contacts/resolve endpoint filter active roles to identify the right person at the right time.

Identifier and structure

Each role has a stable identifier prefixed with ctr_. It references both the parent company and the contact holding the role.

{
"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"
}

Example with a proxy role carrying bounded delegated authority:

{
"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"
}

Fields

Role types

The eleven role types split into two categories according to whether they can be attested by a third-party source.

Certifiable roles

These roles may reach the certified level through an official registry or legal document. They have priority in KYB and compliance processes.

Operational roles

These roles qualify a contact's function for internal routing of notifications and access. They are not third-party certifiable and remain at the declarative.

Certification level

The field certification_level indicates how rigorously the role has been attested. It progresses from declarative to certified as checks advance and never regresses.

The node resolve_contact accepts a parameter certification_levels to retain only roles reaching a minimum level, and the strategy most_certified automatically selects the contact with the highest level among candidates.

Validity window

The fields valid_from and valid_until delimit the period during which a role is active. Both are optional and independent:

• valid_from: null — the role is active from creation.

• valid_until: null — the role has no expiration date.

• valid_until must be greater than or equal to valid_from when both are supplied.

Contact resolution (node resolve_contact and endpoint GET /v1/companies/:id/contacts/resolve) takes a parameter at (reference date, defaulting to now) and includes only roles whose window covers that date. This makes it possible, for example, to ask who was payment_authorizer at the date of a past transaction.

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
}

Revocation

A role is revoked by setting { "revoke": true } in the update. The platform timestamps revoked_at and immediately excludes the role from future resolution.

POST /v1/contact-roles/ctr_9b4c

{
"revoke": true
}

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

A revoked role can no longer be updated. If the same contact must regain an identical role, create a new contact_role.

Revocation emits the event contact_role.revoked that your processes can consume to react — for example removing portal access or notifying that a mandate ended.

In processes

Events

Unlike contact_role.created and contact_role.revoked events emitted on every operation, contact_role.certified is emitted only once — on the first transition to certified. Subsequent updates at this level do not trigger it again.

Every event includes the complete contact_role complete object. Webhook configuration is described in Receive webhooks.