> ## Documentation Index > Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Get an onboarding document > Requires the onboarding-document.view permission. The response adds `download_url` and `download_url_expires_at`, a signed URL to the file valid for one hour, for the organization's own rows, and for a merchant caller a document presented for it; `null` before the upload completes, on a `SHARED` document (the file is another organization's), and on a document the caller may read but not download. ## OpenAPI ````yaml /api-spec.yaml get /v1/onboarding-documents/{id} openapi: 3.1.0 info: title: Rinne API version: 1.0.0 description: > **Rinne API** is a robust payment platform that offers integration with multiple payment providers. ## Authentication The API uses API Key authentication via the `x-api-key` header. Each company has a unique key to access resources. ## Response Format All responses follow a consistent format: - **Success**: Returns the requested data directly - **Error**: Returns an `error` object with detailed information ## Pagination Endpoints that return lists support pagination through parameters: - `page`: Page number (default: 1) - `limit`: Items per page (default: 20, maximum: 100) ## Supported Providers The API supports multiple payment providers: - **Rinne**: Internal provider - **Celcoin**: PIX integration and other financial services ## Raw Card Data (PCI Endpoints) Card credential fields (`card_data.number`, `card_data.cvv`, `card_data.network_token`, `card_data.cryptogram`, and the 3DS `card.number`) must always be sent encrypted — values start with the `ev:` prefix. Plaintext values are rejected with `400 VALIDATION_ERROR` on every host. There are two ways to send encrypted values: - **rinne-js**: card forms and wallet buttons (Apple Pay / Google Pay) encrypt credentials client-side before they leave the browser. - **PCI API host**: server-to-server integrations that handle raw card data must call `https://pci.api.rinne.com.br/core` (sandbox: `https://pci.api-sandbox.rinne.com.br/core`) instead of the regular host. This endpoint encrypts `number` and `cvv` in transit before the request reaches the API; all other fields pass through unchanged. The PCI host serves only transaction creation and 3DS session creation (both the self and merchant variants); use the regular host for everything else. contact: name: Rinne API Support email: suporte@rinne.com.br servers: - url: https://api-sandbox.rinne.com.br/core description: Sandbox - url: https://api.rinne.com.br/core description: Production security: [] tags: - name: System description: System and API health endpoints - name: Tap-on-Phone description: Access-token minting for the Tap-on-Phone SDK (called from your backend) - name: Authentication description: User authentication and authorization endpoints - name: Management description: >- Merchant management endpoints - create, list, get specific, overview, update - name: Transactions description: Transaction operations for merchants - create, list, overview, refunds - name: Affiliations description: Affiliation management for merchants - name: Biometric Verifications description: Biometric verifications of your merchants' contacts - name: Onboarding Requirements description: What your merchants must prove to a provider, and how far along they are - name: Onboarding Documents description: Documents uploaded for your merchants - name: KYC description: KYC check history of your merchants - name: Banking description: Banking operations for merchants - balance, cashout, statements - name: Bank Accounts description: Bank account management for merchants - name: Pix Keys description: PIX key management for merchants - name: Company Transactions description: Direct transaction management and query endpoints for companies - name: Companies description: Company management - name: Company Affiliations description: Payment provider affiliation management - name: Company Biometric Verifications description: Biometric verifications of the company contact - name: Company Onboarding Requirements description: What the company must prove to a provider, and how far along it is - name: Company Onboarding Documents description: Documents the company uploads for its onboarding - name: Company Banking description: Company banking endpoints (balance, etc.) - name: Company Pix description: Company PIX key management - name: Company Ledger description: Company ledger entry query endpoints - name: Company Disputes description: Company dispute query endpoints - name: Company Receivables description: Contract effects on the company's own receivables - name: Ledger description: Ledger entry query endpoints (company and merchants) - name: Disputes description: Dispute query endpoints for an organization's merchants - name: Cards description: Stored card management (self and merchant) - name: API Keys description: API key management - create, list, revoke (hashed, show-once) - name: Webhooks description: Endpoints for receiving webhooks from external providers - name: Pricing description: Fee and cost policy management for transaction pricing - name: Users description: User management endpoints - name: Roles description: Role management endpoints - name: Permissions description: Permission management endpoints paths: /v1/onboarding-documents/{id}: get: tags: - Company Onboarding Documents summary: Get an onboarding document description: > Requires the onboarding-document.view permission. The response adds `download_url` and `download_url_expires_at`, a signed URL to the file valid for one hour, for the organization's own rows, and for a merchant caller a document presented for it; `null` before the upload completes, on a `SHARED` document (the file is another organization's), and on a document the caller may read but not download. parameters: - in: path name: id required: true schema: type: string format: uuid description: The onboarding document ID example: 9c1e7b3a-2d4f-4a6b-8c0d-5e7f9a1b3c2d responses: '200': description: The document, with the download URL when the caller may download it content: application/json: schema: $ref: '#/components/schemas/OnboardingDocumentDetailResponse' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/AuthenticationErrorResponse' '403': description: > Insufficient permissions, or company onboarding is not available to the caller yet (`message`: "Company onboarding is not available yet") content: application/json: schema: $ref: '#/components/schemas/AuthorizationErrorResponse' '404': description: The document is not one the company may see content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorResponse' security: - ApiKeyAuth: [] components: schemas: OnboardingDocumentDetailResponse: allOf: - $ref: '#/components/schemas/OnboardingDocumentResponse' - type: object properties: download_url: type: - string - 'null' format: uri description: >- A signed URL to the file, valid for one hour; `null` before the upload completes, on a `SHARED` document, and when the caller may read the document but not download it example: https://storage.googleapis.com/onboarding-documents/... download_url_expires_at: type: - string - 'null' format: date-time description: When `download_url` stops working example: '2026-10-09T13:00:00.000Z' required: - download_url - download_url_expires_at AuthenticationErrorResponse: type: object properties: error: type: object properties: code: type: string example: AUTHENTICATION_ERROR message: type: string example: Authentication required to access this resource status: type: integer example: 401 details: type: object properties: reason: type: string example: Invalid API key path: type: string example: /companies/me timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 AuthorizationErrorResponse: type: object properties: error: type: object properties: code: type: string example: AUTHORIZATION_ERROR message: type: string example: You need 'admin' permissions to access this resource status: type: integer example: 403 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 NotFoundErrorResponse: type: object properties: error: type: object properties: code: type: string example: RESOURCE_NOT_FOUND message: type: string example: Company with ID '123' not found status: type: integer example: 404 path: type: string example: /companies/me timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 InternalServerErrorResponse: type: object properties: error: type: object properties: code: type: string example: INTERNAL_SERVER_ERROR message: type: string example: An unexpected error occurred status: type: integer example: 500 path: type: string example: /companies timestamp: type: string format: date-time example: '2023-12-01T10:00:00.000Z' requestId: type: string example: req_123456789 OnboardingDocumentResponse: description: >- A document a company holds for a subject, as the list, read and complete responses carry it allOf: - $ref: '#/components/schemas/OnboardingDocumentEntitySnapshot' - type: object required: - screening - screening_note OnboardingDocumentEntitySnapshot: type: object description: > A document as the `entity` of `onboarding-document.status-changed` carries it. Same shape as `OnboardingDocumentResponse`, except that `screening` and `screening_note` may be absent: they were added after the event existed, and a snapshot is taken when the event is written. properties: id: type: string format: uuid example: 9c1e7b3a-2d4f-4a6b-8c0d-5e7f9a1b3c2d company_id: type: string description: >- The company the document was presented for (the organization itself or one of its merchants) example: c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f subject_document_number: type: string description: Whom the document is about, digits only (a CPF or a CNPJ) example: '81146431023' type: type: string enum: - 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 description: >- `RNM_*` and `ID_DOCUMENT_*` only arrive from a provider's capture; `SELFIE` from a capture or an upload example: PROOF_OF_ADDRESS status: type: string enum: - PENDING_UPLOAD - NOT_VALIDATED - VALIDATED - REJECTED - SUPERSEDED description: > `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). example: NOT_VALIDATED source: type: string enum: - UPLOAD - PROVIDER - SHARED description: >- `UPLOAD` by the customer; `PROVIDER` from a provider's capture; `SHARED` a reference to a document another organization validated for the same subject example: UPLOAD requirement_id: type: - string - 'null' format: uuid description: >- The `EVIDENCE_PACKAGE` requirement the document is attached to; `null` for every other document example: null file_name: type: - string - 'null' description: >- The name given at upload, or the name the provider's capture produced; `null` on a `SHARED` document example: address.pdf content_type: type: - string - 'null' description: >- The file's MIME type; `null` until the upload completes and on a `SHARED` document example: application/pdf file_size_bytes: type: - integer - 'null' description: '`null` until the upload completes and on a `SHARED` document' example: 125430 upload_url_expires_at: type: - string - 'null' format: date-time description: >- When the signed upload URL stops accepting the file; `null` once uploaded example: null rejections: type: array description: >- 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 items: $ref: '#/components/schemas/OnboardingDocumentRejection' superseded_by_id: type: - string - 'null' format: uuid description: >- The document that replaced this one, or that already held its bytes, when `SUPERSEDED` example: null screening: type: - string - 'null' enum: - PENDING - PASSED - FAILED - null description: > 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. example: null screening_note: type: - string - 'null' description: >- 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 example: null created_at: type: string format: date-time example: '2026-10-09T12:00:00.000Z' updated_at: type: string format: date-time example: '2026-10-09T12:00:00.000Z' required: - id - company_id - subject_document_number - type - status - source - requirement_id - file_name - content_type - file_size_bytes - upload_url_expires_at - rejections - superseded_by_id - created_at - updated_at OnboardingDocumentRejection: type: object description: A provider's refusal of the document, recorded by the rejection review properties: provider: type: string enum: - CELCOIN - CAPPTA example: CELCOIN affiliation_id: type: string description: The affiliation whose submission the provider refused example: aff_123456789 reason_code: type: string enum: - DOCUMENT_UNREADABLE - DOCUMENT_DATA_MISMATCH - DOCUMENT_EXPIRED - DOCUMENT_MISSING - FACEMATCH_FAILED - COMPANY_DATA_MISMATCH - COMPLIANCE_REFUSAL - OTHER example: DOCUMENT_UNREADABLE message: type: - string - 'null' description: The provider's text, when it gave one example: null rejected_at: type: string format: date-time example: '2026-10-09T12:00:00.000Z' required: - provider - affiliation_id - reason_code - message - rejected_at securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: Company API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.