> ## 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.
# KYC fields by country
> The KYC payload accepted by the Ramps API for Argentina, Brazil, Mexico and Colombia: which fields are required, what format each one takes, and the cross-field rules validated before the verification is opened.
This page covers the [partner-submitted KYC model](/ramps-api/kyc/kyc-via-api-overview), where you collect the customer's data and send it to [Submit KYC Information](/ramps-api/kyc/submit-kyc-information). If Ripio hosts the KYC, you do not send any of these fields — see [Ripio-hosted KYC](/ramps-api/kyc/kyc-with-ripio).
The four countries have **four different schemas**. A payload that is valid for Argentina is not valid for Colombia, and the `required` list in the API reference is only the intersection of the four. This page is the per-country matrix.
The authoritative, always-current list is the one your account returns from [Retrieve KYC Requirements](/ramps-api/kyc/retrieve-kyc-requirements) — it is already scoped to your account's country and carries the catalogs for every `CHOICE` field. Read it at integration time; use this page to understand what each field means and what format it takes.
Only the envelope is camelCase (`kycSubmission`, `redirectUrl`, `kycProviderShareToken`). Every field **inside** `kycSubmission` is snake\_case: `first_name`, `id_number_type`, `personal_activity_other`.
## Everything is validated before anything is created
Formats, catalog values and cross-field rules are checked at the API boundary. A bad value returns `400` with error code `20000` and **nothing is created**: no verification process is opened at the provider and the customer's KYC is not consumed. Correct the field and repeat the same call.
## What is normalized for you
Several fields are cleaned up before validation, so more payloads are accepted than a strict reading of the formats suggests:
* **Surrounding whitespace** is trimmed everywhere.
* **Catalog values are case-insensitive** — `cpf`, `cc` and `dni` are accepted and stored as `CPF`, `CC`, `DNI`.
* **Country-prefixed codes accept the bare form** — `SP` becomes `BR.SP`, `ba` becomes `AR.BA`, `a` becomes `AR.A`. The prefix is only added when the result is a real catalog value.
* **Documents, phones and postal codes tolerate separators** — `20-38804362-9`, `123.456.789-09`, `01310-100`, `B1665 DQJ` and `+54 (11) 2345-6789` are all valid.
* **Dates accept two formats** — `YYYY-MM-DD` and `DD/MM/YYYY`.
The value stored and echoed back is the **normalized** one, not the bytes you sent: `20-38804362-9` comes back as `20388043629`, `SP` as `BR.SP`. If you diff or round-trip KYC data, compare against the normalized form.
What is *not* forgiven is a **label where a code belongs**. `state`, `net_income`, `personal_activity`, `personal_activity_other`, `id_number_type` and `address_type` accept only the `value` from `/kycRequirements/` — `"Buenos Aires"` is rejected, `AR.BA` is correct. Labels are deliberately not resolved: `Buenos Aires` is the label of `AR.BA` and the colloquial name of `AR.DF`, so accepting it would file submissions under the wrong province.
Fields that a country does not accept are **ignored**, not rejected — sending `postal_code` for Colombia is harmless, but it is also not stored.
## Length limits
Text fields are capped, and the cap is the identity provider's own — a longer value is refused here rather than at the provider, where the rejection would arrive after the verification was already opened.
| Field | Max length |
| ------------------------------- | ---------- |
| `first_name`, `last_name` | 64 |
| `address`, `address_flat` | 255 |
| `address_number`, `postal_code` | 32 |
| `city` | 64 |
| `district` | 40 |
## Not every ISO country code is accepted
`nationality` and Mexico's `birthday_place` take an ISO 3166-1 alpha-2 code, but **sixteen current codes are refused**: `AX`, `BL`, `BQ`, `CD`, `CW`, `GG`, `IM`, `JE`, `ME`, `MF`, `MK`, `PS`, `RS`, `SS`, `SX`, `TL` — among them Serbia, Montenegro, North Macedonia, South Sudan, Palestine and DR Congo.
The reason is upstream: the identity provider's list predates the 2006 ISO revision, so it does not carry them. A customer with one of these nationalities cannot be verified today either way; refusing the value here means you get a legible `400` instead of an opaque one after the verification was opened. The list will shrink as the provider adds them.
You do not need to hardcode the exclusions: `nationality` and `birthday_place` are returned by [Retrieve KYC Requirements](/ramps-api/kyc/retrieve-kyc-requirements) as a `CHOICE` carrying the accepted codes, so a form built from that response never offers one of the sixteen.
***
## Argentina
| Field | Required | Format |
| ------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `country` | Yes | `AR` |
| `first_name`, `last_name` | Yes | Text |
| `gender` | Yes | `F` or `M` |
| `birthday` | Yes | Date. Age between 18 and 120, not in the future |
| `nationality` | Yes | ISO 3166-1 alpha-2 (`AR`), not `ARG`. [Some codes are refused](#not-every-iso-country-code-is-accepted) |
| `id_number` | Yes | 7 or 8 digits, no dots or spaces |
| `id_number_type` | No — defaults to `DNI` | `DNI`, `R_P` (temporary residency permit) or `OTHER` |
| `cuit` | Yes | 11 digits with a valid check digit. CUIL when `registered_tax_payer` is `false`, CUIT when `true` |
| `registered_tax_payer` | Yes | Boolean — whether the customer is a *responsable inscripto* |
| `address` | Yes | Street name |
| `address_number` | Yes | Street number |
| `address_flat` | No | Apartment / unit |
| `postal_code` | Yes | CP (`1012`) or CPA (`B1665DQJ`) |
| `city` | Yes | Text |
| `state` | Yes | Province code (`AR.BA`) |
| `phone` | Yes | E.164 |
| `net_income` | Published as required, not yet refused | Income bracket code, `AR.A`–`AR.F` |
| `personal_activity` | Published as required, not yet refused | Occupation code, `AR.1`–`AR.6` |
| `personal_activity_other` | Only for `AR.3` and `AR.4` | Detailed activity code, `AR.1`–`AR.64` |
Argentina does not use `district`.
`net_income` and `personal_activity` are published as required and **should** be sent — they are the regulatory intent and the API will start refusing payloads without them. Today a payload that omits them is still accepted, so that the integrations already live are not turned away; when the value *is* present it is validated against the catalog. Treat them as required when you build the form.
**Income brackets (`net_income`)**
| Code | Bracket |
| ------ | --------------------------- |
| `AR.A` | Under ARS 3,000,000 |
| `AR.B` | ARS 3,000,000 – 5,000,000 |
| `AR.C` | ARS 5,000,000 – 8,000,000 |
| `AR.D` | ARS 8,000,000 – 11,000,000 |
| `AR.E` | ARS 11,000,000 – 15,000,000 |
| `AR.F` | Over ARS 15,000,000 |
**Occupations (`personal_activity`)**
| Code | Occupation |
| ------ | -------------------------------------- |
| `AR.1` | Private-sector employee |
| `AR.2` | Public-sector employee |
| `AR.3` | Monotributista (simplified tax regime) |
| `AR.4` | Autónomo (self-employed) |
| `AR.5` | Retired / pensioner |
| `AR.6` | Student / homemaker / unemployed |
Province codes are in the `state` entry of `/kycRequirements/`, and the 64 detailed-activity codes in the `personal_activity_other` entry.
```bash theme={null}
curl --request POST \
--url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"kycSubmission": {
"country": "AR",
"first_name": "Mateo",
"last_name": "Romero",
"gender": "M",
"birthday": "1990-01-25",
"nationality": "AR",
"id_number": "11122233",
"id_number_type": "DNI",
"cuit": "20388043629",
"registered_tax_payer": false,
"address": "Libertad",
"address_number": "333",
"address_flat": "4B",
"postal_code": "B1665DQJ",
"city": "San Miguel",
"state": "AR.BA",
"phone": "+542211228855",
"net_income": "AR.A",
"personal_activity": "AR.1"
},
"redirectUrl": "https://www.example.com/"
}'
```
***
## Brazil
Brazil requires the fewest fields — only location, contact and income bracket. The identity fields are optional but recommended, since the provider collects them anyway during document upload.
| Field | Required | Format |
| -------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `country` | Yes | `BR` |
| `address` | Yes | Street name |
| `city` | Yes | Text |
| `state` | Yes | State code (`BR.SP`) |
| `postal_code` | Yes | CEP, 8 digits (`01310100`) |
| `phone` | Yes | E.164 |
| `net_income` | Yes | Income bracket code, `BR.A`–`BR.C` |
| `first_name`, `last_name` | No | Text |
| `birthday` | No | Date. Age between 18 and 120, not in the future |
| `nationality` | No | ISO 3166-1 alpha-2. [Some codes are refused](#not-every-iso-country-code-is-accepted) |
| `gender` | No | `F` or `M` |
| `id_number` | No | CPF (11 digits) or CNPJ (14 digits), check digits verified |
| `id_number_type` | No | `CPF` or `CNPJ` |
| `address_number`, `address_flat`, `district` | No | Text |
**Income brackets (`net_income`)**
| Code | Bracket |
| ------ | -------------------- |
| `BR.A` | Up to BRL 60,000 |
| `BR.B` | BRL 60,001 – 150,000 |
| `BR.C` | Over BRL 150,001 |
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 this request.
```bash theme={null}
curl --request POST \
--url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"kycSubmission": {
"country": "BR",
"first_name": "João",
"last_name": "Silva",
"birthday": "1990-06-15",
"nationality": "BR",
"gender": "M",
"id_number": "12345678909",
"id_number_type": "CPF",
"address": "Rua das Flores",
"address_number": "100",
"address_flat": "Apto 42",
"district": "Bela Vista",
"postal_code": "01310100",
"city": "São Paulo",
"state": "BR.SP",
"phone": "+5511999990000",
"net_income": "BR.A"
},
"redirectUrl": "https://www.example.com/"
}'
```
***
## Mexico
| Field | Required | Format |
| ------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------- |
| `country` | Yes | `MX` |
| `first_name`, `last_name` | Yes | Text |
| `birthday` | Yes | Date. Age between 18 and 120, not in the future |
| `nationality` | Yes | ISO 3166-1 alpha-2. [Some codes are refused](#not-every-iso-country-code-is-accepted) |
| `birthday_place` | Yes | **Country** of birth as ISO 3166-1 alpha-2 (`MX`) — not a city name. Same catalog as `nationality` |
| `id_number` | Yes | CURP, 18 characters |
| `rfc` | Yes | Mexican tax ID. Normalized but not format-checked |
| `date_of_issue` | Yes | Date. Cannot be in the future |
| `date_of_expiration` | Yes | Date. Must be later than `date_of_issue` |
| `address` | Yes | Street name |
| `address_number` | Yes | Street number |
| `address_flat` | No | Apartment / unit |
| `district` | Yes | Neighbourhood |
| `postal_code` | Yes | Text, not format-checked |
| `city` | Yes | Text |
| `state` | Yes | State code (`MX.JA`) |
| `phone` | Yes | E.164 |
| `personal_activity` | Yes | Occupation code (see below) |
| `terms_conditions` | Yes | Boolean |
| `gender` | No | `F` or `M` |
| `address_photo` | Only for provider-widget accounts | Base64 image, max 5 MB |
Mexico does not use `id_number_type` — the document is always a CURP.
**Occupations (`personal_activity`)**
| Code | Occupation |
| ------------ | ----------------------------------------- |
| `MX.1000000` | Private-sector employee |
| `MX.1136020` | Public-sector employee |
| `MX.1` | Independent professional / business owner |
| `MX.1135020` | Student / homemaker / unemployed |
| `MX.1135030` | Retired / pensioner |
`birthday_place` used to be documented as the city of birth. It is a **country code**: `Guadalajara` returns `400`, `MX` is correct.
```bash theme={null}
curl --request POST \
--url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"kycSubmission": {
"country": "MX",
"first_name": "Erick Eduardo",
"last_name": "Cuellar Garcia",
"birthday": "1998-12-11",
"nationality": "MX",
"birthday_place": "MX",
"id_number": "CUGE981211HJCLRR06",
"rfc": "HZDT240502GRA",
"date_of_issue": "2020-01-01",
"date_of_expiration": "2030-01-01",
"address": "Isla Cartagena",
"address_number": "123",
"district": "Jalisco",
"postal_code": "44950",
"city": "Guadalajara",
"state": "MX.JA",
"phone": "+523325606411",
"personal_activity": "MX.1000000",
"terms_conditions": true
},
"redirectUrl": "https://www.example.com/"
}'
```
***
## Colombia
| Field | Required | Format |
| ------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `country` | Yes | `CO` |
| `first_name`, `last_name` | Yes | Text |
| `birthday` | Yes | Date. Age between 18 and 120, not in the future |
| `nationality` | Yes | ISO 3166-1 alpha-2. [Some codes are refused](#not-every-iso-country-code-is-accepted) |
| `id_number` | Yes | Text, not format-checked |
| `id_number_type` | Yes | `CC`, `CE` or `PPT` |
| `address` | Yes | Street name |
| `address_number` | Yes | Street number |
| `address_type` | Yes | `SUIT`, `HOME` or `UNIT` |
| `district` | Yes | Neighbourhood |
| `city` | Yes | **DANE code** (`11001`), not the city name |
| `state` | Yes | Department code (`CO.DC`) |
| `phone` | Yes | E.164 |
Colombia does not use `postal_code` or `gender`.
**Document types (`id_number_type`)**
| Code | Document |
| ----- | ------------------------------- |
| `CC` | Cédula de ciudadanía |
| `CE` | Cédula de extranjería |
| `PPT` | Permiso por Protección Temporal |
**Dwelling types (`address_type`)**
| Code | Dwelling |
| ------ | --------- |
| `SUIT` | Apartment |
| `HOME` | House |
| `UNIT` | Unit |
The DANE codes are listed in the `city` entry of `/kycRequirements/`, and the department codes in `state`.
```bash theme={null}
curl --request POST \
--url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"kycSubmission": {
"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",
"district": "Chapinero",
"city": "11001",
"state": "CO.DC",
"phone": "+573001234567"
},
"redirectUrl": "https://www.example.com/"
}'
```
***
## Cross-field rules
Three rules cannot be read off the field list, and each returns `400` with error code `20000`.
**Argentina — `personal_activity_other` follows `personal_activity`.** It is required when `personal_activity` is `AR.3` (Monotributista) or `AR.4` (Autónomo), and optional for the other four occupations, which have a catalog entry of their own.
`personal_activity` and `personal_activity_other` are **different catalogs whose values overlap**. `AR.3` is "Monotributista" in the first and an unrelated activity in the second. Read each list from its own entry in `/kycRequirements/` — do not reuse one for the other.
**Colombia — `city` must belong to `state`.** The DANE code is preferred, but the API also accepts a city name when it matches a city in the declared department. Two different errors, on purpose:
| Message | What it means |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| `City 91001 does not belong to state CO.AN.` | Both values are valid codes, but they come from different records |
| `City No existe is not a known city for state CO.AM.` | The city value is neither a DANE code nor a known city name for that department |
**Mexico — `date_of_expiration` must be later than `date_of_issue`.** An already-expired document is accepted: whether it disqualifies the customer is decided by the KYC provider, not by this API.
***
## When validation fails
The response is `400` with error code `20000`. The offending fields are nested under `kycSubmission`, keyed by field name, each with a human-readable `message` and a stable `code` you can branch on:
```json theme={null}
{
"code": 20000,
"type": "ValidationError",
"detail": {
"kycSubmission": {
"phone": [
{
"message": "Enter the phone in E.164 format, including the country code (e.g. +5491123456789).",
"code": "invalid_phone"
}
]
}
},
"status": 400
}
```
| `code` | Meaning |
| ------------------ | ----------------------------------------------------------------------------- |
| `required` | A field this country requires is missing |
| `blank` / `null` | The field was sent empty. Omit it instead |
| `invalid_choice` | Not a value in that field's catalog — often a label sent where a code belongs |
| `invalid` | Malformed value, most often a date |
| `invalid_phone` | Not E.164, or missing the country code |
| `invalid_document` | Failed a document check — CUIT, CPF/CNPJ, CURP, CEP or postal code |
| `underage` | The customer is under 18 |
| `future` | A date that cannot be in the future |
| `implausible` | A date of birth over 120 years ago |
A `400` here means nothing was created. Correct the field and repeat the same call.