POST /users migration guide — KYC/KYB required fields

Migration guide · Virtual accounts

Portage and ACT previously required different payloads. The products converge on one unified field set — one correctly filled POST /v1/users body covers everything. This guide lists every field that was added, changed, or removed.

This is the migration changelog — what moved and why. For the canonical, version-accurate field reference (enums aligned to the live spec), see Creating users and the Create a user API reference. The authoritative per-user “what’s still missing” list is always the missing_fields map on GET /v1/users/{id}.

Badge key

didn’t exist before — add it ACT users: add this field Portage users: add this field no longer required not applicable for this category no change needed

What changed per bank

Pick the bank you integrated with before. The right-hand column is the unified payload you send now.

How the user category is determined

Two fields drive the required set: type and address_country. The combination produces one of four categories.

Required fields

Select the user type to see every required field, its accepted values, and what changed per bank.

The per-bank badges for the identity and document fields tracked by the live missing_fields map (document_country, the document photos, immigration_status, additional_info, employment_status) are reconciled against that map. Provenance for the questionnaire fields (account_purpose, expected_*, current_employer, income_source) and for the KYB section is illustrative — those fields aren’t tracked by the map, so always confirm against GET /v1/users/{id} → missing_fields.

👤 KYC — Individual
🏢 KYB — Business

Category is set by address_country: "USA" → usa_individual, anything else → international_individual.

All fields from USA Individual apply. The differences are listed below.

Category is set by address_country: "USA" → usa_business, anything else → international_business.

All fields from USA Business apply. The differences are listed below.

Conditional field rules

Some fields are only required in specific situations. Here is what each condition means.

Condition	What it means	Example
`when X = Y`	Include the field only if the condition is true; otherwise omit it.	`occupation` is required only when `employment_status = "employed"`
`unless X = Y`	Include the field in all cases except when the condition is true.	`ssn` is required for everyone except non-US citizens
EDD individual	If `address_country` is in the EDD list (53 countries), also upload a proof-of-address document.	User from `MEX` → add `file_proof_of_address` to `identifying_information`
EDD business	Proof of address is required if any one is true: `address_country` in the EDD list, `formation_country` in the EDD list, or the company was formed within the last 180 days.	Company formed 3 months ago → add `file_proof_of_address` regardless of country

Country restrictions

All codes are ISO 3166-1 alpha-3. Rules apply to address_country unless otherwise noted.

🚫

Blocked — ineligible for all virtual-account products

Users with address_country in this list cannot create any virtual account.

⚠️

EDD countries — individual users (53 countries)

When address_country matches, a proof-of-address document is additionally required.

⚠️

EDD countries — business users (51 countries)

Same list minus GTM and CCK. Applies to address_country AND formation_country — also triggered if the company was formed within the last 180 days.

EDD trigger logic — business users

→

Example payloads

Complete POST /v1/users bodies for each category. Use the copy button and adapt for your integration; content fields take base64-encoded images.

{
  "type": "individual",
  "first_name": "Ana",
  "last_name": "García",
  "birth_date": "1990-04-22",
  "email": "ana@example.com",
  "phone": "+15551234567",
  "nationality": "USA",
  "address_street": "123 Main St",
  "address_city": "Austin",
  "address_state": "TX",
  "address_zip_code": "78701",
  "address_country": "USA",
  "document_type": "drivers_license",
  "document_number": "DL-987654321",
  "document_country": "USA",
  "employment_status": "employed",
  "occupation": "Software Engineer",
  "current_employer": "Acme Corp",
  "account_purpose": "receive_payments",
  "expected_monthly_volume": "10000_to_49999",
  "expected_transaction_count": "11_to_50",
  "identifying_information": [
    { "type": "ssn", "number": "XXX-XX-XXXX" },
    { "type": "front", "content": "<base64>" },
    { "type": "back",  "content": "<base64>" }
  ]
}

{
  "type": "individual",
  "first_name": "Carlos",
  "last_name": "Mendez",
  "birth_date": "1988-11-03",
  "email": "carlos@example.com",
  "phone": "+521234567890",
  "nationality": "MEX",
  "address_street": "Av. Reforma 456",
  "address_city": "Mexico City",
  "address_state": "CDMX",
  "address_zip_code": "06600",
  "address_country": "MEX",
  "document_type": "passport",
  "document_number": "G12345678",
  "document_country": "MEX",
  "immigration_status": "Non-Resident of U.S.",
  "employment_status": "self_employed",
  "income_source": "Freelance consulting",
  "account_purpose": "manage_professional_income",
  "expected_monthly_volume": "50000_to_199999",
  "expected_transaction_count": "11_to_50",
  "additional_info": {
    "has_us_bank_account": "No",
    "has_denied_bank_account": "No"
  },
  "identifying_information": [
    { "type": "front", "content": "<base64>" }
  ]
}

{
  "type": "business",
  "business_legal_name": "Acme Payments LLC",
  "business_type": "limited_liability_company",
  "formation_date": "2019-03-15",
  "formation_country": "USA",
  "email": "ops@acme.com",
  "phone": "+15551234567",
  "address_street": "100 Commerce Blvd",
  "address_city": "Austin",
  "address_state": "TX",
  "address_zip_code": "78701",
  "address_country": "USA",
  "account_purpose": "receive_payments_for_goods_and_services",
  "business_industry": ["telecommunications"],
  "business_description": "B2B SaaS payment processing platform",
  "source_of_funds": "sales_of_goods_and_services",
  "high_risk_industries": "No",
  "is_nbfi_vasp": "No",
  "business_legal_history": "No",
  "pep_status": false,
  "expected_monthly_volume": "100000_to_500000",
  "expected_transaction_count": "101_to_500",
  "identifying_information": [
    { "type": "ein", "number": "XX-XXXXXXX" },
    { "type": "file_business_formation", "content": "<base64>" }
  ],
  "associated_persons": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "birth_date": "1985-07-20",
      "email": "jane@acme.com",
      "nationality": "USA",
      "document_type": "passport",
      "document_number": "US123456789",
      "identifying_information": [
        { "type": "ssn", "number": "XXX-XX-XXXX" },
        { "type": "front", "content": "<base64>" }
      ]
    }
  ]
}

{
  "type": "business",
  "business_legal_name": "Global Trade SRL",
  "business_type": "corporation",
  "formation_date": "2021-06-01",
  "formation_country": "MEX",
  "email": "admin@globaltrade.mx",
  "phone": "+521234567890",
  "address_street": "Paseo de la Reforma 222",
  "address_city": "Mexico City",
  "address_zip_code": "06600",
  "address_country": "MEX",
  "document_number": "RFC-GLO210601ABC",
  "document_country": "MEX",
  "international_entity_type": "Sociedad de Responsabilidad Limitada",
  "account_purpose": "purchase_goods_and_services",
  "business_industry": ["real_estate"],
  "business_description": "Commercial real estate transactions across Latin America",
  "source_of_funds": "sales_of_goods_and_services",
  "high_risk_industries": "No",
  "is_nbfi_vasp": "No",
  "business_legal_history": "No",
  "pep_status": false,
  "expected_monthly_volume": "500000_to_1000000",
  "expected_transaction_count": "26_to_50",
  "additional_info": {
    "has_us_bank_account": "No",
    "has_denied_bank_account": "No"
  },
  "identifying_information": [
    { "type": "file_business_formation", "content": "<base64>" }
  ],
  "associated_persons": [
    {
      "first_name": "Luis",
      "last_name": "Torres",
      "birth_date": "1979-02-14",
      "email": "luis@globaltrade.mx",
      "nationality": "MEX",
      "document_type": "passport",
      "document_number": "G98765432",
      "document_country": "MEX",
      "identifying_information": [
        { "type": "front", "content": "<base64>" }
      ]
    }
  ]
}

Creating users — the canonical, version-accurate required-fields reference.
Create a user — API reference — full schema and live “Try it”.
For AI agents — eligible_products / missing_fields and conditional tokens.
Known limitations — sandbox auto-verification behavior and status vs verification_status.

Getting started

Core concepts

Migrations

Webhooks

POST /users migration guide — KYC/KYB required fields

Badge key

What changed per bank

How the user category is determined

Required fields

Conditional field rules

Country restrictions

Example payloads

​Badge key

​What changed per bank

​How the user category is determined

​Required fields

​Conditional field rules

​Country restrictions

​Example payloads

​Related

Badge key

What changed per bank

How the user category is determined

Required fields

Conditional field rules

Country restrictions

Example payloads

Related