KYC fields by country

This page covers the partner-submitted KYC model, where you collect the customer’s data and send it to Submit KYC Information. If Ripio hosts the KYC, you do not send any of these fields — see Ripio-hosted KYC.

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 — 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 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
`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.

curl --request POST \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
  --header 'Authorization: Bearer <token>' \
  --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
`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.

curl --request POST \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
  --header 'Authorization: Bearer <token>' \
  --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
`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.

curl --request POST \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
  --header 'Authorization: Bearer <token>' \
  --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
`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.

curl --request POST \
  --url https://{baseUrl}/api/v1/customers/{customerId}/kyc/ \
  --header 'Authorization: Bearer <token>' \
  --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:

{
  "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.

Overview

Widget integration

API Integration

Everything is validated before anything is created

What is normalized for you

Length limits

Not every ISO country code is accepted

Argentina

Brazil

Mexico

Colombia

Cross-field rules

When validation fails

​Everything is validated before anything is created

​What is normalized for you

​Length limits

​Not every ISO country code is accepted

​Argentina

​Brazil

​Mexico

​Colombia

​Cross-field rules

​When validation fails

Everything is validated before anything is created

What is normalized for you

Length limits

Not every ISO country code is accepted

Argentina

Brazil

Mexico

Colombia

Cross-field rules

When validation fails