Migrating V1 Customers to V2

V1 and V2 customer records both remain fully supported. This guide is for clients who have approved customers created through the V1 endpoints and want those records to carry the same information V2 collects, typically ahead of moving their integration to V2.

There is currently no dedicated endpoint that backfills V2 fields onto an existing customer record. This guide defines the data gap only: exactly which fields your already-approved V1 customers are missing relative to a V2 customer. Use it to build a one-time data-collection form for your end users, then coordinate with your Fin.com contact on how the collected values get applied to the existing record. Fields fall into three buckets:

New required fields: not collected at all in V1. You must go back to the customer for these.
Renamed or reshaped fields: the data already exists in your V1 record under a different name or shape. No new customer input is needed, just remapping.
Conditionally required fields: only required for a subset of customers (a specific entity type, ownership structure, or risk profile).

Individual Customers
Business Customers

1. New information to collect

Field	Location	V2 requirement	Why V1 doesn’t have it
`employment_status`	`financial_profile`	Required. Enum: `EMPLOYED`, `SELF_EMPLOYED`, `RETIRED`, `STUDENT`, `UNEMPLOYED`	Not part of V1’s financial profile at all
`tax_info[].document_type`	`basic_info`	Required for each tax document (e.g. `SSN`, `TIN`)	V1 stored only a raw `tin` string with no document type

2. Remap from existing V1 data (no customer contact needed)

V1 field	V2 field	Note
`basic_info.nationality`	`basic_info.primary_nationality`	Same value, renamed
`basic_info.tin`	`basic_info.tax_info[0].document_id`	Pair with `country_code` (use `country_of_residence` unless you know otherwise) and the `document_type` collected above
`address.street`	`address.street_line_1`	Same value, renamed
`address.state`	`address.subdivision_code`	Same value, renamed. Confirm it’s a valid ISO 3166-2 code
`financial_profile.source_of_fund_id`	`financial_profile.source_of_fund_ids`	Wrap the existing single ID in a one-item array

3. Conditionally required

Field	Required when	Notes
`basic_info.secondary_nationality`	Customer holds dual citizenship	Optional otherwise
`basic_info.gender`	Never required	Optional field, not collected in V1
`first_name_en`, `last_name_en`, `middle_name_en`, `street_line_1_en`, `street_line_2_en`	The corresponding field contains non-ASCII characters	V1 already restricts all input to English (Latin) characters, so this is unlikely to apply to any V1 record
`financial_profile.source_of_funds_description`, `financial_profile.purpose_remarks`	Never required	Optional context fields, safe to leave blank during migration

V2 also validates that address.country matches basic_info.country_of_residence. Check this against your existing V1 records: if they diverge, you’ll need to confirm which one is correct with the customer before submitting.

1. New information to collect

Field	Location	V2 requirement	Why V1 doesn’t have it
`industry_codes`	Root	Required, min 1 item. NAICS 2022 6-digit codes. See Business industry codes	V1’s `business_industry_id` is an internal catalogue ID that doesn’t map one-to-one to NAICS codes. Treat this as a fresh classification, not a lookup
`basic_info.trade_name`	`basic_info`	Required	V1’s equivalent, `business_trade_name`, is optional. Businesses that skipped it in V1 must provide one now
`basic_info.tax_info[].document_type`	`basic_info`	Required for each tax document (e.g. `EIN`, `VAT_ID`)	V1 stored only a raw `tax_id` string
`financial_profile.estimated_annual_revenue_usd`	`financial_profile`	Required	Not collected in V1
`financial_profile.expected_monthly_deposits_usd` and `expected_monthly_withdrawals_usd`	`financial_profile`	Both required	V1 collected one combined `monthly_volume`. V2 splits it by direction, so you need the deposit/withdrawal breakdown, not just the total
`financial_profile.source_of_wealth_ids`	`financial_profile`	Required, min 1 item	Not collected for businesses in V1 at all
`associated_parties[].roles`	Each associated party	Required, min 1 item (`shareholder`, `ubo`)	V1 has no explicit role list; ownership was implied by `ownership_info` alone
`associated_parties[].ownership_info.has_control`, `.is_signer`, `.is_director`	Each associated party with `ubo` role	All three required	None of these booleans exist in V1’s `ownership_info`
`associated_parties[].basic_info.tax_info[].document_type`	Each associated party	Required	V1 stored only a raw `tin` string per party

2. Remap from existing V1 data (no customer contact needed)

V1 field	V2 field	Note
`basic_info.business_name`	`basic_info.legal_name`	Same value, renamed
`basic_info.website`	`basic_info.websites`	Wrap the existing single URL in a one-item array
`basic_info.tax_id`	`basic_info.tax_info[0].document_id`	Pair with `country_code` and the `document_type` collected above
`addresses.incorporated_address.street` / `physical_address.street`	`street_line_1`	Same value, renamed. Applies to both the incorporated and physical address
`addresses.*.state`	`addresses.*.subdivision_code`	Same value, renamed
`financial_profile.source_of_fund_id`	`financial_profile.source_of_fund_ids`	Wrap the existing single ID in a one-item array
`financial_profile.other_purpose`	`financial_profile.purpose_remarks`	Same value, renamed
`associated_parties[].basic_info.nationality`	`.primary_nationality`	Same value, renamed
`associated_parties[].basic_info.tin`	`.tax_info[0].document_id`	Same pairing as the business-level tax ID above
`associated_parties[].address.street` / `.state`	`.street_line_1` / `.subdivision_code`	Same value, renamed

3. Conditionally required

Field	Required when	Notes
`public_listings`	`entity_type` is `PUBLICLY_LISTED_COMPANY`	Not applicable to most V1 businesses, but check entity type before skipping
`holding_structure.corporate_shareholders` and `foreign_branches`	The business has non-individual (corporate) shareholders or registered foreign branches	V1 has no way to represent a corporate shareholder, only individual associated parties. If a V1 business’s ownership was flattened to individuals for compliance purposes, you may need to reconstruct the actual corporate structure
`compliance.regulated_activity`	The business holds a financial services license or regulatory registration	Required fields: `description`, `primary_authority_country_code`, `primary_authority_name`, `license_number`
`compliance.aml` and `compliance.risk_profile`	`financial_profile.third_party_fund_usage` is `true`, or the business is an MSB, payment processor, or otherwise moves funds on behalf of others	This is the largest new collection area for regulated/high-risk businesses migrating from V1, since V1 has no compliance section at all
`basic_info.legal_entity_identifier` (LEI)	Never required	Optional 20-character code
`basic_info.is_dao`	Never required	Optional, defaults to false if omitted

V1’s entity_type enum includes PRIVATE_LIMITED, which V2 does not support. Any V1 business customer with entity_type: PRIVATE_LIMITED needs to be remapped to a V2-supported value (typically LIMITED_LIABILITY_COMPANY) as part of migration.

Suggested approach

Pull the V1 record for each customer via Get Customer Details and apply the “remap” tables above first. This closes most of the gap with zero customer contact.
Build a short data-collection form covering only the “new information to collect” fields, plus any “conditionally required” fields that apply based on the customer’s existing entity_type or third_party_fund_usage value.
Classify business customers against NAICS before or during the form, since industry_codes has no reliable mapping from the V1 business_industry_id.
Flag regulated or high-risk businesses separately. The compliance section is the largest single gap for these customers and may need input from their compliance team, not just a self-serve form.
Talk to your Fin.com contact about how the completed dataset gets written back to the existing customer record, since there is no self-serve backfill endpoint today.

​1. New information to collect

​2. Remap from existing V1 data (no customer contact needed)

​3. Conditionally required

​1. New information to collect

​2. Remap from existing V1 data (no customer contact needed)

​3. Conditionally required

​Suggested approach

1. New information to collect

2. Remap from existing V1 data (no customer contact needed)

3. Conditionally required

1. New information to collect

2. Remap from existing V1 data (no customer contact needed)

3. Conditionally required

Suggested approach