> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit KYC Information

> Submits KYC data for a specific customer. The response will include a URL to a third-party KYC provider's widget for document uploads and liveness checks. Webhook events will notify about the validation process.

<Note> The provider URL for document uploads and liveness checks only works in production.</Note>



## OpenAPI

````yaml ramps-api/openapi.json POST /api/v1/customers/{customerId}/kyc/
openapi: 3.1.0
info:
  title: Ripio Ramp API
  version: v1
  description: >-
    API for Ripio ramp services, enabling partners to integrate On-Ramp,
    Off-Ramp, customer management, KYC processes, and other financial
    functionalities. This API is RESTful, uses JSON for requests and responses,
    and standard HTTP status codes. This document is based on the
    'onramp-api.pdf' provided and aims to be compliant with OpenAPI
    Specification v3.1.0. The PDF indicates that the API documentation is a
    draft and subject to change.
servers:
  - url: https://skala-sandbox.ripio.com
    description: Sandbox environment
  - url: https://skala.ripio.com
    description: Production environment
security:
  - BearerToken: []
tags:
  - name: Authentication
    description: Operations related to API authentication and authorization.
  - name: Customers
    description: Operations related to customer management.
  - name: KYC
    description: Operations related to Know Your Customer processes.
  - name: Fiat Accounts
    description: Operations related to managing fiat accounts and their requirements.
  - name: Quotes
    description: Operations related to obtaining and managing conversion quotes.
  - name: On-Ramp
    description: Operations related to fiat-to-crypto (on-ramp) processes.
  - name: Off-Ramp
    description: Operations related to crypto-to-fiat (off-ramp) processes.
  - name: Transactions
    description: Operations related to listing and managing all transaction types.
  - name: Networks
    description: >-
      Operations related to retrieving available deposit and withdrawal
      networks.
  - name: Rates
    description: Operations related to retrieving market rates.
  - name: Sandbox
    description: Operations specific to the sandbox environment for testing purposes.
  - name: Webhooks
    description: Webhook event notifications from Ripio Ramp API.
  - name: Sell and Pay
    description: >-
      Endpoints for managing Sell and Pay transactions, which allow customers to
      convert cryptocurrency to fiat currency and pay merchants via QR codes
paths:
  /api/v1/customers/{customerId}/kyc/:
    post:
      tags:
        - KYC
      summary: Submit KYC Information
      description: >-
        Submits KYC data for a specific customer. The response will include a
        URL to a third-party KYC provider's widget for document uploads and
        liveness checks. Webhook events will notify about the validation
        process.


        <Note> The provider URL for document uploads and liveness checks only
        works in production.</Note>
      operationId: submitKycInformation
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      requestBody:
        required: true
        description: >-
          KYC data for the customer. Structure should align with fields from
          /kycRequirements/.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycSubmissionRequest'
            examples:
              Argentina:
                summary: Argentina KYC Submission (API flow)
                value:
                  kycSubmission:
                    country: AR
                    first_name: Mateo
                    last_name: Romero
                    gender: M
                    birthday: '1990-01-25'
                    nationality: AR
                    id_number_type: DNI
                    id_number: '11122233'
                    registered_tax_payer: false
                    cuit: '20111222330'
                    address: Libertad
                    address_flat: '1'
                    address_number: '333'
                    postal_code: '1012'
                    district: Chubut
                    city: Trelew
                    state: AR.CH
                    phone: '+542211228855'
                    personal_activity: AR.6
                  redirectUrl: https://www.example.com/
              Mexico:
                summary: Mexico KYC Submission (API flow)
                value:
                  kycSubmission:
                    country: MX
                    first_name: Jose
                    last_name: Lopez
                    gender: H
                    birthday: '1995-11-19'
                    birthday_place: Guadalajara
                    nationality: MX
                    id_number_type: CURP
                    id_number: LOXJ951119HJCPXS09
                    date_of_issue: '2024-01-01'
                    date_of_expiration: '2034-01-01'
                    rfc: LOJO951119Q18
                    address: isla cartagena
                    address_flat: '1'
                    address_number: '1505'
                    postal_code: '44950'
                    district: district
                    city: Guadalajara
                    state: MX.JA
                    phone: '+523325606411'
                    net_income: '10000'
                    personal_activity: MX.1000000
                    terms_conditions: true
                    address_photo: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
              RipioKyc:
                summary: Ripio KYC delegated flow
                description: >-
                  Used when the account is configured for the Ripio KYC
                  delegated flow. KYC data is not collected directly — the user
                  is redirected to Ripio's KYC platform to complete the process.
                value:
                  redirectUrl: https://www.example.com/
              Colombia:
                summary: Colombia KYC Submission
                value:
                  country: CO
                  first_name: Santiago
                  last_name: García
                  birthday: '1992-05-15'
                  nationality: CO
                  id_number: '1234567890'
                  id_number_type: CC
                  address: Carrera 7
                  address_number: '45'
                  address_type: HOME
                  state: CO.DC
                  city: Bogotá
                  phone: '+573001234567'
                  district: Chapinero
      responses:
        '200':
          description: >-
            KYC submission received successfully. Includes providerUrl for
            document upload and liveness check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycSubmissionResponse'
        '201':
          description: >-
            KYC submission received successfully (alternative success code, as
            per PDF example for other POSTs). Includes providerUrl for document
            upload and liveness check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycSubmissionResponse'
        '400':
          description: Bad Request - e.g., invalid input data or validation errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 40001
                type: NotAuthenticated
                detail:
                  message: Authentication credentials were not provided.
                  code: not_authenticated
                status: 401
        '404':
          description: Not Found - Customer not found or inactive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 40004
                type: NotFound
                detail:
                  message: Not found.
                  code: not_found
                status: 404
components:
  parameters:
    CustomerId:
      name: customerId
      in: path
      required: true
      description: Unique identifier for the customer.
      schema:
        type: string
        format: uuid
      example: 8142b065-79c4-4f48-9e33-11b17bc658d4
  schemas:
    KycSubmissionRequest:
      type: object
      description: >-
        Request body for KYC submission. Use `kycSubmission` + `redirectUrl` for
        the standard API flow, or only `redirectUrl` for the Ripio KYC delegated
        flow.
      properties:
        kycSubmission:
          type: object
          description: >-
            Customer KYC data. Fields vary by country — use `/kycRequirements/`
            to get the required fields for the customer's country. Not required
            when using the Ripio KYC delegated flow.
          properties:
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code (AR, MX, BR, CO).
              example: AR
            first_name:
              type: string
              example: Mateo
            last_name:
              type: string
              example: Romero
            gender:
              type: string
              description: M or F (AR/BR/CO); H or M (MX).
              example: M
            birthday:
              type: string
              format: date
              example: '1990-01-25'
            nationality:
              type: string
              example: AR
            id_number_type:
              type: string
              description: Document type (e.g. DNI, CURP, CPF, CC).
              example: DNI
            id_number:
              type: string
              example: '11122233'
            address:
              type: string
              example: Libertad
            address_number:
              type: string
              example: '333'
            address_flat:
              type: string
              description: Apartment / unit number (optional).
              example: '1'
            postal_code:
              type: string
              example: '1012'
            district:
              type: string
              example: Chubut
            city:
              type: string
              example: Trelew
            state:
              type: string
              description: State code in ISO 3166-2 format (e.g. AR.CH, MX.JA).
              example: AR.CH
            phone:
              type: string
              description: Phone number in E.164 format.
              example: '+542211228855'
            personal_activity:
              type: string
              description: Occupation/activity code from `/kycRequirements/`.
              example: AR.6
            personal_activity_other:
              type: string
              description: Free-text description when activity code requires it (optional).
            net_income:
              type: string
              description: Annual net income (required for some countries/activities).
              example: '10000'
            registered_tax_payer:
              type: boolean
              description: Whether the customer is a registered tax payer (AR only).
              example: false
            cuit:
              type: string
              description: >-
                Argentine tax ID (AR only). Required. Pass the customer's CUIL
                when `registered_tax_payer` is `false` (individual), or their
                CUIT when `registered_tax_payer` is `true` (registered
                taxpayer).
              example: '20111222330'
            rfc:
              type: string
              description: Mexican tax ID (RFC). MX only.
              example: LOJO951119Q18
            birthday_place:
              type: string
              description: City of birth. MX only.
              example: Guadalajara
            date_of_issue:
              type: string
              format: date
              description: ID issue date. MX only.
              example: '2024-01-01'
            date_of_expiration:
              type: string
              format: date
              description: ID expiration date. MX only.
              example: '2034-01-01'
            terms_conditions:
              type: boolean
              description: Acceptance of terms and conditions. Required for MX.
              example: true
            address_photo:
              type: string
              format: byte
              description: >-
                Proof of address document as a base64-encoded image (e.g. JPEG
                or PNG, max 5 MB). Required for MX.
              example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
          required:
            - country
            - first_name
            - last_name
            - gender
            - birthday
            - nationality
            - id_number_type
            - id_number
            - address
            - address_number
            - postal_code
            - district
            - city
            - state
            - phone
        redirectUrl:
          type: string
          format: uri
          description: >-
            URL to redirect the user after completing the KYC flow. Required for
            the Ripio KYC delegated flow; optional for the API flow.
          example: https://www.example.com/
    KycSubmissionResponse:
      type: object
      properties:
        submissionId:
          type: string
          format: uuid
          description: Unique identifier for the submitted KYC data.
        createdAt:
          type: string
          format: date-time
          description: Date and time the KYC submission was created (UTC format).
        providerUrl:
          type: string
          format: url
          description: >-
            Points to a third-party KYC provider's widget to handle file uploads
            and liveness checks. Only available in production.
      required:
        - submissionId
        - createdAt
        - providerUrl
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: Application-specific error code.
        type:
          type: string
          description: Type of error or exception.
        detail:
          type: object
          properties:
            message:
              type: string
              description: Detailed error message.
          additionalProperties: true
        status:
          type: integer
          description: HTTP status code.
      required:
        - code
        - type
        - detail
        - status
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token obtained via
        [/oauth2/token/](/ramps-api/authentication/acquire-access-token). Use as
        `Authorization: Bearer <access_token>`.

````