# Transfer Sessions
> Transfer Sessions allow submitting offsetting ACH credit and debit transfers.

## The Transfer Session object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "created_at": "2020-01-31T23:59:59Z",
  "id": "external_account_ukk55lr923a3ac0pp7iv",
  "idempotency_key": null,
  "preferred_effective_date": {
    "date": null,
    "settlement_schedule": "same_day"
  },
  "status": "pending",
  "type": "transfer_session"
}
```
### Attributes
- `account_id` (string)
  The Account the Transfer Session belongs to.

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

- `id` (string)
  The Transfer Session'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).

- `preferred_effective_date` (dictionary)
  Configuration for how the effective date of the transfer will be set. This determines same-day vs future-dated settlement timing. If not set, defaults to a `settlement_schedule` of `same_day`. If set, exactly one of the child attributes must be set.

  - `preferred_effective_date.date` (string, nullable)
    A specific date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format to use as the effective date when submitting this transfer.

  - `preferred_effective_date.settlement_schedule` (enum, nullable)
    A schedule by which Increase will choose an effective date for the transfer.
    Cases:
    * `same_day` (The chosen effective date will be the same as the ACH processing date on which the transfer is submitted.
    This is necessary, but not sufficient for the transfer to be settled same-day:
    it must also be submitted before the last same-day cutoff
    and be less than or equal to $1,000.000.00.
    )
    * `future_dated` (The chosen effective date will be the business day following the ACH processing date on which the transfer is submitted. The transfer will be settled on that future day.)

- `status` (enum)
  The Transfer Session's status.
  Cases:
  * `pending` (The transfer session is pending. Confirm it via the API to submit its associated transfers.)
  * `canceled` (The transfer session is canceled, no transfers will be submitted.)
  * `confirmed` (The transfer session is confirmed, its transfers will be submitted.)

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

## List Transfer Sessions
GET /transfer_sessions

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

- `status.in` (array of enums, optional)
  The status to retrieve Transfer Sessions for. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
  Cases:
  * `pending` (The transfer session is pending. Confirm it via the API to submit its associated transfers.)
  * `canceled` (The transfer session is canceled, no transfers will be submitted.)
  * `confirmed` (The transfer session is confirmed, its transfers will be submitted.)

- `account_id` (string, optional)
  Filter Transfer Sessions to those belonging to 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 Transfer Session List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "created_at": "2020-01-31T23:59:59Z",
      "id": "external_account_ukk55lr923a3ac0pp7iv",
      "idempotency_key": null,
      "preferred_effective_date": {
        "date": null,
        "settlement_schedule": "same_day"
      },
      "status": "pending",
      "type": "transfer_session"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Transfer Session
POST /transfer_sessions

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/transfer_sessions" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky",
    "preferred_effective_date": {
      "settlement_schedule": "future_dated"
    }
  }'
```

### Body Parameters
- `account_id` (string, required)
  The Account the Transfer Session should belong to.

- `preferred_effective_date` (dictionary, required)
  Configuration for how the effective date of the transfer session will be set. This determines same-day vs future-dated settlement timing. If not set, defaults to a `settlement_schedule` of `same_day`. If set, exactly one of the child attributes must be set.

  - `preferred_effective_date.date` (string, optional)
    A specific date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format to use as the effective date when submitting ACH transfers in this session.

  - `preferred_effective_date.settlement_schedule` (enum, optional)
    A schedule by which Increase will choose an effective date for ACH transfers in this session.
    Cases:
    * `same_day` (The chosen effective date will be the same as the ACH processing date on which the transfer is submitted. This is necessary, but not sufficient for the transfer to be settled same-day: it must also be submitted before the last same-day cutoff and be less than or equal to $1,000.000.00.)
    * `future_dated` (The chosen effective date will be the business day following the ACH processing date on which the transfer is submitted. The transfer will be settled on that future day.)

## Retrieve a Transfer Session
GET /transfer_sessions/{transfer_session_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/transfer_sessions/transfer_session_9uawnxxjsednszpnno3d" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `transfer_session_id` (string, required)
  The identifier of the Transfer Session.

## Cancel a Transfer Session
POST /transfer_sessions/{transfer_session_id}/cancel

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/transfer_sessions/transfer_session_9uawnxxjsednszpnno3d/cancel" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `transfer_session_id` (string, required)
  The identifier of the Transfer Session to cancel.

## Confirm a Transfer Session
POST /transfer_sessions/{transfer_session_id}/confirm

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/transfer_sessions/transfer_session_9uawnxxjsednszpnno3d/confirm" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `transfer_session_id` (string, required)
  The identifier of the Transfer Session to confirm.