Rinne API Documentation

An onboarding document is a file about a subject: a person’s CPF, the merchant’s CNPJ, or the CPF of a merchant that is a natural person. It belongs to your organization, it is not tied to any provider or affiliation, and it is reused wherever the same subject and type are required, across every merchant of your organization and every later attempt. How to upload one, step by step: Build with the API. The onboarding link uploads through the same calls.

Document types

Type	What it is	Satisfies
`CNH_DIGITAL`	The digital driver’s license, one PDF with its QR code	`IDENTITY_DOCUMENT` alone
`CNH_FRONT`, `CNH_BACK`	Front and back of a physical driver’s license	`IDENTITY_DOCUMENT`, as a pair
`RG_FRONT`, `RG_BACK`	Front and back of an identity card	`IDENTITY_DOCUMENT`, as a pair
`RNE_FRONT`, `RNE_BACK`	Front and back of a foreigner’s identity card	`IDENTITY_DOCUMENT`, as a pair
`SELFIE`	The selfie an approved biometric verification stores	Nothing on its own; the verification satisfies `BIOMETRIC_VERIFICATION`
`ARTICLES_OF_INCORPORATION`	The merchant’s constitutive document: the consolidated contrato social or the estatuto social	`ARTICLES_OF_INCORPORATION`
`POWER_OF_ATTORNEY`	The document that lets the contact represent the merchant	`POWER_OF_ATTORNEY`
`PROOF_OF_ADDRESS`	A proof of address	`PROOF_OF_ADDRESS`
`PROOF_OF_INCOME`	A proof of income	`PROOF_OF_INCOME`
`FINANCIAL_STATEMENT`	A financial statement	`FINANCIAL_STATEMENT`
`OTHER`	Anything else, including the files attached to an `EVIDENCE_PACKAGE`	`OTHER`

A provider’s own capture can also produce RNM_FRONT, RNM_BACK, ID_DOCUMENT_FRONT and ID_DOCUMENT_BACK. You never upload these types (400), and they satisfy no requirement.

Accepted files

Formats: PDF, PNG or JPEG. Rinne checks the bytes against the declared content_type.
Size: up to 10 MB per file.
One file per document: each side of an identity document is its own document, one image or one PDF. A side that spans several pages is refused by the provider.

Status

Status	Meaning	What to do
`PENDING_UPLOAD`	The upload is open and nothing was received yet. The upload URL works for 15 minutes; after that the document leaves the list	`PUT` the file and call `complete`, or open a new upload
`NOT_VALIDATED`	Stored and checked for format and size. Usable, and counted toward its requirement; no provider has approved an affiliation with it yet	Nothing
`VALIDATED`	Part of an affiliation a provider approved. A later refusal leaves it `VALIDATED`, except on a shared document, which a refusal makes `REJECTED`	Nothing
`REJECTED`	A provider refused it and none approved it; `rejections` says which, why and in which affiliation. Providers that have not refused it still use it	Upload a new one for the same subject and type, for the provider that refused it
`SUPERSEDED`	A newer upload of the same subject and type replaced it (`superseded_by_id`), or Rinne closed an upload that expired with nothing received	Nothing

Replacing a document

A document is never edited in place. To correct one, upload a new document for the same subject and type: when it completes, the previous one becomes SUPERSEDED and the new one is used from then on. An affiliation already submitted keeps the document it sent. Uploading the very same file again for the same subject and type creates nothing new: complete answers 201 with the document already stored, and the upload you opened becomes SUPERSEDED by it. Only your own uploads replace one another. A selfie captured by a biometric verification, a shared document and the attachments of an evidence package stay as they are.

When a provider refuses a document

A refusal is recorded per provider, in rejections:

{
  "rejections": [
    {
      "provider": "CELCOIN",
      "affiliation_id": "2352ebe5-97c2-4625-8535-cc21b732787a",
      "reason_code": "DOCUMENT_UNREADABLE",
      "message": "Documento ilegível",
      "rejected_at": "2026-10-03T14:10:00.000Z"
    }
  ]
}

Your organization never sends a refused document to that provider again, for any of its merchants, and the requirement it satisfied reads REJECTED until a new one arrives. Providers that have not refused it keep using it, and an approval by one of them makes it VALIDATED. See When the provider asks for more.

Where a document comes from

`source`	Meaning
`UPLOAD`	Uploaded by your integration or through the onboarding link
`PROVIDER`	Produced by a provider’s capture, such as the `SELFIE` of an approved biometric verification
`SHARED`	A reference to a document another organization already had validated for the same person or merchant

Shared documents

When a requirement is still pending and another organization already had a document of the same type validated for the same person or merchant, Rinne can satisfy the requirement with it. Your organization receives a SHARED document of its own: its own id, the type, the subject and the status, and nothing else. It arrives VALIDATED and becomes REJECTED if one of your organization’s providers refuses it. It has no file name, no size, no download_url, and nothing about the organization that uploaded it. The same holds the other way: an organization that receives one of your documents sees only its type, subject and status, never the file, who uploaded it or its refusals. A shared document never replaces your own: an upload of the same type stays current beside it. To stop sharing your organization’s validated documents, ask Rinne support.

Read and download

GET /v1/onboarding-documents lists your documents, newest first, with the standard pagination. Filter by company_id or by subject_document_number. An upload that expired before complete is left out of the list. GET /v1/onboarding-documents/{id} adds download_url and download_url_expires_at, a signed link to the file valid for one hour. It is null before the upload completes and on a SHARED document. A merchant using its own API key downloads only the documents presented for it.

Documents cannot be deleted through the API, since they are onboarding evidence. Send erasure requests to Rinne support.

Rinne’s own screening

Each document carries screening and screening_note, Rinne’s own check of a file before any provider reads it: PENDING, then PASSED or FAILED with a note saying why. A FAILED document satisfies no requirement and its requirement reads REJECTED. While Rinne does not screen documents, both fields are null.

Events

onboarding-document.status-changed fires on every status change after creation, with the document as payload.entity. It reaches the merchant the document was presented for and, when that merchant is not your organization itself, your organization too. See Statuses and events.

Overview

Choose your integration

Building blocks

Lifecycle

Documents

Document types

Accepted files

Status

Replacing a document

When a provider refuses a document

Where a document comes from

Shared documents

Read and download

Rinne’s own screening

Events

​Document types

​Accepted files

​Status

​Replacing a document

​When a provider refuses a document

​Where a document comes from

​Shared documents

​Read and download

​Rinne’s own screening

​Events

Document types

Accepted files

Status

Replacing a document

When a provider refuses a document

Where a document comes from

Shared documents

Read and download

Rinne’s own screening

Events