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

# April 13, 2026

> Changelog for April 13, 2026

## ✨ New Features

### Customers

1. **New Endpoint: `GET /v2/customers`**
   List customers with the same filtering and pagination as V1. The V1 endpoint remains available.

2. **New Endpoint: `GET /v2/customers/{customer_id}`**
   Retrieve customer details with new fields not available in V1. The response now includes `rejection_reason` (populated when `customer_status` is `REJECTED` or `ACTION_REQUIRED`) and `request_for_information` (populated when `customer_status` is `ACTION_REQUIRED`). These fields give developers structured visibility into why a customer was rejected or what action is needed, without requiring a separate API call or webhook.

3. **New Endpoint: `POST /v2/customers/business`**
   Create a business customer with a significantly expanded KYB profile. Key additions over V1 include:

   * `industry_codes` — accepts NAICS 2022 6-digit codes instead of the V1 `business_industry_id` integer
   * `tax_info[]` array — replaces the single `tax_id` string, supporting multiple tax documents per country
   * `holding_structure` — captures corporate shareholders and foreign branch registrations
   * `public_listings` — stock exchange details for publicly traded companies
   * `compliance` — full AML/KYC program details including risk profile, regulated activity, and sanctions screening
   * `source_of_fund_ids` and `source_of_wealth_ids` — accept arrays instead of a single integer, ordered by contribution size
   * `_en` transliteration fields — for non-ASCII business names and addresses
   * Granular volume fields: `expected_monthly_deposits_usd`, `expected_monthly_withdrawals_usd`, `expected_transaction_value_usd`, and `expected_monthly_transaction_count` replace the single `monthly_volume` field

   The V1 `POST /v1/customers/business` endpoint remains available. Returns `201` on success (V1 returns `200`).

4. **New Endpoint: `POST /v2/customers/{customer_id}/business/attach`**
   Attach documents to a V2 business customer. Documents are organized into three categories: `formation_documents`, `ownership_documents`, and `supporting_documents`. This replaces the V1 structure of `ownership_structure`, `company_details`, and `legal_presence`. The `customer_id` is now a path parameter instead of a request body field.

5. **New Endpoint: `POST /v2/customers/{customer_id}/associated-parties/individual/attach`**
   Attach identity and address documents for associated parties of a V2 business customer. Replaces `proof_of_identity` and `proof_of_address` with `identifying_documents` and `address_documents` arrays, allowing multiple identity documents per party. Also adds an optional `supporting_documents` array.

6. **New Endpoint: `PATCH /v1/customers/{customer_id}`**
   Unified endpoint for responding to RFI requests across all customer types and API versions. Submit only the fields and documents specified in the `customer.rfi` webhook. Sending unrequested fields will trigger an error. The request body accepts the same field structures used by the customer creation and document attachment endpoints (both V1 and V2). This single endpoint replaces the need for separate PATCH calls per document category.

### Beneficiaries

7. **New Endpoint: `POST /v3/beneficiaries`**
   Create a beneficiary with a required `counter_party` field (`FIRST_PARTY` or `THIRD_PARTY`). The `occupation_remarks` field is no longer required in `receiver_meta_data`. The response returns `beneficiary_id` directly instead of `id` and `status`. The beneficiary is ready for transactions only when its `status` reaches `ACTIVE` (delivered via the `beneficiary.status` webhook).

### Virtual Accounts

8. **New Endpoint: `POST /v2/customers/virtual-account`**
   Create a virtual account with a restructured request body. Key changes from V1:
   * `customer_id` is no longer in the request body (inferred from auth context)
   * Uses `destination.wallet`, `destination.currency`, `destination.rail` instead of flat fields
   * Uses `source.currency` and `source.rail` instead of `source_currency` and `source_rail`
   * Accepts both `developer_fee.percentage` and `developer_fee.fixed` instead of only `developer_fee_percentage`
   * The account starts in `PROCESSING` status. `deposit_instructions` will be null until the account becomes `ACTIVE`.

9. **New Endpoint: `GET /v2/customers/virtual-account`**
   List virtual accounts with the same filtering as V1. The response adds `developer_fee_fixed`, `rfi`, `bank_country`, `account_type`, and `bank_code` fields. The `status` enum is expanded to include `PROCESSING`, `IN_COMPLIANCE`, `REQUEST_FOR_INFORMATION`, `ACTIVE`, `INACTIVE`, and `DECLINED`.

### Catalogue

10. **New Endpoint: `GET /v1/source-of-wealth`**
    Retrieve a list of source of wealth options. Accepts `type` (`INDIVIDUAL` or `BUSINESS`) as a required query parameter. Used by `POST /v2/customers/business` via the `source_of_wealth_ids` field.

### Webhooks

11. **New Webhook: `customer.rfi`**
    Fires when the compliance team requests additional documents or data from a customer. Sets the customer status to `ACTION_REQUIRED`. The payload includes a structured `request_for_information` array describing exactly which sections, document types, and fields are `MISSING`, `EXPIRED`, or `INVALID`. Scoped to either the customer or a specific associated party. Can also fire after a customer is already `APPROVED`.

    | Customer Type       | Section Values                                                       |
    | ------------------- | -------------------------------------------------------------------- |
    | Individual          | `proof_of_identity`, `proof_of_address`, `tos_policies_value`        |
    | Business V1         | `company_details`, `ownership_structure`, `legal_presence`           |
    | Business V2         | `formation_documents`, `ownership_documents`, `supporting_documents` |
    | Associated Party V1 | `proof_of_identity`, `proof_of_address`                              |
    | Associated Party V2 | `identifying_documents`, `tax_info`, `address_documents`             |

12. **New Webhook: `virtual_account.created.v2`**
    Fires when a V2 virtual account is created. The account starts in `PROCESSING` status with `deposit_instructions` set to null. Includes a `developer_fee_fixed` field and an `rfi` object (null initially).

13. **New Webhook: `virtual_account.status.v2`**
    Fires when a V2 virtual account status changes. Possible values: `PROCESSING`, `IN_COMPLIANCE`, `REQUEST_FOR_INFORMATION`, `ACTIVE`, `INACTIVE`, `DECLINED`. The payload includes `deposit_instructions` (populated once active), `developer_fee_fixed`, `developer_fee_percent`, and `rfi`.

## 🛠️ Improvements

### Customers

1. **V2 Customer Status Names**
   Three customer status values have been renamed in V2 endpoints and webhooks. V1 status names remain unchanged for V1 created customers.

   | Status                | V1 Name      | V2 Name           |
   | --------------------- | ------------ | ----------------- |
   | Awaiting processing   | `QUEUED`     | `PROCESSING`      |
   | Paused for compliance | `ON_HOLD`    | `IN_COMPLIANCE`   |
   | Action needed         | `REINITIATE` | `ACTION_REQUIRED` |

   The status values you receive are determined by which version of the Get Customer Details endpoint you call, not which version was used to create the customer. A business customer created via `POST /v1/customers/business` will return V2 status names when retrieved via `GET /v2/customers/{customer_id}`, and vice versa.

2. **V1 entity\_type enum: `PRIVATE_LIMITED` removed**
   The `PRIVATE_LIMITED` value has been removed from the `entity_type` enum in `POST /v2/customers/business`. It remains available in V1.

3. **Identity document types expanded**
   The `ProofOfIdentity` schema now includes `RESIDENCE_PERMIT` and `PERMANENT_RESIDENCY_ID` as accepted types. `PERMANENT_RESIDENCY_ID` is only supported for USA residents and will be rejected for non-USA residents.

4. **`GET /v1/industries` scoped to V1 only**
   The List Industries catalogue endpoint now applies only to `POST /v1/customers/business`. The V2 business customer endpoint uses `industry_codes` (NAICS 6-digit codes) instead.

### Beneficiaries

5. **`counter_party` field added to `POST /v2/beneficiaries`**
   An optional `counter_party` field (`FIRST_PARTY` or `THIRD_PARTY`) has been added to the existing V2 Create Beneficiary endpoint.

6. **`status` and `counter_party` fields added to `GET /v2/beneficiaries/details`**
   The Fetch Beneficiary Details V2 response now includes a `status` field with values `PROCESSING`, `ACTIVE`, `INACTIVE`, or `REJECTED`, and a `counter_party` field with values `FIRST_PARTY` or `THIRD_PARTY`.

7. **`beneficiary.status` webhook now includes `status` field**
   The `beneficiary.status` webhook payload now includes a `status` field (`PROCESSING`, `ACTIVE`, `INACTIVE`, `REJECTED`) alongside the existing `active` boolean. The webhook now fires for all four status transitions.