---
title: "Request a New Transfer"
method: POST
path: "/v1/accounts/{account_id}/transfers"
tags: ["Funding", "Accounts"]
---

# Request a New Transfer

`POST /v1/accounts/{account_id}/transfers`

Create a new transfer to deposit money into or withdraw money from an account.

Two `transfer_type` values are accepted, and both are available in sandbox and production:

- **`ach`** — supports both `INCOMING` (deposit) and `OUTGOING` (withdrawal) directions. A `relationship_id` from a previously created [ACH Relationship](https://docs.alpaca.markets/reference/createachrelationshipforaccount) is required.
- **`wire`** — supports the `OUTGOING` (withdrawal) direction only. Incoming wires cannot be initiated through this endpoint; they are pushed in by the sending bank and recorded automatically. A `bank_id` from a previously created [Bank Relationship](https://docs.alpaca.markets/reference/createrecipientbank) is required, and the bank must be in `APPROVED` status before the transfer will progress past `QUEUED`.

In the sandbox environment, ACH deposits and withdrawals settle instantly against virtual funds. Outgoing wire withdrawals are accepted and simulated end-to-end — no funds are transmitted to a bank, but the transfer progresses to `COMPLETE` and the account is debited against virtual funds. Sandbox wire withdrawals are asynchronous (not instant) and auto-complete on weekdays only; transfers submitted on a weekend will not progress until Monday. For more on funding accounts in sandbox, see [this tutorial](https://alpaca.markets/learn/fund-broker-api/).

## Path parameters

- `account_id` string, uuid, required

## Request body

- CreateTransferRequest — [See main docs here](https://alpaca.markets/docs/api-references/broker-api/funding/transfers/#creating-a-transfer-entity)
  - `additional_information` string, nullable — Additional details for when type = `wire`
  - `amount` string, decimal, required — Must be > 0.00
  - `bank_id` string, uuid — Required if type = `wire` The bank_relationship created for the account_id [here](https://alpaca.markets/docs/api-references/broker-api/funding/bank/#creating-a-new-bank-relationship)
  - `direction` 'INCOMING' | 'OUTGOING', required — - **INCOMING** Funds incoming to user's account (deposit). - **OUTGOING** Funds outgoing from user's account (withdrawal).
  - `fee_payment_method` string — Only outgoing wire fees are currently supported for automated processing. **user** The end user will pay any applicable fees **invoice** Any applicable fees will be billed to the client in the following monthly invoice
  - `ira` TransferIRA — This field is used for IRA Account only
    - `distribution_reason` string
    - `tax_withholding` TransferIRATaxWithholding
      - `fed_pct` string
      - `state_pct` string
    - `tax_year` string
  - `relationship_id` string, uuid — Required if type = `ach` The ach_relationship created for the account_id [here](https://alpaca.markets/docs/api-references/broker-api/funding/ach/#creating-an-ach-relationship)
  - `timing` 'immediate' — Deprecated. Not honored by the API; values sent are silently ignored and this field will be removed.
  - `transfer_type` 'ach' | 'wire', required — - **ach** Transfer via ACH (US Only). Supports both `INCOMING` (deposit) and `OUTGOING` (withdrawal) directions. - **wire** Transfer via wire. `OUTGOING` (withdrawal) only.

## Response `200`

Successfully requested a transfer.

- Transfer — Transfers allow you to transfer money/balance into your end customers' account (deposits) or out (withdrawal). [Main docs here](https://alpaca.markets/docs/api-references/broker-api/funding/transfers/#the-transfer-object)
  - `account_id` string, uuid, required — The account ID
  - `additional_information` string, nullable — Additional information. Only applies when type = "wire".
  - `amount` string, decimal, required — Must be > 0.00
  - `bank_id` string, uuid — The ID of the Bank, only present if type = "wire"
  - `created_at` string, date-time, required — Timestamp when transfer was created
  - `direction` 'INCOMING' | 'OUTGOING', required — - **INCOMING** Funds incoming to user's account (deposit). - **OUTGOING** Funds outgoing from user's account (withdrawal).
  - `expires_at` string, date-time — Timestamp when transfer expires
  - `fee` string, decimal, nullable — Fee amount to be collected. Only applies when type = "wire".
  - `fee_payment_method` string, nullable — Either "user" or "invoice". Only applies when type = "wire".
  - `hold_until` string, date-time
  - `id` string, uuid, required — The transfer ID
  - `instant_amount` string
  - `ira` TransferIRADetails
    - `distribution_reason` string
    - `fed_withholding_amount` string
    - `fed_withholding_pct` string
    - `state_withholding_amount` string
    - `state_withholding_pct` string
    - `tax_year` string
  - `reason` string, nullable — Cause of the status
  - `relationship_id` string, uuid — The ACH relationship ID only present if type = "ach"
  - `requested_amount` string, decimal, nullable — Must be > 0.00. Only applies when type = "wire".
  - `status` 'QUEUED' | 'APPROVAL_PENDING' | 'PENDING' | 'SENT_TO_CLEARING' | 'REJECTED' | 'CANCELED' | 'APPROVED' | 'COMPLETE' | 'RETURNED', required — - **QUEUED** Transfer is in queue to be processed. - **APPROVAL_PENDING** Transfer is pending approval. - **PENDING** Transfer is pending processing. - **SENT_TO_CLEARING** Transfer is being processed by the clearing firm. - **REJECTED** Transfer is rejected. - **CANCELED** Client initiated transfer cancellation. - **APPROVED** Transfer is approved. - **COMPLETE** Transfer is completed. - **RETURNED** The bank issued an ACH return for the transfer.
  - `type` 'ach' | 'wire', required — - **ach** Transfer via ACH (US Only). Supports both `INCOMING` (deposit) and `OUTGOING` (withdrawal) directions. - **wire** Transfer via wire. `OUTGOING` (withdrawal) only.
  - `updated_at` string, date-time — Timestamp when transfer was updated

## Other responses

- `400` — The request body is malformed (e.g. invalid JSON).
- `403` — The account is not permitted to perform this transfer. Examples include: - `deposits are not permitted for this account` — the account's `depositable_status` is not `allowed` / `limited`. - `withdrawals are not permitted for this account` — the account's `withdrawable_status` is not `allowed` / `limited`.
- `422` — The request was rejected by validation. Common reasons include: - `cannot submit incoming wire transfer using this API` — sent `transfer_type: wire` with `direction: INCOMING`. Incoming wires cannot be initiated through this endpoint. - `invalid relationship_id` / `bank_id required for wire transfer` — missing the required relationship/bank identifier for the chosen `transfer_type`. - `bank_id should be empty for ach transfer` / `relationship_id should be empty for wire transfer` — provided the wrong identifier for the chosen `transfer_type`. - `only wire transfer type can provide additional information for the transfer` — `additional_information` was supplied on a non-wire request. - `amount must be greater than 0.00` / `deposit amount must be greater than or equal to <min>` / `withdrawal amount must be greater than <min>` — amount fails the minimum-amount checks. - `transfer_type must be either ach or wire` / `direction must be either incoming or outgoing` — invalid enum values.

---

[API](https://skmtc.net/alpacahq/apis/gift-city-extensions-api.md) · [All operations](https://skmtc.net/alpacahq/apis/gift-city-extensions-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/alpacahq/gift-city-extensions-api/revisions/62e3378bb273/schema)