# Wire Drawdown Requests
> Wire drawdown requests enable you to request that someone else send you a wire. Because there is nuance to making sure your counterparty's bank processes these correctly, we ask that you reach out to [support@increase.com](mailto:support@increase.com) to enable this feature so we can help you plan your integration. For more information, see our [Wire Drawdown Requests documentation](/documentation/wire-drawdown-requests).

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

## The Wire Drawdown Request object
### Example
```json
{
  "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
  "amount": 10000,
  "created_at": "2020-01-31T23:59:59Z",
  "creditor_address": {
    "city": "New York",
    "country": "US",
    "line1": "33 Liberty Street",
    "line2": null,
    "postal_code": "10045",
    "state": "NY"
  },
  "creditor_name": "Ian Crease",
  "currency": "USD",
  "debtor_account_number": "987654321",
  "debtor_address": {
    "city": "New York",
    "country": "US",
    "line1": "33 Liberty Street",
    "line2": null,
    "postal_code": "10045",
    "state": "NY"
  },
  "debtor_external_account_id": null,
  "debtor_name": "Ian Crease",
  "debtor_routing_number": "101050001",
  "fulfillment_inbound_wire_transfer_id": "inbound_wire_transfer_f228m6bmhtcxjco9pwp0",
  "id": "wire_drawdown_request_q6lmocus3glo0lr2bfv3",
  "idempotency_key": null,
  "status": "fulfilled",
  "submission": {
    "input_message_accountability_data": "20220118MMQFMP0P000003"
  },
  "type": "wire_drawdown_request",
  "unstructured_remittance_information": "Invoice 29582"
}
```
### Attributes
- `account_number_id` (string)
  The Account Number to which the debtor—the recipient of this request—is being requested to send funds.

- `amount` (integer)
  The amount being requested in cents.

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

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

  - `creditor_address.city` (string)
    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 code of the address.

  - `creditor_address.state` (string, nullable)
    The address state.

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

- `currency` (string)
  The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the amount being requested. Will always be "USD".

- `debtor_account_number` (string)
  The debtor's account number.

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

  - `debtor_address.city` (string)
    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 code of the address.

  - `debtor_address.state` (string, nullable)
    The address state.

- `debtor_external_account_id` (string, nullable)
  The debtor's external account identifier.

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

- `debtor_routing_number` (string)
  The debtor's routing number.

- `fulfillment_inbound_wire_transfer_id` (string, nullable)
  If the recipient fulfills the drawdown request by sending funds, then this will be the identifier of the corresponding Transaction.

- `id` (string)
  The Wire drawdown request 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).

- `status` (enum)
  The lifecycle status of the drawdown request.
  Cases:
  * `pending_submission` (The drawdown request is queued to be submitted to Fedwire.)
  * `fulfilled` (The drawdown request has been fulfilled by the recipient.)
  * `pending_response` (The drawdown request has been sent and the recipient should respond in some way.)
  * `refused` (The drawdown request has been refused by the recipient.)

- `submission` (dictionary, nullable)
  After the drawdown request is submitted to Fedwire, this will contain supplemental details.

  - `submission.input_message_accountability_data` (string)
    The input message accountability data (IMAD) uniquely identifying the submission with Fedwire.

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

- `unstructured_remittance_information` (string)
  Remittance information the debtor will see as part of the drawdown request.

## Sandbox: Refuse a Wire Drawdown Request
POST /simulations/wire_drawdown_requests/{wire_drawdown_request_id}/refuse
> Simulates a Wire Drawdown Request being refused by the debtor.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/wire_drawdown_requests/wire_drawdown_request_q6lmocus3glo0lr2bfv3/refuse" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_drawdown_request_id` (string, required)
  The identifier of the Wire Drawdown Request you wish to refuse.

## Sandbox: Submit a Wire Drawdown Request
POST /simulations/wire_drawdown_requests/{wire_drawdown_request_id}/submit
> Simulates a Wire Drawdown Request being submitted to Fedwire.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/wire_drawdown_requests/wire_drawdown_request_q6lmocus3glo0lr2bfv3/submit" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_drawdown_request_id` (string, required)
  The identifier of the Wire Drawdown Request you wish to submit.

## List Wire Drawdown Requests
GET /wire_drawdown_requests

### Example
```curl
curl \
  --url "${INCREASE_URL}/wire_drawdown_requests" \
  -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)
  Filter Wire Drawdown Requests for those with the specified status. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
  Cases:
  * `pending_submission` (The drawdown request is queued to be submitted to Fedwire.)
  * `fulfilled` (The drawdown request has been fulfilled by the recipient.)
  * `pending_response` (The drawdown request has been sent and the recipient should respond in some way.)
  * `refused` (The drawdown request has been refused by the recipient.)

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

### Returns a Wire Drawdown Request List object:
```json
{
  "data": [
    {
      "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
      "amount": 10000,
      "created_at": "2020-01-31T23:59:59Z",
      "creditor_address": {
        "city": "New York",
        "country": "US",
        "line1": "33 Liberty Street",
        "line2": null,
        "postal_code": "10045",
        "state": "NY"
      },
      "creditor_name": "Ian Crease",
      "currency": "USD",
      "debtor_account_number": "987654321",
      "debtor_address": {
        "city": "New York",
        "country": "US",
        "line1": "33 Liberty Street",
        "line2": null,
        "postal_code": "10045",
        "state": "NY"
      },
      "debtor_external_account_id": null,
      "debtor_name": "Ian Crease",
      "debtor_routing_number": "101050001",
      "fulfillment_inbound_wire_transfer_id": "inbound_wire_transfer_f228m6bmhtcxjco9pwp0",
      "id": "wire_drawdown_request_q6lmocus3glo0lr2bfv3",
      "idempotency_key": null,
      "status": "fulfilled",
      "submission": {
        "input_message_accountability_data": "20220118MMQFMP0P000003"
      },
      "type": "wire_drawdown_request",
      "unstructured_remittance_information": "Invoice 29582"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Wire Drawdown Request
POST /wire_drawdown_requests

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/wire_drawdown_requests" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
    "amount": 10000,
    "creditor_address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "postal_code": "10045",
      "state": "NY"
    },
    "creditor_name": "National Phonograph Company",
    "debtor_account_number": "987654321",
    "debtor_address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "postal_code": "10045",
      "state": "NY"
    },
    "debtor_name": "Ian Crease",
    "debtor_routing_number": "101050001",
    "unstructured_remittance_information": "Invoice 29582"
  }'
```

### Body Parameters
- `account_number_id` (string, required)
  The Account Number to which the debtor should send funds.

- `amount` (integer, required)
  The amount requested from the debtor, in USD cents.

- `charge_bearer` (enum, optional)
  Determines who bears the cost of the drawdown request. Defaults to `shared` if not specified.
  Cases:
  * `shared` (Charges are shared between the debtor and creditor.)
  * `debtor` (Charges are borne by the debtor.)
  * `creditor` (Charges are borne by the creditor.)
  * `service_level` (Charges are determined by the service level.)

- `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 code of the address.

  - `creditor_address.state` (string, optional)
    The address state.

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

- `debtor_account_number` (string, optional)
  The debtor's account number.

- `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 code of the address.

  - `debtor_address.state` (string, optional)
    The address state.

- `debtor_external_account_id` (string, optional)
  The ID of an External Account to initiate a transfer to. If this parameter is provided, `debtor_account_number` and `debtor_routing_number` must be absent.

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

- `debtor_routing_number` (string, optional)
  The debtor's routing number.

- `end_to_end_identification` (string, optional)
  A free-form reference string set by the sender mirrored back in the subsequent wire transfer.

- `unstructured_remittance_information` (string, required)
  Remittance information the debtor will see as part of the request.

## Retrieve a Wire Drawdown Request
GET /wire_drawdown_requests/{wire_drawdown_request_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/wire_drawdown_requests/wire_drawdown_request_q6lmocus3glo0lr2bfv3" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `wire_drawdown_request_id` (string, required)
  The identifier of the Wire Drawdown Request to retrieve.