Rinne API Documentation

Rinne runs Know Your Customer (KYC) checks automatically whenever a merchant company is created or has its identification data updated. The checks compare the merchant’s registration data against trusted data sources and evaluate a set of verification rules. Results are delivered to the parent organization through the kyc.completed webhook.

KYC results are informational. They never block company creation or updates—the merchant resource is created or updated regardless of the outcome. Your organization decides how to act on the findings (for example, pausing onboarding or requesting corrected data).

When KYC runs

Checks are triggered automatically for merchant companies—you never start a check yourself:

On creation: every new merchant is checked.
On update: a new check runs only when a KYC-relevant field changes—the tax document type, the legal/full name, or the contact information. Other updates do not trigger a re-check.

Organization-type companies are not checked. Each qualifying create or update produces a new, independent check and its own kyc.completed webhook.

Check types

The set of rules evaluated depends on the merchant’s document type, reported as kyc_type in the webhook:

NATURAL_PERSON_COMPANY: the merchant is an individual (CPF).
LEGAL_PERSON_COMPANY: the merchant is a legal entity (CNPJ). Rules also cover the registered contact person and the company’s ownership structure.

Rule results

Each rule execution reports a status:

Status	Meaning
`PASSED`	The data source confirms the merchant’s data for this rule.
`ISSUES_FOUND`	A discrepancy or risk signal was found—review it and decide how to proceed.
`FAILED`	The rule could not be evaluated for this specific field (for example, the data source timed out or returned no value). Treat it as inconclusive, not as a problem with the merchant.

Every rule execution includes the expected values required to pass and, unless the underlying data was unavailable, the received values actually observed. A human-readable description is included whenever the rule does not pass.

A systemic failure at the data source (for example, a malformed provider response) does not produce a kyc.completed webhook with all-FAILED rules. Rinne aborts the check, retries the message, and only delivers kyc.completed once the check runs against a valid response.If you do not see a kyc.completed webhook within your usual window after a merchant is created or updated, either the check is still being retried or it completed and its webhook delivery is delayed or failed. To tell them apart, list the merchant’s checks with GET /v1/merchants/{merchantId}/kyc-checks, which returns only checks that have run, newest first. The history also holds the merchant’s earlier checks, so look for a check whose created_at is later than the create or update you are waiting on:

Such a check is listed: the check completed and the webhook delivery is delayed or failed. Look up its kyc.completed event in the delivery history of your webhook dashboard, where you can replay it, and see Retry behavior for the delivery schedule.
No such check is listed: the check has not completed yet and is still being retried, even if older checks appear. Its kyc.completed webhook arrives once it runs.

Rules for natural persons

Rule	Verifies
`DOCUMENT_NUMBER_VALID`	The CPF exists
`DOCUMENT_STATUS_VALID`	The CPF is in a regular status
`FULL_NAME_CORRECT`	The provided name matches the document holder
`DATE_OF_BIRTH_CORRECT`	The provided date of birth matches the document holder
`IS_ALIVE`	The document holder is not deceased
`HAS_SANCTIONS`	The document holder is not sanctioned or politically exposed

Rules for legal entities

Rule	Verifies
`LEGAL_DOCUMENT_NUMBER_VALID`	The CNPJ exists
`LEGAL_DOCUMENT_STATUS_VALID`	The CNPJ is in a regular status
`LEGAL_NAME_CORRECT`	The provided legal name matches the registration
`LEGAL_HAS_SANCTIONS`	The entity is not sanctioned
`COMPANY_TYPE_CORRECT`	The declared company type matches the registration
`IS_CONTACT_REPRESENTATIVE`	The registered contact is a representative of the entity
`NO_SHAREHOLDERS_RESTRICTIONS`	No restrictions found on the entity’s shareholders

For legal entities, the registered contact person (CPF) is also verified with contact-scoped counterparts of the natural-person rules: CONTACT_DOCUMENT_NUMBER_VALID, CONTACT_DOCUMENT_STATUS_VALID, CONTACT_FULL_NAME_CORRECT, CONTACT_DATE_OF_BIRTH_CORRECT, CONTACT_IS_ALIVE, and CONTACT_HAS_SANCTIONS.

The exact set of rules executed comes from the KYC policy applied to the check, identified by policy_id and policy_name in the webhook payload. Handle the rule_executions array dynamically rather than expecting a fixed list.

The `kyc.completed` webhook

The webhook is delivered to the parent organization using the same envelope, Svix signatures, and retry behavior as every other Rinne event (see Webhooks). In the envelope, company_id is the merchant that was checked and correlation_id equals the kyc_check_id.

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "kyc.completed",
  "version": 1,
  "timestamp": "2025-01-15T10:30:00.000Z",
  "source": "kyc",
  "company_id": "889fd9b3-1634-429a-b54f-eaa0004345cd",
  "correlation_id": "d01c7832-b63c-4cb6-90b0-74e821f7123e",
  "payload": {
    "kyc_check_id": "d01c7832-b63c-4cb6-90b0-74e821f7123e",
    "company_id": "889fd9b3-1634-429a-b54f-eaa0004345cd",
    "policy_id": "cb350742-a9b8-4a3c-9d7a-02aa8cbb24cb",
    "policy_name": "rinne-default-natural-person",
    "kyc_type": "NATURAL_PERSON_COMPANY",
    "rule_executions": [
      {
        "rule_name": "DOCUMENT_NUMBER_VALID",
        "status": "PASSED",
        "expected": { "document_exists": true },
        "received": { "document_exists": true }
      },
      {
        "rule_name": "HAS_SANCTIONS",
        "status": "ISSUES_FOUND",
        "expected": { "is_sanctioned": false, "is_pep": false },
        "received": { "is_sanctioned": true, "is_pep": false },
        "description": "Document holder is currently sanctioned"
      }
    ]
  }
}

Payload fields

kyc_check_id: Unique ID of this check run
company_id: The merchant company that was checked
policy_id / policy_name: The KYC policy that defined the rules
kyc_type: NATURAL_PERSON_COMPANY or LEGAL_PERSON_COMPANY
rule_executions: One entry per rule in the policy—rule_name, status, expected, and received (omitted only if the underlying data was unavailable); description is included when the rule does not pass

Delivery is at-least-once. Use the event id for idempotency, and kyc_check_id to group rule results belonging to the same check when a merchant is checked more than once.

Retrieve past checks

Read a merchant’s KYC history from your organization account with GET /v1/merchants/{merchantId}/kyc-checks. Results are paginated and returned newest first. Each entry mirrors the rule outcomes delivered by the kyc.completed webhook, so you can rebuild a merchant’s KYC state without persisting webhook payloads.

This endpoint is for organization callers only. Merchant-scoped credentials receive 403. Requests scoped to a merchant that belongs to another organization return 404.

Permission

The endpoint requires the merchant.kyc.list permission. It is also matched by the merchant.kyc.* and merchant.* wildcards on any credential, and by the *.* wildcard on API keys only. Organization JWT roles reject *.* with 400 at role creation, so a JWT role must list merchant.kyc.list, merchant.kyc.*, or merchant.*.

Historical policy pinning

The policy applied to a check is captured at execution time. Historical checks keep their original rule set and outcomes even after the KYC policy changes, so reconcile results using the policy_id and policy_name recorded on each check rather than the current policy.

Empty history

A merchant with no recorded checks returns 200 with an empty data array and pagination reporting total: 0 and totalPages: 0. New merchants are checked on creation, so this case normally appears only when a check has not finished writing yet.

What the response includes

Row identifiers (id), timestamps (created_at), the merchant company_id, the policy that was in effect (policy_id, policy_name), the merchant type (kyc_type), and the rule_executions array with per-rule status, expected, received, and description.

What the response excludes

The merchant snapshot captured at check time, the idempotency key used to deduplicate provider calls, and raw data returned by the external verification provider. These fields never leave the API.

Full request and response shapes, query parameters, and every status code live in the API reference entry.

Next steps

Webhooks

Endpoint setup, Svix signature verification, and retries

Organizations and merchants

How merchants relate to your organization

Affiliations

Provider onboarding and document requirements

API reference

Full kyc.completed event schema under Webhooks → Events

Getting started

Core concepts

Guides

KYC Verification

When KYC runs

Check types

Rule results

Rules for natural persons

Rules for legal entities

The `kyc.completed` webhook

Payload fields

Retrieve past checks

Permission

Historical policy pinning

Empty history

Next steps

Webhooks

Organizations and merchants

Affiliations

API reference

​When KYC runs

​Check types

​Rule results

​Rules for natural persons

​Rules for legal entities

​The kyc.completed webhook

​Payload fields

​Retrieve past checks

​Permission

​Historical policy pinning

​Empty history

​Next steps

Webhooks

Organizations and merchants

Affiliations

API reference

When KYC runs

Check types

Rule results

Rules for natural persons

Rules for legal entities

The `kyc.completed` webhook

Payload fields

Retrieve past checks

Permission

Historical policy pinning

Empty history

Next steps