> ## 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.
# Retrieve KYC Requirements
> Retrieves the specific Know Your Customer (KYC) requirements, detailing the fields and document types needed for customer verification.
KYC requirements are determined by the country your account is configured for — you do not need to filter by country, the response is already scoped to it. For example, an account operating in Argentina returns the fields and document types required by Argentine regulations, while a Brazil account requires `first_name`, `last_name`, `id_number`, `id_number_type` and `net_income` in addition to its location and contact fields.
For every field returned as a `CHOICE`, submit the exact `value` from `choices`, never the `label`: `MX.JA` for Jalisco, `BR.SP` for São Paulo, `AR.A` for an income bracket. Labels are rejected. See [KYC fields by country](/ramps-api/kyc/kyc-fields-by-country) for what each field means and how it is validated.
**`requiredIf` — a field required only for certain values of another field.** Entries in `kycRequiredFields` may carry a `requiredIf` object naming the field they depend on and the values that make them required. Today it appears on Argentina's `personal_activity_other`:
```json theme={null}
{
"fieldName": "personal_activity_other",
"required": false,
"type": "CHOICE",
"choices": [{ "value": "AR.1", "label": "..." }],
"requiredIf": { "fieldName": "personal_activity", "isOneOf": ["AR.3", "AR.4"] }
}
```
The key is additive — a parser that ignores it still works — but a form built only on `required` will let the customer submit without a field the API then rejects.
Two fields are validated but not published in `kycRequiredFields`, so read their accepted values here rather than from the response: `id_number_type` for **Argentina** (`DNI`, `R_P`, `OTHER`; optional, defaults to `DNI`) and for **Mexico** (not used — the document is always a CURP).
For **Mexico**, `address_photo` is published as required but is only enforced for accounts configured for the Ripio-provider widget flow.
For **Argentina**, `net_income` and `personal_activity` are published as required but a payload that omits them is still accepted today, so that integrations already live are not turned away. Build the form as if they were required — that is the regulatory intent and the API will start refusing payloads without them. When the value is present it is validated against the catalog either way.
**`nationality` carries its own catalog.** It is returned as a `CHOICE` with every accepted ISO 3166-1 alpha-2 code, so a form built from this response cannot offer one of the [codes the identity provider refuses](/ramps-api/kyc/kyc-fields-by-country#not-every-iso-country-code-is-accepted). Mexico's `birthday_place` — the country of birth — carries the same catalog.
For Brazil, identity documents (ID front/back and selfie) are collected through the KYC provider's document-upload flow, not submitted as inline base64 fields in the KYC request.
## OpenAPI
````yaml ramps-api/openapi.json GET /api/v1/kycRequirements/
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: Support Tickets
description: >-
Operations for raising and tracking customer support tickets with Ripio's
support team. This feature must be enabled for your account by the Ripio
team.
- name: Customers
description: Operations related to customer management.
- name: KYC
description: Operations related to Know Your Customer processes.
- name: Investor Profile
description: >-
Brazilian accounts only: the investor-profile (suitability) questionnaire
required by Resolução BCB nº 520/2025.
- 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: Refunds
description: >-
Operations for returning the money of an on-ramp or off-ramp operation
that could not be completed. Each ramp must be enabled for your account by
the Ripio team.
- 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: Transaction Limits
description: >-
Operations related to retrieving per-transaction limits by currency and
ramp operation.
- 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/kycRequirements/:
get:
tags:
- KYC
summary: Retrieve KYC Requirements
description: >-
Retrieves the specific Know Your Customer (KYC) requirements, detailing
the fields and document types needed for customer verification.
operationId: getKycRequirements
responses:
'200':
description: Successfully retrieved KYC requirements.
content:
application/json:
schema:
$ref: '#/components/schemas/KycRequirementsResponse'
examples:
Argentina:
summary: Argentina — 19 fields
description: >-
Catalogs are truncated here; the response carries every
value. `net_income` and `personal_activity` are published as
required but a payload that omits them is still accepted
today.
value:
kycRequiredFields:
- fieldName: country
required: true
type: CHOICE
choices:
- value: AR
label: Argentina
- fieldName: first_name
required: true
type: TEXT
- fieldName: last_name
required: true
type: TEXT
- fieldName: gender
required: true
type: CHOICE
choices:
- value: F
label: Femenino
- value: M
label: Masculino
- fieldName: birthday
required: true
type: DATE
- fieldName: nationality
required: true
type: CHOICE
choices:
- value: AR
label: AR
- value: BR
label: BR
- value: …
label: 233 codes in total
- fieldName: id_number
required: true
type: NUMERIC
- fieldName: address
required: true
type: TEXT
- fieldName: address_flat
required: false
type: TEXT
- fieldName: address_number
required: true
type: NUMERIC
- fieldName: postal_code
required: true
type: TEXT
- fieldName: city
required: true
type: TEXT
- fieldName: state
required: true
type: CHOICE
choices:
- value: AR.BA
label: Buenos Aires
- value: AR.CB
label: Córdoba
- value: …
label: 24 provinces in total
- fieldName: phone
required: true
type: TEXT
- fieldName: registered_tax_payer
required: true
type: BOOLEAN
- fieldName: cuit
required: true
type: TEXT
- fieldName: net_income
required: true
type: CHOICE
choices:
- value: AR.A
label: Menos de 3.000.000 ARS
- value: …
label: 6 brackets in total
- fieldName: personal_activity
required: true
type: CHOICE
choices:
- value: AR.1
label: Empleado del Sector Privado
- value: …
label: 6 occupations in total
- fieldName: personal_activity_other
required: false
type: CHOICE
requiredIf:
fieldName: personal_activity
isOneOf:
- AR.3
- AR.4
choices:
- value: AR.1
label: Fabricación de joyas finas…
- value: …
label: 64 activities in total
Mexico:
summary: Mexico — 22 fields plus the address document
description: >-
`birthday_place` is the country of birth and shares the
`nationality` catalog. `address_photo` is only enforced for
accounts on the Ripio-provider widget flow.
value:
kycRequiredFields:
- fieldName: country
required: true
type: CHOICE
choices:
- value: MX
label: Mexico
- fieldName: first_name
required: true
type: TEXT
- fieldName: last_name
required: true
type: TEXT
- fieldName: birthday
required: true
type: DATE
- fieldName: id_number
required: true
type: NUMERIC
- fieldName: date_of_issue
required: true
type: TEXT
- fieldName: date_of_expiration
required: true
type: TEXT
- fieldName: nationality
required: true
type: CHOICE
choices:
- value: AR
label: AR
- value: BR
label: BR
- value: …
label: 233 codes in total
- fieldName: gender
required: false
type: CHOICE
choices:
- value: F
label: Femenino
- value: M
label: Masculino
- fieldName: address
required: true
type: TEXT
- fieldName: address_number
required: true
type: NUMERIC
- fieldName: address_flat
required: false
type: TEXT
- fieldName: city
required: true
type: TEXT
- fieldName: state
required: true
type: CHOICE
choices:
- value: MX.AG
label: Aguascalientes
- value: MX.JA
label: Jalisco
- value: …
label: 32 states in total
- fieldName: postal_code
required: true
type: TEXT
- fieldName: phone
required: true
type: TEXT
- fieldName: personal_activity
required: true
type: CHOICE
choices:
- value: MX.1000000
label: Empleado del Sector Privado
- value: …
label: 5 occupations in total
- fieldName: birthday_place
required: true
type: CHOICE
choices:
- value: AR
label: AR
- value: BR
label: BR
- value: …
label: 233 codes in total
- fieldName: rfc
required: true
type: TEXT
- fieldName: district
required: true
type: TEXT
- fieldName: terms_conditions
required: true
type: BOOLEAN
- fieldName: address_photo
required: true
type: FILE_UPLOAD
'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
components:
schemas:
KycRequirementsResponse:
type: object
properties:
kycRequiredFields:
type: array
items:
$ref: '#/components/schemas/KycRequiredField'
required:
- kycRequiredFields
ErrorResponse:
type: object
properties:
code:
type: integer
description: Application-specific error code.
type:
type: string
description: Type of error or exception.
detail:
type:
- object
- array
description: >-
Error details. The shape depends on the error:
- Most business errors return an object with a `message` key.
- Field validation errors return an object keyed by field name, each
holding an array of `{ message, code }`.
- Request-level validation errors (e.g. a missing query parameter)
return a bare array of `{ message, code }`.
properties:
message:
type: string
description: Detailed error message.
additionalProperties: true
status:
type: integer
description: HTTP status code.
required:
- code
- type
- detail
- status
KycRequiredField:
type: object
properties:
fieldName:
type: string
description: The technical name of the required field used within the API.
required:
type: boolean
description: Indicates whether the field is mandatory (true) or optional (false).
type:
type: string
description: >-
The data type expected for the field value (e.g., TEXT, DATE,
FILE_UPLOAD).
choices:
type: array
items:
type: object
properties:
value:
type: string
label:
type: string
description: >-
A list of valid options for the field. This is only present for
fields that have a predefined set of values.
required:
- fieldName
- required
- type
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 `.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.