# Account Transfers
> Account transfers move funds between your own accounts at Increase (accounting systems often refer to these as Book Transfers). Account Transfers are free and synchronous. Upon creation they create two Transactions, one negative on the originating account and one positive on the destination account (unless the transfer requires approval, in which case the Transactions will be created when the transfer is approved).

[Events](https://increase.com/documentation/events.md) will be generated for this resource. The possible event categories are: `account_transfer.created` and `account_transfer.updated`.

## The Account Transfer object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "amount": 100,
  "approval": {
    "approved_at": "2020-01-31T23:59:59Z",
    "approved_by": null
  },
  "cancellation": null,
  "created_at": "2020-01-31T23:59:59Z",
  "created_by": {
    "category": "user",
    "user": {
      "email": "user@example.com"
    }
  },
  "currency": "USD",
  "description": "Move money into savings",
  "destination_account_id": "account_uf16sut2ct5bevmq3eh",
  "destination_transaction_id": "transaction_j3itv8dtk5o8pw3p1xj4",
  "id": "account_transfer_7k9qe1ysdgqztnt63l7n",
  "idempotency_key": null,
  "pending_transaction_id": null,
  "status": "complete",
  "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
  "type": "account_transfer"
}
```
### Attributes
- `account_id` (string)
  The Account from which the transfer originated.

- `amount` (integer)
  The transfer amount in cents. This will always be positive and indicates the amount of money leaving the originating account.

- `approval` (dictionary, nullable)
  If your account requires approvals for transfers and the transfer was approved, this will contain details of the approval.

  - `approval.approved_at` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the transfer was approved.

  - `approval.approved_by` (string, nullable)
    If the Transfer was approved by a user in the dashboard, the email address of that user.

- `cancellation` (dictionary, nullable)
  If your account requires approvals for transfers and the transfer was not approved, this will contain details of the cancellation.

  - `cancellation.canceled_at` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Transfer was canceled.

  - `cancellation.canceled_by` (string, nullable)
    If the Transfer was canceled by a user in the dashboard, the email address of that user.

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the transfer was created.

- `created_by` (dictionary, nullable)
  What object created the transfer, either via the API or the dashboard.

  - `created_by.api_key` (dictionary, nullable)
    If present, details about the API key that created the transfer.

      - `created_by.api_key.description` (string, nullable)
        The description set for the API key when it was created.

  - `created_by.category` (enum)
    The type of object that created this transfer.
    Cases:
    * `api_key` (An API key. Details will be under the `api_key` object.)
    * `oauth_application` (An OAuth application you connected to Increase. Details will be under the `oauth_application` object.)
    * `user` (A User in the Increase dashboard. Details will be under the `user` object.)

  - `created_by.oauth_application` (dictionary, nullable)
    If present, details about the OAuth Application that created the transfer.

      - `created_by.oauth_application.name` (string)
        The name of the OAuth Application.

  - `created_by.user` (dictionary, nullable)
    If present, details about the User that created the transfer.

      - `created_by.user.email` (string)
        The email address of the User.

- `currency` (enum)
  The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the transfer's currency.
  Cases:
  * `USD` (US Dollar (USD))

- `description` (string)
  An internal-facing description for the transfer for display in the API and dashboard. This will also show in the description of the created Transactions.

- `destination_account_id` (string)
  The destination Account's identifier.

- `destination_transaction_id` (string, nullable)
  The identifier of the Transaction on the destination Account representing the received funds.

- `id` (string)
  The Account Transfer's identifier.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `pending_transaction_id` (string, nullable)
  The ID for the pending transaction representing the transfer. A pending transaction is created when the transfer [requires approval](https://increase.com/documentation/transfer-approvals#transfer-approvals) by someone else in your organization.

- `status` (enum)
  The lifecycle status of the transfer.
  Cases:
  * `pending_approval` (The transfer is pending approval from your team.)
  * `canceled` (The transfer was pending approval from your team and has been canceled.)
  * `complete` (The transfer has been completed.)

- `transaction_id` (string, nullable)
  The identifier of the Transaction on the originating account representing the transferred funds.

- `type` (string)
  A constant representing the object's type. For this resource it will always be `account_transfer`.

## List Account Transfers
GET /account_transfers

### Example
```curl
curl \
  --url "${INCREASE_URL}/account_transfers?account_id=account_in71c4amph0vgo2qllky" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `account_id` (string, optional)
  Filter Account Transfers to those that originated from the specified Account.

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `created_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

### Returns a Account Transfer List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "amount": 100,
      "approval": {
        "approved_at": "2020-01-31T23:59:59Z",
        "approved_by": null
      },
      "cancellation": null,
      "created_at": "2020-01-31T23:59:59Z",
      "created_by": {
        "category": "user",
        "user": {
          "email": "user@example.com"
        }
      },
      "currency": "USD",
      "description": "Move money into savings",
      "destination_account_id": "account_uf16sut2ct5bevmq3eh",
      "destination_transaction_id": "transaction_j3itv8dtk5o8pw3p1xj4",
      "id": "account_transfer_7k9qe1ysdgqztnt63l7n",
      "idempotency_key": null,
      "pending_transaction_id": null,
      "status": "complete",
      "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
      "type": "account_transfer"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create an Account Transfer
POST /account_transfers

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/account_transfers" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky",
    "amount": 100,
    "description": "Creating liquidity",
    "destination_account_id": "account_uf16sut2ct5bevmq3eh"
  }'
```

### Body Parameters
- `account_id` (string, required)
  The identifier for the originating Account that will send the transfer.

- `amount` (integer, required)
  The transfer amount in the minor unit of the account currency. For dollars, for example, this is cents.

- `description` (string, required)
  An internal-facing description for the transfer for display in the API and dashboard. This will also show in the description of the created Transactions.

- `destination_account_id` (string, required)
  The identifier for the destination Account that will receive the transfer.

- `require_approval` (boolean, optional)
  Whether the transfer should require explicit approval via the dashboard or API. For more information, see [Transfer Approvals](/documentation/transfer-approvals).

## Retrieve an Account Transfer
GET /account_transfers/{account_transfer_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/account_transfers/account_transfer_7k9qe1ysdgqztnt63l7n" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `account_transfer_id` (string, required)
  The identifier of the Account Transfer.

## Approve an Account Transfer
POST /account_transfers/{account_transfer_id}/approve
> Approves an Account Transfer in status `pending_approval`.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/account_transfers/account_transfer_7k9qe1ysdgqztnt63l7n/approve" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `account_transfer_id` (string, required)
  The identifier of the Account Transfer to approve.

## Cancel an Account Transfer
POST /account_transfers/{account_transfer_id}/cancel
> Cancels an Account Transfer in status `pending_approval`.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/account_transfers/account_transfer_7k9qe1ysdgqztnt63l7n/cancel" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `account_transfer_id` (string, required)
  The identifier of the pending Account Transfer to cancel.