> ## 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 20, 2026

> API Migration Guide — deprecation deadline May 20, 2026

<Warning>
  **Deprecation Notice:** The endpoints listed below will be deprecated on **May
  20, 2026**. Please migrate to the new versions before this date to avoid
  service disruption.
</Warning>

## API Migration Guide

This guide outlines the endpoints scheduled for deprecation, their replacements, and the key behavioral changes you need to be aware of when migrating. Each section includes direct links to the relevant API reference for both the deprecated and new endpoints.

***

## Endpoint Migration Reference

### Customers

| Resource                            | Deprecated Endpoint                                                                                                                   | New Endpoint                                                                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Create business customer            | `POST /v1/customers/business` — [reference](/api-reference/customers/create-business-customer)                                        | `POST /v2/customers/business` — [reference](/api-reference/customers/create-business-customer-v2)                                                      |
| Attach business documents           | `POST /v1/customers/business/attach` — [reference](/api-reference/customers/attach-documents-to-business-customer)                    | `POST /v2/customers/{customer_id}/business/attach` — [reference](/api-reference/customers/attach-documents-to-business-customer-v2)                    |
| Attach document to associated party | `POST /v1/customers/associated-parties/individual/attach` — [reference](/api-reference/customers/attach-document-to-associated-party) | `POST /v2/customers/{customer_id}/associated-parties/individual/attach` — [reference](/api-reference/customers/attach-document-to-associated-party-v2) |
| List customers                      | `GET /v1/customers` — [reference](/api-reference/customers/list-customers)                                                            | `GET /v2/customers` — [reference](/api-reference/customers/list-customers-v2)                                                                          |
| Get business customer details       | `GET /v1/customers/{customer_id}` — [reference](/api-reference/customers/get-customer-details)                                        | `GET /v2/customers/{customer_id}` — [reference](/api-reference/customers/get-customer-details-v2)                                                      |

### Beneficiaries

| Resource                | Deprecated Endpoint                                                                                   | New Endpoint                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Create beneficiary      | `POST /v2/beneficiaries` — [reference](/api-reference/beneficiaries/create-beneficiary)               | `POST /v3/beneficiaries` — [reference](/api-reference/beneficiaries/create-beneficiary-v3)               |
| Get beneficiary details | `GET /v1/beneficiaries/details` — [reference](/api-reference/beneficiaries/fetch-beneficiary-details) | `GET /v2/beneficiaries/details` — [reference](/api-reference/beneficiaries/fetch-beneficiary-details-v2) |

The new beneficiary details endpoint adds visibility into the `status` and `counter_party` fields.

### Virtual Accounts

| Resource               | Deprecated Endpoint                                                                                        | New Endpoint                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Create virtual account | `POST /v1/customers/virtual-account` — [reference](/api-reference/virtual-accounts/create-virtual-account) | `POST /v2/customers/virtual-account` — [reference](/api-reference/virtual-accounts/create-virtual-account-v2) |
| List virtual accounts  | `GET /v1/customers/virtual-account` — [reference](/api-reference/virtual-accounts/list-virtual-accounts)   | `GET /v2/customers/virtual-account` — [reference](/api-reference/virtual-accounts/list-virtual-accounts-v2)   |

***

## What's Changed

### 1. New Status Values for Business Customers (v2)

The v2 business customer API introduces clearer, more descriptive status values. If you have logic that branches on customer status, you'll need to update it.

| Legacy Status (v1) | New Status (v2)   |
| ------------------ | ----------------- |
| `QUEUED`           | `PROCESSING`      |
| `ON_HOLD`          | `IN_COMPLIANCE`   |
| `REINITIATE`       | `ACTION_REQUIRED` |

**Versioning rules:**

* **Business customers** — Use v2 for both creation and retrieval.
* **Individual customers** — Continue using v1 for both creation and retrieval.

### 2. Request for Information (RFI) Management

A new `request_for_information` object has been introduced on the business customer resource to streamline RFI handling.

To respond to or update an RFI, use:

```
PATCH /v1/customers/{customer_id}
```

This is the canonical way to manage RFIs going forward — no separate workflow is required.

### 3. Capabilities Moved to a Dedicated Endpoint

The `capabilities` object has been **removed** from the v2 customer details response. To fetch a customer's capabilities, use the new dedicated endpoint:

```
GET /v2/customers/{customer_id}/capabilities
```

This keeps customer detail responses lighter and lets you fetch capability data only when you actually need it.

### 4. New Beneficiary Status Values

Beneficiaries now expose a more granular status lifecycle so you can clearly determine transaction eligibility:

| Status       | Description                                             | Eligible for Transactions? |
| ------------ | ------------------------------------------------------- | -------------------------- |
| `PROCESSING` | The beneficiary is being prepared and is not yet ready. | No                         |
| `ACTIVE`     | The beneficiary is fully set up and ready to use.       | Yes                        |
| `INACTIVE`   | The beneficiary is currently disabled.                  | No                         |
| `REJECTED`   | Beneficiary failed validation.                          | No                         |

Make sure your transaction-initiation logic checks for `ACTIVE` before attempting to send funds to a beneficiary.

***

## Migration Checklist

Use this list to track your migration work before **May 20, 2026**:

* Update all business customer create and fetch calls to v2.
* Map legacy customer statuses (`QUEUED`, `ON_HOLD`, `REINITIATE`) to their new values in your codebase.
* Implement the `PATCH /v1/customers/{customer_id}` flow for RFI handling.
* Update document attachment calls to use the new `{customer_id}`-scoped paths.
* Update customer list and detail integrations to v2.
* Move any capabilities-dependent logic to `GET /v2/customers/{customer_id}/capabilities`.
* Update beneficiary creation calls to v3 and fetch calls to v2.
* Handle the new beneficiary statuses (`PROCESSING`, `ACTIVE`, `INACTIVE`, `REJECTED`) — gate transactions on `ACTIVE`.
* Update virtual account create and list calls to v2.
* Verify individual customer flows remain on v1 (no change required).
* Complete migration before **May 20, 2026**.