curl --request POST \
--url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"type": "PROOF_OF_ADDRESS",
"subject_document_number": "811.464.310-23",
"file_name": "address.pdf",
"content_type": "application/pdf",
"requirement_id": "7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
}
'import requests
url = "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents"
payload = {
"type": "PROOF_OF_ADDRESS",
"subject_document_number": "811.464.310-23",
"file_name": "address.pdf",
"content_type": "application/pdf",
"requirement_id": "7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: 'PROOF_OF_ADDRESS',
subject_document_number: '811.464.310-23',
file_name: 'address.pdf',
content_type: 'application/pdf',
requirement_id: '7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10'
})
};
fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'PROOF_OF_ADDRESS',
'subject_document_number' => '811.464.310-23',
'file_name' => 'address.pdf',
'content_type' => 'application/pdf',
'requirement_id' => '7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents"
payload := strings.NewReader("{\n \"type\": \"PROOF_OF_ADDRESS\",\n \"subject_document_number\": \"811.464.310-23\",\n \"file_name\": \"address.pdf\",\n \"content_type\": \"application/pdf\",\n \"requirement_id\": \"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"PROOF_OF_ADDRESS\",\n \"subject_document_number\": \"811.464.310-23\",\n \"file_name\": \"address.pdf\",\n \"content_type\": \"application/pdf\",\n \"requirement_id\": \"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"PROOF_OF_ADDRESS\",\n \"subject_document_number\": \"811.464.310-23\",\n \"file_name\": \"address.pdf\",\n \"content_type\": \"application/pdf\",\n \"requirement_id\": \"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10\"\n}"
response = http.request(request)
puts response.read_body{
"id": "9c1e7b3a-2d4f-4a6b-8c0d-5e7f9a1b3c2d",
"company_id": "c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f",
"subject_document_number": "81146431023",
"type": "PROOF_OF_ADDRESS",
"status": "NOT_VALIDATED",
"source": "UPLOAD",
"requirement_id": null,
"file_name": "address.pdf",
"content_type": "application/pdf",
"file_size_bytes": 125430,
"upload_url_expires_at": "2026-10-09T12:15:00.000Z",
"rejections": [
{
"provider": "CELCOIN",
"affiliation_id": "aff_123456789",
"reason_code": "DOCUMENT_UNREADABLE",
"message": null,
"rejected_at": "2026-10-09T12:00:00.000Z"
}
],
"superseded_by_id": null,
"screening": null,
"screening_note": null,
"created_at": "2026-10-09T12:00:00.000Z",
"updated_at": "2026-10-09T12:00:00.000Z",
"upload_url": "https://storage.googleapis.com/onboarding-documents/..."
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation error",
"status": 400,
"details": {
"issues": [
{
"field": "email",
"type": "REQUIRED",
"message": "Field 'email' is required",
"value": "invalid_value",
"constraints": {
"min": 18,
"max": 120
}
}
]
},
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication required to access this resource",
"status": 401,
"details": {
"reason": "Invalid API key"
},
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHORIZATION_ERROR",
"message": "You need 'admin' permissions to access this resource",
"status": 403,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Company with ID '123' not found",
"status": 404,
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "CONFLICT_ERROR",
"message": "The evidence package was already answered; a refusal reopens it",
"status": 409,
"details": {
"requirement_id": "7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
}
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred",
"status": 500,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}Open an onboarding document upload
Requires the merchant.onboarding-document.create permission.
Opens an upload of one document for the merchant: creates the document as PENDING_UPLOAD and returns
upload_url, a signed PUT URL valid for fifteen minutes. PUT the file there with three headers, all
signed into the URL: Content-Type equal to the declared content_type, x-goog-if-generation-match: 0,
and x-goog-content-length-range: 0,10485760; while the object exists a second PUT through the URL
answers 412, and the storage refuses a body over 10 MB. Then call complete, which
checks the file and makes the document current; when complete refuses the file it deletes it, and the
same URL takes a corrected file until it expires. A document is never
replaced in place: a correction is a new upload, and the previous current document of the same subject
and type becomes SUPERSEDED when the new one completes.
type is one of the types a customer can upload; the types a provider’s capture produces answer 400 on
type. subject_document_number is the CPF or CNPJ the document is about: the merchant, its contact, or the subject of one of the merchant’s requirements; anyone
else answers 400 on subject_document_number. requirement_id makes the document an attachment of an
EVIDENCE_PACKAGE requirement of the merchant with the same subject, still open; it then satisfies no
other requirement and supersedes nothing.
curl --request POST \
--url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"type": "PROOF_OF_ADDRESS",
"subject_document_number": "811.464.310-23",
"file_name": "address.pdf",
"content_type": "application/pdf",
"requirement_id": "7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
}
'import requests
url = "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents"
payload = {
"type": "PROOF_OF_ADDRESS",
"subject_document_number": "811.464.310-23",
"file_name": "address.pdf",
"content_type": "application/pdf",
"requirement_id": "7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
type: 'PROOF_OF_ADDRESS',
subject_document_number: '811.464.310-23',
file_name: 'address.pdf',
content_type: 'application/pdf',
requirement_id: '7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10'
})
};
fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'type' => 'PROOF_OF_ADDRESS',
'subject_document_number' => '811.464.310-23',
'file_name' => 'address.pdf',
'content_type' => 'application/pdf',
'requirement_id' => '7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents"
payload := strings.NewReader("{\n \"type\": \"PROOF_OF_ADDRESS\",\n \"subject_document_number\": \"811.464.310-23\",\n \"file_name\": \"address.pdf\",\n \"content_type\": \"application/pdf\",\n \"requirement_id\": \"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"type\": \"PROOF_OF_ADDRESS\",\n \"subject_document_number\": \"811.464.310-23\",\n \"file_name\": \"address.pdf\",\n \"content_type\": \"application/pdf\",\n \"requirement_id\": \"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/onboarding-documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"type\": \"PROOF_OF_ADDRESS\",\n \"subject_document_number\": \"811.464.310-23\",\n \"file_name\": \"address.pdf\",\n \"content_type\": \"application/pdf\",\n \"requirement_id\": \"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10\"\n}"
response = http.request(request)
puts response.read_body{
"id": "9c1e7b3a-2d4f-4a6b-8c0d-5e7f9a1b3c2d",
"company_id": "c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f",
"subject_document_number": "81146431023",
"type": "PROOF_OF_ADDRESS",
"status": "NOT_VALIDATED",
"source": "UPLOAD",
"requirement_id": null,
"file_name": "address.pdf",
"content_type": "application/pdf",
"file_size_bytes": 125430,
"upload_url_expires_at": "2026-10-09T12:15:00.000Z",
"rejections": [
{
"provider": "CELCOIN",
"affiliation_id": "aff_123456789",
"reason_code": "DOCUMENT_UNREADABLE",
"message": null,
"rejected_at": "2026-10-09T12:00:00.000Z"
}
],
"superseded_by_id": null,
"screening": null,
"screening_note": null,
"created_at": "2026-10-09T12:00:00.000Z",
"updated_at": "2026-10-09T12:00:00.000Z",
"upload_url": "https://storage.googleapis.com/onboarding-documents/..."
}{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation error",
"status": 400,
"details": {
"issues": [
{
"field": "email",
"type": "REQUIRED",
"message": "Field 'email' is required",
"value": "invalid_value",
"constraints": {
"min": 18,
"max": 120
}
}
]
},
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHENTICATION_ERROR",
"message": "Authentication required to access this resource",
"status": 401,
"details": {
"reason": "Invalid API key"
},
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "AUTHORIZATION_ERROR",
"message": "You need 'admin' permissions to access this resource",
"status": 403,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Company with ID '123' not found",
"status": 404,
"path": "/companies/me",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}{
"error": {
"code": "CONFLICT_ERROR",
"message": "The evidence package was already answered; a refusal reopens it",
"status": 409,
"details": {
"requirement_id": "7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
}
}
}{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred",
"status": 500,
"path": "/companies",
"timestamp": "2023-12-01T10:00:00.000Z",
"requestId": "req_123456789"
}
}Authorizations
Company API key for authentication
Path Parameters
The merchant ID
Body
The document type; the types a provider's capture produces (RNM_*, ID_DOCUMENT_*) cannot be uploaded
CNH_FRONT, CNH_BACK, CNH_DIGITAL, RG_FRONT, RG_BACK, RNE_FRONT, RNE_BACK, SELFIE, ARTICLES_OF_INCORPORATION, POWER_OF_ATTORNEY, PROOF_OF_ADDRESS, PROOF_OF_INCOME, FINANCIAL_STATEMENT, OTHER "PROOF_OF_ADDRESS"
The CPF or CNPJ the document is about; punctuation is ignored. The company, its contact, or the subject of one of its requirements
"811.464.310-23"
The file's name, kept for display; surrounding whitespace is trimmed
1 - 255"address.pdf"
The file's MIME type, sent as Content-Type on the PUT and checked against the bytes on complete
application/pdf, image/png, image/jpeg "application/pdf"
Makes the document an attachment of that EVIDENCE_PACKAGE requirement, which must be the company's, still open, and of the same subject
"7f3d9c2a-5b1e-4c8d-9a6f-0e2b4d6c8a10"
Response
The document, PENDING_UPLOAD, with the signed upload URL
A document a company holds for a subject, as the list, read and complete responses carry it
"9c1e7b3a-2d4f-4a6b-8c0d-5e7f9a1b3c2d"
The company the document was presented for (the organization itself or one of its merchants)
"c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f"
Whom the document is about, digits only (a CPF or a CNPJ)
"81146431023"
RNM_* and ID_DOCUMENT_* only arrive from a provider's capture; SELFIE from a capture or an upload
CNH_FRONT, CNH_BACK, CNH_DIGITAL, RG_FRONT, RG_BACK, RNE_FRONT, RNE_BACK, RNM_FRONT, RNM_BACK, ID_DOCUMENT_FRONT, ID_DOCUMENT_BACK, SELFIE, ARTICLES_OF_INCORPORATION, POWER_OF_ATTORNEY, PROOF_OF_ADDRESS, PROOF_OF_INCOME, FINANCIAL_STATEMENT, OTHER "PROOF_OF_ADDRESS"
PENDING_UPLOAD until complete; NOT_VALIDATED once the file is recorded and until a provider judges it;
VALIDATED when a provider accepted it; REJECTED when every provider that saw it refused it (see rejections);
SUPERSEDED when a newer document of the same subject and type replaced it, when complete found its bytes
already stored in another document (superseded_by_id), or when Rinne closed an upload whose URL expired with
nothing received (superseded_by_id null).
PENDING_UPLOAD, NOT_VALIDATED, VALIDATED, REJECTED, SUPERSEDED "NOT_VALIDATED"
UPLOAD by the customer; PROVIDER from a provider's capture; SHARED a reference to a document another organization validated for the same subject
UPLOAD, PROVIDER, SHARED "UPLOAD"
The EVIDENCE_PACKAGE requirement the document is attached to; null for every other document
null
The name given at upload, or the name the provider's capture produced; null on a SHARED document
"address.pdf"
The file's MIME type; null until the upload completes and on a SHARED document
"application/pdf"
null until the upload completes and on a SHARED document
125430
When upload_url stops accepting the file
"2026-10-09T12:15:00.000Z"
In the list, read and complete responses, the provider refusals of these bytes, newest first, from every document of the organization that holds the same file for the same subject, this one included. The entity of a webhook carries the refusals recorded on this document only
Show child attributes
Show child attributes
The document that replaced this one, or that already held its bytes, when SUPERSEDED
null
Rinne's own check of the file before any provider reads it: PENDING until Rinne looks at it,
then PASSED or FAILED. A FAILED document satisfies no requirement and its requirement reads
REJECTED, with screening_note saying why; upload a new one. Always null while Rinne does not
screen documents.
PENDING, PASSED, FAILED, null null
The screener's note on a FAILED, saying why the document did not pass; null on any other verdict, and always null while Rinne does not screen documents
null
"2026-10-09T12:00:00.000Z"
"2026-10-09T12:00:00.000Z"
The signed PUT URL for the file, valid for fifteen minutes; send the declared content_type as Content-Type, plus x-goog-if-generation-match: 0 and x-goog-content-length-range: 0,10485760
"https://storage.googleapis.com/onboarding-documents/..."