> ## 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.

# List biometric verifications

> Requires the merchant.biometric-verification.list permission.

Lists the verifications of the merchant's contact within the organization, whichever company's route created them, plus those created for the merchant. The list never carries the evidence package URL; `GET` the verification for it.




## OpenAPI

````yaml /api-spec.yaml get /v1/merchants/{merchantId}/biometric-verifications
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/merchants/{merchantId}/biometric-verifications:
    get:
      tags:
        - Biometric Verifications
      summary: List biometric verifications
      description: >
        Requires the merchant.biometric-verification.list permission.


        Lists the verifications of the merchant's contact within the
        organization, whichever company's route created them, plus those created
        for the merchant. The list never carries the evidence package URL; `GET`
        the verification for it.
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
          description: The merchant ID
          example: c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for pagination
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of verifications per page
        - in: query
          name: subject_document_number
          schema:
            type: string
          description: Filter by the verified person's document number (CPF)
        - in: query
          name: provider
          schema:
            type: string
            enum:
              - CELCOIN
          description: Filter by provider
        - in: query
          name: status
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - PENDING
                - APPROVED
                - REPROVED
                - EXPIRED
          description: Comma-separated list of statuses to filter by
        - in: query
          name: sort
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - created_at
                - updated_at
                - '-created_at'
                - '-updated_at'
          description: >-
            Multi-field sort string (e.g., -created_at). Allowed fields:
            created_at, updated_at. Defaults to -created_at.
          example: '-created_at'
      responses:
        '200':
          description: Paginated list of biometric verifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiometricVerificationListResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
        '403':
          description: >
            Insufficient permissions, or biometric verifications are not
            available to the caller yet

            (`message`: "Biometric verifications is not available yet")
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationErrorResponse'
        '404':
          description: >-
            Merchant not found or does not belong to the authenticated
            organization
          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:
    BiometricVerificationListResponse:
      type: object
      description: Paginated list of biometric verifications
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BiometricVerificationResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      required:
        - data
        - pagination
    ValidationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Validation error
            status:
              type: integer
              example: 400
            details:
              type: object
              properties:
                issues:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        example: email
                      type:
                        type: string
                        example: REQUIRED
                      message:
                        type: string
                        example: Field 'email' is required
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: boolean
                        example: invalid_value
                      constraints:
                        type: object
                        example:
                          min: 18
                          max: 120
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    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
    BiometricVerificationResponse:
      description: A biometric verification of a company contact at a provider
      allOf:
        - $ref: '#/components/schemas/BiometricVerificationEntitySnapshot'
        - type: object
          required:
            - approved_at
    PaginationResponse:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
        - hasNext
        - hasPrev
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 50
        totalPages:
          type: integer
          example: 3
        hasNext:
          type: boolean
          example: true
        hasPrev:
          type: boolean
          example: false
    BiometricVerificationEntitySnapshot:
      type: object
      description: >
        A biometric verification as the `entity` of
        `biometric-verification.status-changed` carries it. Same

        shape as `BiometricVerificationResponse`, except that `approved_at` may
        be absent: it was added after

        the event existed, and a snapshot is taken when the event is written.
      properties:
        id:
          type: string
          format: uuid
          example: 2b6f0a5e-7c1d-4f1a-9a3e-2d0c1b7e8f90
        company_id:
          type: string
          description: >-
            The company the verification was created for (the organization
            itself or one of its merchants)
          example: c0a8012e-4d3b-4a6e-8f1b-1a2b3c4d5e6f
        provider:
          type: string
          enum:
            - CELCOIN
          example: CELCOIN
        subject_document_number:
          type: string
          description: The verified person's document number (CPF), digits only
          example: '81146431023'
        status:
          type: string
          enum:
            - PENDING
            - APPROVED
            - REPROVED
            - EXPIRED
          description: >
            `PENDING` until the provider reports the capture; `APPROVED` or
            `REPROVED` from its result;

            `EXPIRED` when the capture URL expired with no result.
          example: PENDING
        verification_url:
          type: string
          format: uri
          description: The provider's capture URL, to be handed to the person as is
          example: https://biometric.provider.example/session/abc
        verification_url_expires_at:
          type: string
          format: date-time
          description: When the capture URL stops working
          example: '2026-10-09T12:00:00.000Z'
        redirect_url:
          type: string
          format: uri
          nullable: true
          description: >-
            Where the provider sends the person after the capture, when given at
            creation
          example: https://app.example.com/onboarding/done
        selfie_onboarding_document_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            The `SELFIE` onboarding document an `APPROVED` result produced;
            `null` otherwise
          example: null
        approved_at:
          type: string
          format: date-time
          nullable: true
          description: When the verification became `APPROVED`; `null` on any other status
          example: null
        rejection_reason:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BiometricVerificationRejectionReason'
          description: The provider's reason for a `REPROVED` result; `null` otherwise
        created_at:
          type: string
          format: date-time
          example: '2026-10-08T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-10-08T12:00:00.000Z'
      required:
        - id
        - company_id
        - provider
        - subject_document_number
        - status
        - verification_url
        - verification_url_expires_at
        - redirect_url
        - selfie_onboarding_document_id
        - rejection_reason
        - created_at
        - updated_at
    BiometricVerificationRejectionReason:
      type: object
      description: The provider's reason for a `REPROVED` result
      properties:
        code:
          type: string
          description: The provider's reason code
          example: RRU008
        message:
          type: string
          description: The provider's reason, as it stated it
          example: Identity could not be confirmed during the biometric validation test
      required:
        - code
        - message
  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.