Skip to main content
The onboarding API is the set of building blocks the onboarding link runs on. Use it to put onboarding inside your own product, to supply documents you already hold, or to automate the whole flow. The blocks do not depend on each other or on any order. A document uploaded today satisfies an affiliation created next month, and a biometric verification approved before the affiliation exists is already counted when it is created.

​
Before you start

  • Who the calls act on. Every route exists in two forms. The root path (/v1/onboarding-requirements) acts on the authenticated merchant: your organization onboarding itself, or a merchant with its own API key. The same path under /v1/merchants/{merchantId} is for an organization acting on one of its merchants, with the same body and response. The examples below use the merchant form.
  • Permissions. Each route requires its own permission, named on its reference page: onboarding-requirement.list and onboarding-requirement.edit, onboarding-document.create, onboarding-document.list and onboarding-document.view, biometric-verification.create, biometric-verification.list and biometric-verification.view, with a merchant. twin of each for the merchant routes.
  • The merchant’s contact. Requirements about a person name the merchant’s registered contact, and only that person can be verified. Register the contact’s CPF when you create the merchant.

​
1. Read what is pending

GET /v1/onboarding-requirements?provider=CELCOIN returns the merchant’s requirements for that provider, each with its status and what satisfies it. Reading it is optional, but it is the one call that tells you exactly what to collect and what Rinne already holds, from this merchant, another merchant of your organization, or an earlier attempt.
Here the contact’s identity document is already on file, so only the biometric verification and the merchant’s articles of incorporation are left. Each requirement type, status and origin is described in Requirements.

​
2. Upload documents

A document is uploaded in three calls: open the upload, send the bytes to the signed URL it returns, and confirm. Upload each document under the CPF or CNPJ it is about (subject_document_number), whenever you have it, before or after the affiliation exists.
1

Open the upload

cURL
201 Created
2

Send the file to upload_url

upload_url is a signed PUT valid for 15 minutes. Send the bytes with these three headers, all signed into the URL:
cURL
Content-Type must equal the content_type you declared. A file over 10 MB is refused here, and a second PUT answers 412 while a file is already behind the URL.
3

Confirm the upload

cURL
Rinne checks that the file is a PDF, PNG or JPEG of at most 10 MB whose bytes match the declared type, and the document becomes NOT_VALIDATED: stored, usable, and counted toward its requirement.
The response is 201 with status NOT_VALIDATED and file_size_bytes filled, and onboarding-document.status-changed fires. The ARTICLES_OF_INCORPORATION requirement now reads SATISFIED. If the merchant already held the same file for the same subject and type, the 201 carries that existing document with its current status instead, and the one you opened is closed as SUPERSEDED.
The same three steps in Node.js:
upload-document.js
An identity document is satisfied by a CNH_DIGITAL alone, or by the front and back of one document: CNH_FRONT with CNH_BACK, RG_FRONT with RG_BACK, or RNE_FRONT with RNE_BACK. Upload each side as its own document, one image or one PDF per side. All document types and statuses: Documents.

​
3. Run the biometric verification

The biometric verification is a selfie with a liveness and face-match check of the merchant’s contact, done live by the person on the provider’s own capture page. It is the one item a person has to do themselves.
1

Check whether a capture is needed

The BIOMETRIC_VERIFICATION requirement from step 1 decides: SATISFIED means an approved verification already serves this merchant, since one serves every merchant of your organization where that person is the contact, and there is nothing to do. When it is PENDING, list the person’s verifications to follow one that is still PENDING instead of starting another:
cURL
An APPROVED verification of the person does not settle it on its own: when Rinne could not store its selfie within a day of the approval, the requirement goes back to PENDING and the person does it again. Go by the requirement’s status.
2

Start a verification

cURL
201 Created
3

Hand verification_url to the person

Open it on the person’s phone or send it to them, in a browser tab of its own: the provider’s page does not run inside a frame. It works until verification_url_expires_at; read that field rather than assuming a lifetime. redirect_url is optional and is where the person lands when the capture ends.
4

Receive the result

The result arrives by the biometric-verification.status-changed webhook and on GET .../biometric-verifications/{id}, never through the redirect.
APPROVED stores the selfie as a SELFIE document (selfie_onboarding_document_id) and satisfies the BIOMETRIC_VERIFICATION requirement. REPROVED carries the provider’s rejection_reason; start a new verification.
Only one verification per person and provider can be pending at a time: a second POST answers 409 with details.pending_verification_id, the one to follow. Statuses, reuse and the evidence package: Biometric verification.

​
4. Answer questions and evidence requests

A provider can ask for information in text (INFORMATION) or for an explanation backed by files (EVIDENCE_PACKAGE). These requirements carry a description with the request, written for the merchant’s contact.
Answer with the text:
cURL
The response is 201 with the requirement SATISFIED and the text in satisfied_by.answer.
An answer never changes the merchant’s registration. Any other requirement type answers 400.

​
5. Create the affiliation

Create it whenever you want, before, during or after collecting:
cURL
One affiliation per merchant and provider can wait for documents at a time: a second POST /v1/affiliations while one is WAITING_DOCUMENTS answers 409 naming the open one. Cancel it to start over.
From here, follow the affiliation through its webhooks: Statuses and events. The link and the API write to the same requirements, so you can split the work any way you like:
  • Supply what you hold, send the link for the rest. Upload the articles of incorporation and the power of attorney your back office already has, then send onboarding_url. The contact sees only their identity document and the biometric step.
  • Use the link for the live step only. Collect every document in your own screens and let the contact do the biometric verification through the link.
  • Start in your app, finish on the phone. Anything the contact started on your screens is already received when they open the link on their phone.
Whichever way an item arrives, the requirement it satisfies changes at once, the page stops asking for it, and the affiliation is submitted when nothing is left.

​
Next steps

Requirements

Types, statuses, origins and what each provider asks for.

Statuses and events

Follow the affiliation and every building block by webhook.

When the provider asks for more

Rejection reasons and the next attempt.

API reference

Every route, parameter and response.