> ## 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.

# Create Business Customer V2

> Create a new business customer with full KYB profile, associated parties (UBOs/directors), compliance data, and optionally holding structure and public listing details.

## Important Requirements

* **Email Address**: Must be all lowercase or you will receive a validation error
* **RELIANCE Verification**: If you attempt to use `RELIANCE` verification type but it's not enabled for your client, you will receive a 423 error with message: "RELIANCE is not available for your client"
* **Non-ASCII characters**: If any input field contains non-ASCII characters, you must provide a transliterated (Latin) value in the corresponding `_en` field (e.g., `legal_name_en`, `street_line_1_en`, `first_name_en`)
* **Third-party Fund Usage**: The `third_party_fund_usage` field indicates whether this customer will be moving other people's money
* **Ownership Percentages**: The total ownership percentages of all associated parties must add up to more than 0 and less than 100
* **Reference Data**: `purpose_id`, `source_of_fund_ids` and `source_of_wealth_ids` are integer foreign keys — fetch valid values from [List Account Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes) , [List Source of Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds) and [List Source of Wealth](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth)
* **subdivision\_code**: Pass the ISO 3166-2 code. For example for CA, pass US-CA.


## OpenAPI

````yaml POST /v2/customers/business
openapi: 3.1.0
info:
  title: Fin.com API
  version: 1.0.0
  description: A simple API specification
servers:
  - url: https://sandbox.api.fin.com
    description: Sandbox server
  - url: https://api.fin.com
    description: Production server
security: []
tags:
  - name: Authentication
    description: A modified OAuth 2.0 Client Credential Flow
  - name: Customers
    description: Customer management and document upload operations
  - name: Balances
    description: Retrieve wallet balance information
  - name: Catalogue
    description: |
      A set of endpoints to retrieve contextual data to assemble requests
      to fin.com's API
  - name: Beneficiaries
    description: Manage beneficiary accounts for payments and transfers
  - name: Transactions
    description: Transaction history and management for beneficiaries
  - name: Virtual Accounts
    description: Create and manage virtual accounts for USD to USDC conversions
  - name: Fees & FX Rates
    description: Retrieve fees and foreign exchange rates
paths:
  /v2/customers/business:
    post:
      tags:
        - Customers
      summary: Create Business Customer V2
      description: >-
        Create a new business customer with full KYB profile, associated parties
        (UBOs/directors), compliance data, and optionally holding structure and
        public listing details.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBusinessCustomerV2Input'
            example:
              verification_type: STANDARD
              industry_codes:
                - '541512'
                - '522390'
              basic_info:
                legal_name: Fin.com
                legal_name_en: Fin.com
                trade_name: Toronggo
                trade_name_en: Toronggo
                description: >-
                  Bangladesh-based technology company providing cross-border B2B
                  payment and financial technology services to enterprise
                  clients
                entity_type: LIMITED_LIABILITY_COMPANY
                email: m@tech.com
                phone: '+8801529876543'
                incorporation_date: '2018-06-15'
                country_of_incorporation: BGD
                registration_number: C-123456/2018
                is_dao: false
                tax_info:
                  - country_code: BGD
                    document_type: TIN
                    document_id: '123456789012'
                websites:
                  - https://fin.com
              financial_profile:
                purpose_id: 3
                purpose_remarks: Cross-border B2B payments for international suppliers
                source_of_fund_ids:
                  - 1
                  - 4
                source_of_funds_description: Revenue from software licensing and technology services
                source_of_wealth_ids:
                  - 2
                estimated_annual_revenue_usd: 5000000
                expected_monthly_deposits_usd: 400000
                expected_monthly_withdrawals_usd: 350000
                expected_transaction_value_usd: 50000
                expected_monthly_transaction_count: 20
                third_party_fund_usage: false
              addresses:
                is_incorporated_address_same: false
                incorporated_address:
                  street_line_1: House 12, Road 4, Dhanmondi
                  city: Dhaka
                  state: BD-13
                  subdivision_code: BD-13
                  postal_code: '1205'
                  country: BGD
                physical_address:
                  street_line_1: Level 5, 45 Gulshan Avenue
                  city: Dhaka
                  state: BD-13
                  subdivision_code: BD-13
                  postal_code: '1212'
                  country: BGD
              associated_parties:
                - ref: owner-001
                  basic_info:
                    first_name: Fatima
                    last_name: Rahman
                    dob: '1990-05-15'
                    email: fatima.rahman22@acmecorp.com.bd
                    phone: '+8801711223344'
                    country_of_residence: BGD
                    primary_nationality: BGD
                    tax_info:
                      - country_code: BGD
                        document_type: TIN
                        document_id: '1234567890123'
                  address:
                    street_line_1: House 12, Road 4, Dhanmondi
                    city: Dhaka
                    state: BD-13
                    subdivision_code: BD-13
                    postal_code: '1205'
                    country: BGD
                  roles:
                    - shareholder
                  ownership_info:
                    designation: CEO & Founder
                    percentage_of_ownership: 60
                    relationship_establishment_date: '2018-06-15'
                    has_control: true
                    is_signer: true
                    is_director: true
                - ref: owner-002
                  basic_info:
                    first_name: Karim
                    last_name: Islam
                    dob: '1992-08-22'
                    email: karim.islam22@acmecorp.com.bd
                    phone: '+8801822334455'
                    country_of_residence: BGD
                    primary_nationality: BGD
                    tax_info:
                      - country_code: BGD
                        document_type: TIN
                        document_id: '9876543210123'
                  address:
                    street_line_1: Flat 3B, 78 Mirpur Road
                    city: Dhaka
                    state: BD-13
                    subdivision_code: BD-13
                    postal_code: '1216'
                    country: BGD
                  roles:
                    - ubo
                  ownership_info:
                    designation: CTO & Co-Founder
                    percentage_of_ownership: 40
                    relationship_establishment_date: '2018-06-15'
                    has_control: false
                    is_signer: false
                    is_director: false
              holding_structure:
                has_material_intermediary_ownership: true
                corporate_shareholders:
                  - entity_name: Toronggo Ventures Limited
                    entity_name_en: Toronggo Ventures Limited
                    registration_country_code: BGD
                    ownership_percentage: 0
                    registration_number: C-987654/2015
                    entity_type: LIMITED_LIABILITY_COMPANY
                    incorporation_date: '2015-03-01'
              compliance:
                operates_in_prohibited_countries: false
                additional_description_for_compliance_screening: We do not operate in any OFAC-sanctioned jurisdictions.
                risk_profile:
                  high_risk_activities:
                    - adult_entertainment
                  high_risk_activities_explanation: >-
                    We facilitate cross-border B2B payments, subject to enhanced
                    due diligence.
                  conducts_money_services: true
                  conducts_money_services_via_fin: false
                  conducts_money_services_description: >-
                    Licensed payment service provider offering international
                    transfer services.
                regulated_activity:
                  description: >-
                    Licensed payment service provider under Bangladesh Bank
                    regulation
                  primary_authority_country_code: BGD
                  primary_authority_name: Bangladesh Bank
                  license_number: PSP-2019-00123
                aml:
                  supervisory_authority_name: Bangladesh Financial Intelligence Unit
                  license_number: PSP-2019-00123
                  has_appointed_mlro: true
                  customer_risk_split:
                    low_risk: 70
                    medium_risk: 25
                    high_risk: 5
                  prohibits_anonymous_or_fictitious_accounts: true
                  prohibits_accounts_for_unlicensed_or_shell_customers: true
                  customer_identity_verification:
                    method: automated
                    system: Jumio
                  pep_and_sanctions_screening:
                    method: automated
                    system: Dow Jones Risk & Compliance
                  sanction_lists:
                    - OFAC
                    - EU
                    - UN
                    - HMT
                  customer_risk_classification_from_due_diligence: true
                  enhanced_due_diligence_process: true
                  transaction_monitoring:
                    method: automated
                    system: Actimize
                  procedures_for_transaction_monitoring: true
                  subject_to_ml_or_tf_investigation: none
                  subject_to_regulatory_enforcement_past_2_years: none
                  confirms_no_service_to_sanctioned_countries: true
                  client_funds_accessibility: closed_loop
                  aml_ctf_audit_completed: true
                  planned_audit_date: '2026-12-01'
              meta_data:
                reference: REF-20250123-TORONGGO
      responses:
        '201':
          description: Business customer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_id:
                    type: string
                    format: uuid
                    description: Unique identifier for the created customer
                    example: ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06
                  tos_policies_url:
                    type: string
                    format: uri
                    description: >-
                      URL for customer to accept Terms of Service. Parse the
                      tos_policies_value query parameter and pass it when
                      attaching business documents.
                    example: >-
                      https://orchestration.fin.com/orchestration-customer-tos?customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06&tos_policies_value=6955e70b-f9f3-4076-b1ce-5c897085dd24
        '400':
          description: Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Validation failed
                  data:
                    type: object
                    additionalProperties:
                      type: string
                    example:
                      basic_info.email: Must be a valid email address
                      associated_parties[0].basic_info.dob: Party must be at least 18 years old
                      addresses.physical_address: Required when is_incorporated_address_same is false
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '423':
          description: Locked — RELIANCE verification is not available for your client
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 423
                  message:
                    type: string
                    example: RELIANCE is not available for your client
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal server error
      security:
        - bearerAuth: []
components:
  schemas:
    CreateBusinessCustomerV2Input:
      type: object
      required:
        - verification_type
        - industry_codes
        - basic_info
        - financial_profile
        - addresses
        - associated_parties
      properties:
        verification_type:
          type: string
          enum:
            - STANDARD
            - RELIANCE
          description: >-
            Verification level. Defaults to STANDARD if omitted. RELIANCE must
            be explicitly enabled for your client.
          example: STANDARD
        industry_codes:
          type: array
          description: >-
            NAICS 2022 6-digit industry codes. Min 1 item. See the full list at
            [Business-industry-codes](https://developer.fin.com/business-industry-codes).
          minItems: 1
          items:
            type: string
          example:
            - '523130'
        basic_info:
          $ref: '#/components/schemas/V2BasicInfo'
        financial_profile:
          $ref: '#/components/schemas/V2FinancialProfile'
        addresses:
          $ref: '#/components/schemas/V2Addresses'
        associated_parties:
          type: array
          description: >-
            UBOs (≥25% ownership), directors, and authorized signatories. Min 1
            item required.
          minItems: 1
          items:
            $ref: '#/components/schemas/V2AssociatedParty'
        holding_structure:
          $ref: '#/components/schemas/V2HoldingStructure'
        public_listings:
          type: array
          description: Stock exchange listings. Required for publicly traded companies.
          items:
            $ref: '#/components/schemas/V2PublicListing'
        compliance:
          $ref: '#/components/schemas/V2Compliance'
        meta_data:
          type: object
          description: Client-defined key-value metadata for internal tracking.
          properties:
            reference:
              type: string
              description: Client-defined external reference identifier.
              example: REF-20250123-ACME
          additionalProperties: true
    V2BasicInfo:
      type: object
      required:
        - legal_name
        - legal_name_en
        - trade_name
        - description
        - entity_type
        - email
        - phone
        - incorporation_date
        - country_of_incorporation
        - registration_number
        - tax_info
        - websites
      properties:
        legal_name:
          type: string
          maxLength: 255
          description: >-
            Official registered business name. Must match incorporation
            documents.
          example: Fin.com
        legal_name_en:
          type: string
          description: >-
            English translation of the legal name. Required if legal_name
            contains non-ASCII characters.
          example: Fin.com
        trade_name:
          type: string
          description: Common operating name or DBA (Doing Business As).
          example: Toronggo
        trade_name_en:
          type: string
          description: English translation of the trade name.
          example: Toronggo
        description:
          type: string
          maxLength: 500
          description: Description of the company's business activities and purpose.
          example: >-
            Bangladesh-based technology company providing cross-border B2B
            payment and financial technology services
        entity_type:
          type: string
          enum:
            - LIMITED_LIABILITY_COMPANY
            - PUBLICLY_LISTED_COMPANY
            - SOLE_PROPRIETOR
            - PARTNERSHIP
            - CORPORATION
            - TRUST
            - PRIVATE_FOUNDATION
            - CHARITY
            - NONPROFIT_ORGANIZATION
            - PUBLIC_AGENCY_OR_AUTHORITY
          description: Legal entity type of the business.
          example: LIMITED_LIABILITY_COMPANY
        email:
          type: string
          format: email
          description: Business email address. Must be all lowercase.
          example: m@tech.com
        phone:
          type: string
          description: Business phone number in E.164 format.
          example: '+8801529876543'
        incorporation_date:
          type: string
          format: date
          description: Date of incorporation in YYYY-MM-DD format. Cannot be a future date.
          example: '2018-06-15'
        country_of_incorporation:
          $ref: '#/components/schemas/CountryCode'
        registration_number:
          type: string
          description: Business registration or company number. Required.
          example: 12-3456789
        legal_entity_identifier:
          type: string
          minLength: 20
          maxLength: 20
          description: LEI code (20-character alphanumeric). Optional.
          example: 549300EXAMPLE0001X23
        is_dao:
          type: boolean
          description: Whether the entity is a Decentralized Autonomous Organization.
          example: false
        tax_info:
          type: array
          description: Tax and identifying documents for the business. Min 1 item.
          minItems: 1
          items:
            $ref: '#/components/schemas/V2IdentifyingDocument'
        websites:
          type: array
          description: Business website URLs. Min 1 item.
          minItems: 1
          items:
            type: string
            format: uri
          example:
            - https://fin.com
    V2FinancialProfile:
      type: object
      required:
        - purpose_id
        - source_of_fund_ids
        - source_of_wealth_ids
        - estimated_annual_revenue_usd
        - expected_monthly_deposits_usd
        - expected_monthly_withdrawals_usd
        - third_party_fund_usage
      properties:
        purpose_id:
          type: integer
          description: >-
            Account purpose. Foreign key to purposes reference table. Fetch
            valid values from [List Account
            Purposes](https://developer.fin.com/api-reference/catalogue/list-account-purposes)
            endpoint.
          example: 3
        purpose_remarks:
          type: string
          description: >-
            Additional context for the account purpose. Required if purpose
            represents "Other".
          example: Cross-border B2B payments for international suppliers
        source_of_fund_ids:
          type: array
          description: >-
            Source(s) of business funds. FK array to source_of_funds reference
            table. Min 1 item. Fetch valid values from [List Source of
            Funds](https://developer.fin.com/api-reference/catalogue/list-source-of-funds).
            Order items from the largest to smallest contributor — the ID
            representing the primary source of funds must come first, followed
            by secondary sources in descending order.
          minItems: 1
          items:
            type: integer
          example:
            - 1
            - 4
        source_of_funds_description:
          type: string
          description: Additional context for source of funds.
          example: Revenue from software licensing and SaaS subscriptions
        source_of_wealth_ids:
          type: array
          description: >-
            Source(s) of owner's wealth. FK array to source_of_wealth reference
            table. Min 1 item. Fetch valid values from [List Source of
            Wealth](https://developer.fin.com/api-reference/catalogue/list-source-of-wealth).
            Order items from the largest to smallest contributor — the primary
            source must come first.
          minItems: 1
          items:
            type: integer
          example:
            - 2
        estimated_annual_revenue_usd:
          type: integer
          minimum: 0
          description: Estimated annual revenue in USD (not cents). Must be >= 0.
          example: 5000000
        expected_monthly_deposits_usd:
          type: integer
          minimum: 0
          description: Expected monthly deposit volume in USD (not cents). Must be >= 0.
          example: 400000
        expected_monthly_withdrawals_usd:
          type: integer
          minimum: 0
          description: Expected monthly withdrawal volume in USD (not cents). Must be >= 0.
          example: 350000
        expected_transaction_value_usd:
          type: integer
          minimum: 0
          description: Typical single transaction value in USD (not cents). Optional.
          example: 50000
        expected_monthly_transaction_count:
          type: integer
          minimum: 0
          description: Expected number of transactions per month. Optional.
          example: 20
        third_party_fund_usage:
          type: boolean
          description: >-
            Whether this business will process, hold, or move funds on behalf of
            other parties. Set to true only for MSBs and payment processors.
            Triggers enhanced compliance review.
          example: false
    V2Addresses:
      type: object
      required:
        - is_incorporated_address_same
        - incorporated_address
      properties:
        is_incorporated_address_same:
          type: boolean
          description: >-
            Whether the physical operating address is the same as the
            incorporated address. If false, physical_address is required.
          example: false
        incorporated_address:
          $ref: '#/components/schemas/V2Address'
        physical_address:
          allOf:
            - $ref: '#/components/schemas/V2Address'
          description: >-
            Physical operating address. Required when
            is_incorporated_address_same is false.
    V2AssociatedParty:
      type: object
      required:
        - basic_info
        - address
        - roles
      properties:
        ref:
          type: string
          description: >-
            Client-defined reference identifier for this party. Used for
            internal tracking only.
          example: owner-001
        basic_info:
          $ref: '#/components/schemas/V2APBasicInfo'
        address:
          $ref: '#/components/schemas/V2Address'
        roles:
          type: array
          description: >-
            Roles held by this party. At least one role is required. A party may
            hold both roles simultaneously — at least one party must hold both
            shareholder and ubo.
          minItems: 1
          items:
            type: string
            enum:
              - shareholder
              - ubo
          example:
            - shareholder
            - ubo
        ownership_info:
          $ref: '#/components/schemas/V2OwnershipInfo'
    V2HoldingStructure:
      type: object
      properties:
        has_material_intermediary_ownership:
          type: boolean
          description: Whether any intermediary holds a material ownership stake.
          example: true
        corporate_shareholders:
          type: array
          description: List of corporate (non-individual) shareholders.
          items:
            $ref: '#/components/schemas/V2CorporateShareholder'
        foreign_branches:
          type: array
          description: List of foreign branch registrations.
          items:
            $ref: '#/components/schemas/V2ForeignBranch'
    V2PublicListing:
      type: object
      properties:
        mic:
          type: string
          description: ISO 10383 Market Identifier Code (e.g., XNAS for NASDAQ).
          example: XNAS
        isin:
          type: string
          minLength: 12
          maxLength: 12
          description: International Securities Identification Number (12 chars).
          example: US0231351067
        ticker_symbol:
          type: string
          description: Stock exchange ticker symbol.
          example: ACME
    V2Compliance:
      type: object
      properties:
        operates_in_prohibited_countries:
          type: boolean
          description: Whether the business operates in OFAC/sanctioned countries.
          example: false
        additional_description_for_compliance_screening:
          type: string
          description: Free-text compliance notes for manual review.
          example: We do not operate in any OFAC-sanctioned jurisdictions.
        risk_profile:
          $ref: '#/components/schemas/V2RiskProfile'
        regulated_activity:
          $ref: '#/components/schemas/V2RegulatedActivity'
        aml:
          $ref: '#/components/schemas/V2AML'
    CountryCode:
      type: string
      description: ISO 3166-1 alpha-3 country code
      example: USA
      enum:
        - AFG
        - ALB
        - DZA
        - ASM
        - AND
        - AGO
        - AIA
        - ATA
        - ATG
        - ARG
        - ARM
        - ABW
        - AUS
        - AUT
        - AZE
        - BHS
        - BHR
        - BGD
        - BRB
        - BLR
        - BEL
        - BLZ
        - BEN
        - BMU
        - BTN
        - BOL
        - BES
        - BIH
        - BWA
        - BVT
        - BRA
        - IOT
        - BRN
        - BGR
        - BFA
        - BDI
        - CPV
        - KHM
        - CMR
        - CAN
        - CYM
        - CAF
        - TCD
        - CHL
        - CHN
        - CXR
        - CCK
        - COL
        - COM
        - COD
        - COG
        - COK
        - CRI
        - HRV
        - CUB
        - CUW
        - CYP
        - CZE
        - CIV
        - DNK
        - DJI
        - DMA
        - DOM
        - ECU
        - EGY
        - SLV
        - GNQ
        - ERI
        - EST
        - SWZ
        - ETH
        - FLK
        - FRO
        - FJI
        - FIN
        - FRA
        - GUF
        - PYF
        - ATF
        - GAB
        - GMB
        - GEO
        - DEU
        - GHA
        - GIB
        - GRC
        - GRL
        - GRD
        - GLP
        - GUM
        - GTM
        - GGY
        - GIN
        - GNB
        - GUY
        - HTI
        - HMD
        - VAT
        - HND
        - HKG
        - HUN
        - ISL
        - IND
        - IDN
        - IRN
        - IRQ
        - IRL
        - IMN
        - ISR
        - ITA
        - JAM
        - JPN
        - JEY
        - JOR
        - KAZ
        - KEN
        - KIR
        - PRK
        - KOR
        - KWT
        - KGZ
        - LAO
        - LVA
        - LBN
        - LSO
        - LBR
        - LBY
        - LIE
        - LTU
        - LUX
        - MAC
        - MDG
        - MWI
        - MYS
        - MDV
        - MLI
        - MLT
        - MHL
        - MTQ
        - MRT
        - MUS
        - MYT
        - MEX
        - FSM
        - MDA
        - MCO
        - MNG
        - MNE
        - MSR
        - MAR
        - MOZ
        - MMR
        - NAM
        - NRU
        - NPL
        - NLD
        - NCL
        - NZL
        - NIC
        - NER
        - NGA
        - NIU
        - NFK
        - MNP
        - NOR
        - OMN
        - PAK
        - PLW
        - PSE
        - PAN
        - PNG
        - PRY
        - PER
        - PHL
        - PCN
        - POL
        - PRT
        - PRI
        - QAT
        - MKD
        - ROU
        - RUS
        - RWA
        - REU
        - BLM
        - SHN
        - KNA
        - LCA
        - MAF
        - SPM
        - VCT
        - WSM
        - SMR
        - STP
        - SAU
        - SEN
        - SRB
        - SYC
        - SLE
        - SGP
        - SXM
        - SVK
        - SVN
        - SLB
        - SOM
        - ZAF
        - SGS
        - SSD
        - ESP
        - LKA
        - SDN
        - SUR
        - SJM
        - SWE
        - CHE
        - SYR
        - TWN
        - TJK
        - TZA
        - THA
        - TLS
        - TGO
        - TKL
        - TON
        - TTO
        - TUN
        - TUR
        - TKM
        - TCA
        - TUV
        - UGA
        - UKR
        - ARE
        - GBR
        - UMI
        - USA
        - URY
        - UZB
        - VUT
        - VEN
        - VNM
        - VGB
        - VIR
        - WLF
        - ESH
        - YEM
        - ZMB
        - ZWE
        - ALA
    V2IdentifyingDocument:
      type: object
      required:
        - country_code
        - document_type
        - document_id
      properties:
        country_code:
          $ref: '#/components/schemas/CountryCode'
        document_type:
          type: string
          description: >-
            Business tax ID document type, validated per country. Examples: EIN,
            TIN, VAT_ID, TAX_ID, etc. See all available types at [Business tax
            id documents by
            region](https://developer.fin.com/business-tax-id-documents-by-region).
          example: EIN
        document_id:
          type: string
          description: >-
            The document ID or number. Format validated per country and document
            type.
          example: 12-3456789
    V2Address:
      type: object
      required:
        - street_line_1
        - street_line_1_en
        - city
        - state
        - subdivision_code
        - postal_code
        - country
      properties:
        street_line_1:
          type: string
          description: Primary street address. P.O. Box addresses are not accepted.
          example: 123 Main Street
        street_line_1_en:
          type: string
          description: >-
            English translation of street_line_1. Required if address contains
            non-ASCII characters.
          example: 123 Main Street
        street_line_2:
          type: string
          description: Secondary address (suite, floor, unit, etc.). Optional.
          example: Suite 400
        street_line_2_en:
          type: string
          description: English translation of street_line_2. Optional.
          example: Suite 400
        city:
          type: string
          maxLength: 100
          description: City or municipality name.
          example: San Francisco
        state:
          type: string
          description: >-
            State or province. Required. Must be an ISO 3166-2 subdivision code
            (e.g. US-CA, BD-13).
          example: US-CA
        subdivision_code:
          type: string
          description: >-
            State/province code from [List
            Subdivisions](https://developer.fin.com/api-reference/catalogue/list-subdivisions).
            Same value as state field.
          example: US-CA
        postal_code:
          type: string
          description: ZIP or postal code. Format validated per country.
          example: '94105'
        country:
          $ref: '#/components/schemas/CountryCode'
    V2APBasicInfo:
      type: object
      required:
        - first_name
        - first_name_en
        - last_name
        - last_name_en
        - dob
        - email
        - phone
        - country_of_residence
        - primary_nationality
        - tax_info
      properties:
        first_name:
          type: string
          maxLength: 50
          description: First name.
          example: John
        first_name_en:
          type: string
          description: >-
            English transliteration of first name. Required if name contains
            non-ASCII characters.
          example: John
        middle_name:
          type: string
          description: Middle name(s). Optional.
          example: Michael
        middle_name_en:
          type: string
          description: English transliteration of middle name. Optional.
          example: Michael
        last_name:
          type: string
          maxLength: 50
          description: Last or family name.
          example: Doe
        last_name_en:
          type: string
          description: >-
            English transliteration of last name. Required if name contains
            non-ASCII characters.
          example: Doe
        dob:
          type: string
          format: date
          description: >-
            Date of birth in YYYY-MM-DD format. Party must be at least 18 years
            old.
          example: '1985-03-20'
        email:
          type: string
          format: email
          description: >-
            Personal email address. Must be unique across all associated parties
            in the same request.
          example: john.doe@acmecorp.com
        phone:
          type: string
          description: Personal phone number in E.164 format.
          example: '+14155551234'
        country_of_residence:
          $ref: '#/components/schemas/CountryCode'
        primary_nationality:
          $ref: '#/components/schemas/CountryCode'
        secondary_nationality:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          description: Secondary nationality for dual citizens. Optional.
        tax_info:
          type: array
          description: >-
            Tax and identifying documents for this individual.  See all
            available individual tax ID document types at [Individual Tax ID
            documents](https://developer.fin.com/guides/compliance-and-regulatory/individual-tax-id-documents).
          items:
            $ref: '#/components/schemas/V2IndividualIdentifyingDocument'
    V2OwnershipInfo:
      type: object
      description: Required when roles includes ubo.
      required:
        - designation
        - percentage_of_ownership
        - relationship_establishment_date
        - has_control
        - is_signer
        - is_director
      properties:
        designation:
          type: string
          maxLength: 100
          description: Title or position in the company (e.g., CEO, CFO, Founder).
          example: CEO
        percentage_of_ownership:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: >-
            Ownership stake as a percentage (0–100). Individual parties may have
            0% ownership. Total across all parties must be < 100%.
          example: 75
        relationship_establishment_date:
          type: string
          format: date
          description: >-
            Date when the relationship with the business began. Format:
            YYYY-MM-DD. Cannot be a future date.
          example: '2018-06-15'
        has_control:
          type: boolean
          description: Whether this party has significant control over the entity.
          example: true
        is_signer:
          type: boolean
          description: Whether this party is an authorized signatory.
          example: true
        is_director:
          type: boolean
          description: Whether this party serves as a director.
          example: true
    V2CorporateShareholder:
      type: object
      required:
        - entity_name
        - entity_name_en
        - registration_country_code
        - ownership_percentage
      properties:
        entity_name:
          type: string
          description: Corporate shareholder's legal name.
          example: Acme Ventures LLC
        entity_name_en:
          type: string
          description: >-
            English translation of entity name. Required if entity_name contains
            non-ASCII characters.
          example: Acme Ventures LLC
        registration_country_code:
          $ref: '#/components/schemas/CountryCode'
        ownership_percentage:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Ownership stake as a percentage (0–100).
          example: 60
        registration_number:
          type: string
          description: Entity registration number. Optional.
          example: 98-7654321
        entity_type:
          type: string
          enum:
            - LIMITED_LIABILITY_COMPANY
            - PUBLICLY_LISTED_COMPANY
            - SOLE_PROPRIETOR
            - PARTNERSHIP
            - CORPORATION
            - TRUST
            - PRIVATE_FOUNDATION
            - CHARITY
            - NONPROFIT_ORGANIZATION
            - PUBLIC_AGENCY_OR_AUTHORITY
          description: Legal entity type of the corporate shareholder. Optional.
          example: LIMITED_LIABILITY_COMPANY
        incorporation_date:
          type: string
          format: date
          description: Incorporation date in YYYY-MM-DD format. Optional.
          example: '2015-03-01'
    V2ForeignBranch:
      type: object
      required:
        - registration_country_code
      properties:
        registration_country_code:
          $ref: '#/components/schemas/CountryCode'
        name:
          type: string
          description: Branch name. Optional.
          example: Acme Corp UK Branch
        registration_number:
          type: string
          description: Branch registration number. Optional.
          example: BR000123
    V2RiskProfile:
      type: object
      properties:
        high_risk_activities:
          type: array
          description: >-
            High-risk activities the business engages in. If non-empty,
            high_risk_activities_explanation is required.
          items:
            type: string
            enum:
              - adult_entertainment
              - crypto_exchange
              - gambling
              - cannabis
              - weapons
              - money_services
              - cross_border_payments
          example:
            - cross_border_payments
        high_risk_activities_explanation:
          type: string
          description: >-
            Explanation of declared high-risk activities. Required when
            high_risk_activities is non-empty.
          example: >-
            We facilitate cross-border B2B payments, subject to enhanced due
            diligence procedures.
        conducts_money_services:
          type: boolean
          description: Whether the business provides money services.
          example: true
        conducts_money_services_via_fin:
          type: boolean
          description: Whether money services are provided via financial intermediaries.
          example: false
        conducts_money_services_description:
          type: string
          description: Details about the money services offered.
          example: >-
            Licensed money transmitter providing international wire transfer
            services.
    V2RegulatedActivity:
      type: object
      required:
        - description
        - primary_authority_country_code
        - primary_authority_name
        - license_number
      properties:
        description:
          type: string
          description: Description of the regulated activity.
          example: >-
            Licensed money transmitter operating under FinCEN registration and
            state-level MSB licenses
        primary_authority_country_code:
          $ref: '#/components/schemas/CountryCode'
        primary_authority_name:
          type: string
          description: Name of the primary regulatory authority.
          example: FinCEN
        license_number:
          type: string
          description: Regulatory license or registration number.
          example: MSB-12345678
    V2AML:
      type: object
      properties:
        supervisory_authority_name:
          type: string
          description: Name of the AML supervisory authority.
          example: FinCEN
        license_number:
          type: string
          description: AML license number.
          example: MSB-12345678
        has_appointed_mlro:
          type: boolean
          description: Whether a Money Laundering Reporting Officer has been appointed.
          example: true
        customer_risk_split:
          $ref: '#/components/schemas/V2CustomerRiskSplit'
        prohibits_anonymous_or_fictitious_accounts:
          type: boolean
          description: Policy on anonymous or fictitious accounts.
          example: true
        prohibits_accounts_for_unlicensed_or_shell_customers:
          type: boolean
          description: Policy on unlicensed or shell customers.
          example: true
        customer_identity_verification:
          $ref: '#/components/schemas/V2VerificationMethod'
        pep_and_sanctions_screening:
          $ref: '#/components/schemas/V2VerificationMethod'
        sanction_lists:
          type: array
          description: Names of sanction lists screened against.
          items:
            type: string
          example:
            - OFAC
            - EU
            - UN
            - HMT
        customer_risk_classification_from_due_diligence:
          type: boolean
          example: true
        enhanced_due_diligence_process:
          type: boolean
          example: true
        transaction_monitoring:
          $ref: '#/components/schemas/V2VerificationMethod'
        procedures_for_transaction_monitoring:
          type: boolean
          example: true
        subject_to_ml_or_tf_investigation:
          type: string
          description: Current ML/TF investigation status.
          example: none
        subject_to_regulatory_enforcement_past_2_years:
          type: string
          description: Regulatory enforcement history over the last 2 years.
          example: none
        confirms_no_service_to_sanctioned_countries:
          type: boolean
          example: true
        client_funds_accessibility:
          type: string
          description: Policy on client fund accessibility.
          example: closed_loop
        aml_ctf_audit_completed:
          type: boolean
          example: true
        planned_audit_date:
          type: string
          format: date
          description: Planned next audit date in YYYY-MM-DD format.
          example: '2026-12-01'
    V2IndividualIdentifyingDocument:
      type: object
      required:
        - country_code
        - document_type
        - document_id
      properties:
        country_code:
          $ref: '#/components/schemas/CountryCode'
        document_type:
          type: string
          description: >-
            Individual tax ID document type, validated per country. See all
            available types at [Individual Tax ID
            documents](https://developer.fin.com/guides/compliance-and-regulatory/individual-tax-id-documents).
          example: TIN
        document_id:
          type: string
          description: >-
            The document ID or number. Format validated per country and document
            type.
          example: '1234567890123'
    V2CustomerRiskSplit:
      type: object
      description: Breakdown of customer risk classifications. Percentages must sum to 100.
      required:
        - low_risk
        - medium_risk
        - high_risk
      properties:
        low_risk:
          type: integer
          minimum: 0
          maximum: 100
          description: Percentage of low-risk customers.
          example: 70
        medium_risk:
          type: integer
          minimum: 0
          maximum: 100
          description: Percentage of medium-risk customers.
          example: 25
        high_risk:
          type: integer
          minimum: 0
          maximum: 100
          description: Percentage of high-risk customers.
          example: 5
    V2VerificationMethod:
      type: object
      description: >-
        Used for customer_identity_verification, pep_and_sanctions_screening,
        and transaction_monitoring.
      required:
        - method
        - system
      properties:
        method:
          type: string
          description: Verification method (e.g., automated, manual, third_party).
          example: automated
        system:
          type: string
          description: System or vendor used (e.g., Jumio, Onfido, Internal).
          example: Jumio
  responses:
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication. Obtain token from [Issue a
        Token](https://developer.fin.com/api-reference/authentication/issue-a-token)
        endpoint

````