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

> 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 for Fin.com, a financial services platform that
    provides a range of banking and payment solutions for businesses and
    individuals. This API allows developers to integrate Fin.com's services into
    their applications, enabling functionalities such as customer management,
    transaction processing, and access to financial data.
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
      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
            - 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 to 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 to 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
            - 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

````