# Swift Transfers
> Swift Transfers send funds internationally.

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

## The Swift Transfer object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "account_number": "987654321",
  "amount": 100,
  "bank_identification_code": "ECBFDEFFTPP",
  "created_at": "2020-01-31T23:59:59Z",
  "created_by": {
    "category": "user",
    "user": {
      "email": "user@example.com"
    }
  },
  "creditor_address": {
    "city": "Frankfurt",
    "country": "DE",
    "line1": "Sonnemannstrasse 20",
    "line2": null,
    "postal_code": "60314",
    "state": null
  },
  "creditor_name": "Ian Crease",
  "debtor_address": {
    "city": "New York",
    "country": "US",
    "line1": "33 Liberty Street",
    "line2": null,
    "postal_code": "10045",
    "state": null
  },
  "debtor_name": "National Phonograph Company",
  "id": "swift_transfer_29h21xkng03788zwd3fh",
  "idempotency_key": null,
  "instructed_amount": 100,
  "instructed_currency": "USD",
  "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4",
  "routing_number": null,
  "source_account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
  "status": "initiated",
  "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
  "type": "swift_transfer",
  "unique_end_to_end_transaction_reference": "9a21e10a-7600-4a24-8ff3-2cbc5943c27a",
  "unstructured_remittance_information": "Remittance information"
}
```
### Attributes
- `account_id` (string)
  The Account to which the transfer belongs.

- `account_number` (string)
  The creditor's account number.

- `amount` (integer)
  The transfer amount in USD cents.

- `bank_identification_code` (string)
  The bank identification code (BIC) of the creditor.

- `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)
  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.

- `creditor_address` (dictionary)
  The creditor's address.

  - `creditor_address.city` (string, nullable)
    The city, district, town, or village of the address.

  - `creditor_address.country` (string)
    The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code for the country of the address.

  - `creditor_address.line1` (string)
    The first line of the address.

  - `creditor_address.line2` (string, nullable)
    The second line of the address.

  - `creditor_address.postal_code` (string, nullable)
    The ZIP or postal code of the address.

  - `creditor_address.state` (string, nullable)
    The state, province, or region of the address. Required in certain countries.

- `creditor_name` (string)
  The creditor's name.

- `debtor_address` (dictionary)
  The debtor's address.

  - `debtor_address.city` (string, nullable)
    The city, district, town, or village of the address.

  - `debtor_address.country` (string)
    The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code for the country of the address.

  - `debtor_address.line1` (string)
    The first line of the address.

  - `debtor_address.line2` (string, nullable)
    The second line of the address.

  - `debtor_address.postal_code` (string, nullable)
    The ZIP or postal code of the address.

  - `debtor_address.state` (string, nullable)
    The state, province, or region of the address. Required in certain countries.

- `debtor_name` (string)
  The debtor's name.

- `id` (string)
  The Swift 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).

- `instructed_amount` (integer)
  The amount that was instructed to be transferred in minor units of the `instructed_currency`.

- `instructed_currency` (enum)
  The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the instructed amount.
  Cases:
  * `USD` (United States Dollar)

- `pending_transaction_id` (string, nullable)
  The ID for the pending transaction representing the transfer.

- `routing_number` (string, nullable)
  The creditor's bank account routing or transit number. Required in certain countries.

- `source_account_number_id` (string)
  The Account Number included in the transfer as the debtor's account number.

- `status` (enum)
  The lifecycle status of the transfer.
  Cases:
  * `pending_approval` (The transfer is pending approval.)
  * `canceled` (The transfer has been canceled.)
  * `pending_reviewing` (The transfer is pending review by Increase.)
  * `requires_attention` (The transfer requires attention from an Increase operator.)
  * `pending_initiating` (The transfer is pending initiation.)
  * `initiated` (The transfer has been initiated.)
  * `rejected` (The transfer has been rejected by Increase.)
  * `returned` (The transfer has been returned.)

- `transaction_id` (string, nullable)
  The ID for the transaction funding the transfer. This will be populated after the transfer is initiated.

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

- `unique_end_to_end_transaction_reference` (string)
  The Unique End-to-end Transaction Reference ([UETR](https://www.swift.com/payments/what-unique-end-end-transaction-reference-uetr)) for the transfer.

- `unstructured_remittance_information` (string)
  The unstructured remittance information that was included with the transfer.

## List Swift Transfers
GET /swift_transfers

### Example
```curl
curl \
  --url "${INCREASE_URL}/swift_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 Swift 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).

- `status.in` (array of enums, optional)
  Return results whose value is in the provided list. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
  Cases:
  * `pending_approval` (The transfer is pending approval.)
  * `canceled` (The transfer has been canceled.)
  * `pending_reviewing` (The transfer is pending review by Increase.)
  * `requires_attention` (The transfer requires attention from an Increase operator.)
  * `pending_initiating` (The transfer is pending initiation.)
  * `initiated` (The transfer has been initiated.)
  * `rejected` (The transfer has been rejected by Increase.)
  * `returned` (The transfer has been returned.)

- `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 Swift Transfer List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "account_number": "987654321",
      "amount": 100,
      "bank_identification_code": "ECBFDEFFTPP",
      "created_at": "2020-01-31T23:59:59Z",
      "created_by": {
        "category": "user",
        "user": {
          "email": "user@example.com"
        }
      },
      "creditor_address": {
        "city": "Frankfurt",
        "country": "DE",
        "line1": "Sonnemannstrasse 20",
        "line2": null,
        "postal_code": "60314",
        "state": null
      },
      "creditor_name": "Ian Crease",
      "debtor_address": {
        "city": "New York",
        "country": "US",
        "line1": "33 Liberty Street",
        "line2": null,
        "postal_code": "10045",
        "state": null
      },
      "debtor_name": "National Phonograph Company",
      "id": "swift_transfer_29h21xkng03788zwd3fh",
      "idempotency_key": null,
      "instructed_amount": 100,
      "instructed_currency": "USD",
      "pending_transaction_id": "pending_transaction_k1sfetcau2qbvjbzgju4",
      "routing_number": null,
      "source_account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
      "status": "initiated",
      "transaction_id": "transaction_uyrp7fld2ium70oa7oi",
      "type": "swift_transfer",
      "unique_end_to_end_transaction_reference": "9a21e10a-7600-4a24-8ff3-2cbc5943c27a",
      "unstructured_remittance_information": "Remittance information"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Swift Transfer
POST /swift_transfers

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/swift_transfers" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky",
    "account_number": "987654321",
    "bank_identification_code": "ECBFDEFFTPP",
    "creditor_address": {
      "city": "Frankfurt",
      "country": "DE",
      "line1": "Sonnemannstrasse 20",
      "postal_code": "60314"
    },
    "creditor_name": "Ian Crease",
    "debtor_address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "postal_code": "10045",
      "state": "NY"
    },
    "debtor_name": "National Phonograph Company",
    "instructed_amount": 100,
    "instructed_currency": "USD",
    "source_account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
    "unstructured_remittance_information": "New Swift transfer"
  }'
```

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

- `account_number` (string, required)
  The creditor's account number.

- `bank_identification_code` (string, required)
  The bank identification code (BIC) of the creditor. If it ends with the three-character branch code, this must be 11 characters long. Otherwise this must be 8 characters and the branch code will be assumed to be `XXX`.

- `creditor_address` (dictionary, required)
  The creditor's address.

  - `creditor_address.city` (string, required)
    The city, district, town, or village of the address.

  - `creditor_address.country` (string, required)
    The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code for the country of the address.

  - `creditor_address.line1` (string, required)
    The first line of the address. This is usually the street number and street.

  - `creditor_address.line2` (string, optional)
    The second line of the address. This might be the floor or room number.

  - `creditor_address.postal_code` (string, optional)
    The ZIP or postal code of the address. Required in certain countries.

  - `creditor_address.state` (string, optional)
    The state, province, or region of the address. Required in certain countries.

- `creditor_name` (string, required)
  The creditor's name.

- `debtor_address` (dictionary, required)
  The debtor's address.

  - `debtor_address.city` (string, required)
    The city, district, town, or village of the address.

  - `debtor_address.country` (string, required)
    The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code for the country of the address.

  - `debtor_address.line1` (string, required)
    The first line of the address. This is usually the street number and street.

  - `debtor_address.line2` (string, optional)
    The second line of the address. This might be the floor or room number.

  - `debtor_address.postal_code` (string, optional)
    The ZIP or postal code of the address. Required in certain countries.

  - `debtor_address.state` (string, optional)
    The state, province, or region of the address. Required in certain countries.

- `debtor_name` (string, required)
  The debtor's name.

- `instructed_amount` (integer, required)
  The amount, in minor units of `instructed_currency`, to send to the creditor.

- `instructed_currency` (enum, required)
  The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the instructed amount.
  Cases:
  * `USD` (United States Dollar)

- `require_approval` (boolean, optional)
  Whether the transfer requires explicit approval via the dashboard or API.

- `routing_number` (string, optional)
  The creditor's bank account routing or transit number. Required in certain countries.

- `source_account_number_id` (string, required)
  The Account Number to include in the transfer as the debtor's account number.

- `unstructured_remittance_information` (string, required)
  Unstructured remittance information to include in the transfer.

## Retrieve a Swift Transfer
GET /swift_transfers/{swift_transfer_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/swift_transfers/swift_transfer_29h21xkng03788zwd3fh" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `swift_transfer_id` (string, required)
  The identifier of the Swift Transfer.

## Approve a Swift Transfer
POST /swift_transfers/{swift_transfer_id}/approve

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/swift_transfers/swift_transfer_29h21xkng03788zwd3fh/approve" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `swift_transfer_id` (string, required)
  The identifier of the Swift Transfer to approve.

## Cancel a pending Swift Transfer
POST /swift_transfers/{swift_transfer_id}/cancel

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/swift_transfers/swift_transfer_29h21xkng03788zwd3fh/cancel" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `swift_transfer_id` (string, required)
  The identifier of the pending Swift Transfer to cancel.