> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating V1 Customers to V2
> Field-by-field checklist of the additional information required to bring already-approved V1 individual and business customers up to V2 parity.
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:
1. **New required fields**: not collected at all in V1. You must go back to the customer for these.
2. **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.
3. **Conditionally required fields**: only required for a subset of customers (a specific entity type, ownership structure, or risk profile).
### 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](https://developer.fin.com/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
1. **Pull the V1 record** for each customer via [Get Customer Details](/api-reference/customers/get-customer-details) and apply the "remap" tables above first. This closes most of the gap with zero customer contact.
2. **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.
3. **Classify business customers against NAICS** before or during the form, since `industry_codes` has no reliable mapping from the V1 `business_industry_id`.
4. **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.
5. 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.