> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # POST /users migration guide โ€” KYC/KYB required fields > What changed in the POST /v1/users payload: every field added, changed, or removed as Portage and ACT converge on one unified field set, by user category. export const C = { blue: '#2F7FE0', green: '#0E8A63', amber: '#B4690E', red: '#CF3030', muted: '#8C959F', surface: 'rgba(127,127,127,0.05)', border: 'rgba(127,127,127,0.25)', borderSoft: 'rgba(127,127,127,0.18)', mono: 'ui-monospace, SFMono-Regular, Menlo, monospace' }; export const badgeTones = { new: { bg: C.green, fg: '#fff' }, portage: { bg: C.blue, fg: '#fff' }, act: { bg: C.amber, fg: '#fff' }, removed: { bg: C.red, fg: '#fff' }, na: { bg: C.red, fg: '#fff' }, ok: { bg: C.green, fg: '#fff' } }; export const Badge = ({tone = 'same', children}) => { if (tone === 'same') return {children}; const t = badgeTones[tone] || badgeTones.new; return {children}; }; export const pillTones = { new: C.green, changed: C.amber, removed: C.red, neutral: C.muted }; export const Pill = ({tone = 'neutral', children}) => {children}; export const Val = ({children}) => {children}; export const Hint = ({children}) => {children}; export const FieldGroup = ({title, children}) =>
{title}
{children}
; export const FieldRow = ({name, cond, badge, children}) =>
{name}{cond ? {cond} : null}
{badge}
{children}
; export const Subsection = ({children}) =>
{children}
; export const Chip = ({tone = 'edd', children}) => { const map = { blocked: { bg: 'rgba(207,34,46,0.10)', fg: C.red, bd: 'rgba(207,34,46,0.35)' }, edd: { bg: 'rgba(180,105,14,0.12)', fg: C.amber, bd: 'rgba(180,105,14,0.35)' } }; const c = map[tone] || map.edd; return {children}; }; export const ChipGrid = ({items, tone}) =>
{items.map(x => {x})}
; export const DiffWrap = ({children}) =>
{children}
; export const DiffCol = ({title, tone, children}) =>
{title}
{children}
; export const L = ({tone = 'neutral', children}) => { const c = tone === 'add' ? { color: C.green, background: 'rgba(11,110,79,0.12)' } : tone === 'rem' ? { color: C.red, background: 'rgba(207,34,46,0.10)' } : { opacity: 0.85 }; return
{children}
; }; export const VLine = ({h = 18, dashed = false}) =>
; export const Fork = () =>
; export const TNode = ({tone = 'blue', title, sub, dashed = false}) => { const col = C[tone] || C.blue; return
{title}
{sub ?
{sub}
: null}
; }; export const Diamond = ({children}) =>
{children}
; export const TreePanel = ({label, tone, children}) =>
{label}
{children}
; export const BLOCKED = ['๐Ÿ‡ฆ๐Ÿ‡ซ AFG', '๐Ÿ‡ง๐Ÿ‡พ BLR', '๐Ÿ‡ฒ๐Ÿ‡ฒ MMR', '๐Ÿ‡จ๐Ÿ‡ซ CAF', '๐Ÿ‡จ๐Ÿ‡ฎ CIV', '๐Ÿ‡จ๐Ÿ‡บ CUB', '๐Ÿ‡จ๐Ÿ‡ฉ COD', '๐Ÿ‡ฎ๐Ÿ‡ท IRN', '๐Ÿ‡ฎ๐Ÿ‡ถ IRQ', '๐Ÿ‡ฑ๐Ÿ‡ท LBR', '๐Ÿ‡ฑ๐Ÿ‡พ LBY', '๐Ÿ‡ฐ๐Ÿ‡ต PRK', '๐Ÿ‡ท๐Ÿ‡บ RUS', '๐Ÿ‡ธ๐Ÿ‡ฆ SAU', '๐Ÿ‡ธ๐Ÿ‡ด SOM', '๐Ÿ‡ธ๐Ÿ‡ฉ SDN', '๐Ÿ‡ธ๐Ÿ‡พ SYR', '๐Ÿ‡บ๐Ÿ‡ฆ UKR', '๐Ÿ‡พ๐Ÿ‡ช YEM', '๐Ÿ‡ป๐Ÿ‡ช VEN', '๐Ÿ‡ฟ๐Ÿ‡ผ ZWE']; export const EDD_IND = ['๐Ÿ‡ฉ๐Ÿ‡ฟ DZA', '๐Ÿ‡ฆ๐Ÿ‡ด AGO', '๐Ÿ‡ฆ๐Ÿ‡ฒ ARM', '๐Ÿ‡ฆ๐Ÿ‡ฟ AZE', '๐Ÿ‡ง๐Ÿ‡ธ BHS', '๐Ÿ‡ง๐Ÿ‡ญ BHR', '๐Ÿ‡ง๐Ÿ‡ฉ BGD', '๐Ÿ‡ง๐Ÿ‡ฒ BMU', '๐Ÿ‡ง๐Ÿ‡ด BOL', '๐Ÿ‡ป๐Ÿ‡ฌ VGB', '๐Ÿ‡ง๐Ÿ‡ณ BRN', '๐Ÿ‡ง๐Ÿ‡ซ BFA', '๐Ÿ‡ฐ๐Ÿ‡ญ KHM', '๐Ÿ‡จ๐Ÿ‡ฒ CMR', '๐Ÿ‡จ๐Ÿ‡ฝ CXR', '๐Ÿ‡จ๐Ÿ‡จ CCK', '๐Ÿ‡จ๐Ÿ‡ท CRI', '๐Ÿ‡จ๐Ÿ‡พ CYP', '๐Ÿ‡ช๐Ÿ‡ฌ EGY', '๐Ÿ‡ธ๐Ÿ‡ป SLV', '๐Ÿ‡ฌ๐Ÿ‡ฎ GIB', '๐Ÿ‡ฌ๐Ÿ‡ท GRC', '๐Ÿ‡ฌ๐Ÿ‡น GTM', '๐Ÿ‡ฌ๐Ÿ‡ฌ GGY', '๐Ÿ‡ญ๐Ÿ‡น HTI', '๐Ÿ‡ญ๐Ÿ‡ณ HND', '๐Ÿ‡ฎ๐Ÿ‡ฉ IDN', '๐Ÿ‡ฎ๐Ÿ‡ฒ IMN', '๐Ÿ‡ฏ๐Ÿ‡ช JEY', '๐Ÿ‡ฏ๐Ÿ‡ด JOR', '๐Ÿ‡ฐ๐Ÿ‡ฟ KAZ', '๐Ÿ‡ฐ๐Ÿ‡ช KEN', '๐Ÿ‡ฐ๐Ÿ‡ผ KWT', '๐Ÿ‡ฑ๐Ÿ‡ง LBN', '๐Ÿ‡ฑ๐Ÿ‡ฎ LIE', '๐Ÿ‡ฒ๐Ÿ‡พ MYS', '๐Ÿ‡ฒ๐Ÿ‡จ MCO', '๐Ÿ‡ฒ๐Ÿ‡ณ MNG', '๐Ÿ‡ฒ๐Ÿ‡ฟ MOZ', '๐Ÿ‡ณ๐Ÿ‡ฎ NIC', '๐Ÿ‡ณ๐Ÿ‡ฌ NGA', '๐Ÿ‡ด๐Ÿ‡ฒ OMN', '๐Ÿ‡ต๐Ÿ‡ฌ PNG', '๐Ÿ‡ต๐Ÿ‡พ PRY', '๐Ÿ‡ต๐Ÿ‡ญ PHL', '๐Ÿ‡ฟ๐Ÿ‡ฆ ZAF', '๐Ÿ‡ฑ๐Ÿ‡ฐ LKA', '๐Ÿ‡น๐Ÿ‡ญ THA', '๐Ÿ‡น๐Ÿ‡น TTO', '๐Ÿ‡น๐Ÿ‡ณ TUN', '๐Ÿ‡บ๐Ÿ‡ฌ UGA', '๐Ÿ‡บ๐Ÿ‡ฟ UZB', '๐Ÿ‡ป๐Ÿ‡ณ VNM']; export const EDD_BIZ = EDD_IND.filter(s => !s.includes('GTM') && !s.includes('CCK'));
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.

+13 new fields20 fields unified across banks2 fields removed4 user categories
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](/guides/creating-users) and the [Create a user](/api-reference/users/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
new didn't exist before โ€” add it was Portage only ACT users: add this field was ACT only Portage users: add this field removed no longer required N/A 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. {'{'} {' "type": "individual",'} {' "first_name": "Ana",'} {' "address_country": "USA",'} {' "employment_status": "employed",'} {' "account_purpose": "receive_payments",'} {' "document_country": "USA",'} {' // โœ— no expected_monthly_volume'} {' // โœ— no expected_transaction_count'} {' // โœ— no current_employer'} {' // โœ— no income_source'} {'}'} {'{'} {' "type": "individual",'} {' "first_name": "Ana",'} {' "address_country": "USA",'} {' "document_country": "USA",'} {' "employment_status": "employed",'} {' "account_purpose": "receive_payments",'} {' "expected_monthly_volume": "10000_to_49999",'} {' "expected_transaction_count": "11_to_50",'} {' "current_employer": "Acme Corp",'} {' "occupation": "Engineer",'} {'}'} {'{'} {' "type": "individual",'} {' "first_name": "Ana",'} {' "address_country": "USA",'} {' "document_country": "MEX",'} {' "employment_status": "employed",'} {' "immigration_status": "Non-Resident of U.S.",'} {' // โœ— no account_purpose'} {' // โœ— no expected_monthly_volume'} {' // โœ— no expected_transaction_count'} {' // โœ— no income_source'} {'}'} {'{'} {' "type": "individual",'} {' "first_name": "Ana",'} {' "address_country": "USA",'} {' "document_country": "MEX",'} {' "employment_status": "employed",'} {' "account_purpose": "receive_payments",'} {' "expected_monthly_volume": "10000_to_49999",'} {' "expected_transaction_count": "11_to_50",'} {' "current_employer": "Acme Corp",'} {' "occupation": "Engineer",'} {'}'} ## How the user category is determined Two fields drive the required set: `type` and `address_country`. The combination produces one of four categories.
address\_country?
= USA
โ‰  USA
 address\_country?
= USA
โ‰  USA
## 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`. Category is set by `address_country`: `"USA"` โ†’ usa\_individual, anything else โ†’ international\_individual. ๐Ÿ‡บ๐Ÿ‡ธ USA Individual โ€”}>Free text โ€”}>ISO 8601 โ€” e.g. 1990-01-15 โ€”}>Email string ยท phone string โ€”}>ISO alpha-3 โ€” e.g. USA MEX COL โ€”}>Free text; address\_country = ISO alpha-3 โ€”}>passport drivers\_license national\_id โ€”}>ISO alpha-3Required by both Portage and ACT (per the live missing\_fields map) โ€”}>Sent as {'identifying_information: [{type:"ssn", number:"..."}]'} was Portage only}>Document photoPortage required it; ACT did not โ€” now required for all banks was Portage only}>Document photoPortage required it; ACT did not โ€” now required for all banks was Portage only}>receive\_payments manage\_professional\_income make\_payments manage\_personal\_funds investment\_tradingWas excluded for ACT individuals โ€” now required for all banks was ACT only}>employed self\_employed unemployed retired studentACT required it; Portage did not โ€” now required for all banks new}>less\_than\_10000 10000\_to\_49999 50000\_to\_199999 200000\_to\_999999 1000000\_or\_more new}>1\_to\_10 11\_to\_50 51\_to\_200 more\_than\_200 โ€”}>Free text was ACT only}>Free textWas ACT-only โ€” now required for all banks new}>Free text โ€” required for retired student unemployed self\_employed was Portage only}>Proof of address documentPortage required it at base; for ACT and the unified flow it's required under EDD ๐ŸŒŽ International Individual All fields from **USA Individual** apply. The differences are listed below. N/A}>Not required for international individuals was ACT only}>Common values: U.S. Citizen Permanent U.S. Resident Non-Permanent U.S. Resident Non-Resident of U.S.Free text โ€” these are the common values but not a strict enum was ACT only}>Yes NoWas ACT-only โ€” now required for all banks was ACT only}>Yes NoWas ACT-only โ€” now required for all banks Category is set by `address_country`: `"USA"` โ†’ usa\_business, anything else โ†’ international\_business. ๐Ÿ‡บ๐Ÿ‡ธ USA Business โ€”}>Free text โ€”}>limited\_liability\_company corporation general\_partnership limited\_liability\_partnership sole\_proprietor non\_profit trust government\_organization publicly\_traded\_company โ€”}>ISO 8601 โ€” e.g. 2019-03-01 was Portage only}>ISO alpha-3Was missing in Portage โ€” now required for all banks was ACT only}>Email ยท phone stringphone was missing in ACT was Portage only}>Free text; country = ISO alpha-3address\_state was missing in Portage โ€”}>Sent as {'identifying_information: [{type:"ein", number:"..."}]'} was ACT only}>Business formation documentWas missing in ACT โ€” now required for all banks removed}>No longer required โ€”}>charitable\_donations ecommerce\_retail\_payments investment\_purposes purchase\_goods\_and\_services receive\_payments\_for\_goods\_and\_services internal\_treasury third\_party\_money\_transmission was ACT only}>NAICS codes โ€” e.g. telecommunications real\_estate food\_manufacturingWas missing in ACT โ€” now required for all banks new}>Free text new}>business\_loans inter\_company\_funds investment\_proceeds owners\_capital sales\_of\_goods\_and\_services tax\_refund third\_party\_funds treasury\_reserves new}>Yes No new}>Yes No new}>Yes No new}>true false (boolean) new}>less\_than\_50000 50000\_to\_100000 100000\_to\_500000 500000\_to\_1000000 1000000\_to\_5000000 5000000\_to\_10000000 more\_than\_10000000 new}>less\_than\_10 10\_to\_25 26\_to\_50 51\_to\_100 101\_to\_500 more\_than\_500 โ€”}>Array of UBO/director objects was Portage only}>Free textWas missing in Portage was Portage only}>ISO 8601Was missing in Portage was Portage only}>Valid emailWas missing in Portage was Portage only}>ISO alpha-3Was missing in Portage was Portage only}>SSN stringWas missing in Portage new}>Free text was Portage only}>Free textWas missing in Portage was ACT only}>Document photoWas missing in ACT was ACT only}>Document photoWas missing in ACT new}>Proof of address document ๐ŸŒŽ International Business All fields from **USA Business** apply. The differences are listed below. N/A}>Not required for international entities required}>Still required for international entities โ€” state / province / department of the business address required}>Required for international entities โ€” free text new}>ISO alpha-3 was ACT only}>Free textWas ACT-only โ€” now required for all banks was ACT only}>Yes NoWas ACT-only โ€” now required for all banks was ACT only}>Yes NoWas ACT-only โ€” now required for all banks was ACT only}>ISO alpha-3 โ€” required for international UBOs ## 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
OR
OR
โ†’
## 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. ```json ๐Ÿ‡บ๐Ÿ‡ธ KYC Individual theme={null} { "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": "" }, { "type": "back", "content": "" } ] } ``` ```json ๐ŸŒŽ KYC Intl Individual theme={null} { "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": "" } ] } ``` ```json ๐Ÿ‡บ๐Ÿ‡ธ KYB Business theme={null} { "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": "" } ], "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": "" } ] } ] } ``` ```json ๐ŸŒŽ KYB Intl Business theme={null} { "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": "" } ], "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": "" } ] } ] } ``` ## Related * [Creating users](/guides/creating-users) โ€” the canonical, version-accurate required-fields reference. * [Create a user โ€” API reference](/api-reference/users/create-a-user) โ€” full schema and live "Try it". * [For AI agents](/guides/for-ai-agents) โ€” `eligible_products` / `missing_fields` and conditional tokens. * [Known limitations](/guides/known-limitations) โ€” sandbox auto-verification behavior and `status` vs `verification_status`.