# Lockboxes
> Lockboxes are physical locations that can receive mail containing paper checks. Increase will automatically create a Check Deposit for checks received this way.

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

## The Lockbox object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "address": {
    "city": "San Francisco",
    "line1": "1234 Market St",
    "line2": "Ste 567",
    "postal_code": "94114",
    "recipient": "Company Inc. ATTN: VRE6P",
    "state": "CA"
  },
  "check_deposit_behavior": "enabled",
  "created_at": "2020-01-31T23:59:59Z",
  "description": "Lockbox 1",
  "id": "lockbox_3xt21ok13q19advds4t5",
  "idempotency_key": null,
  "recipient_name": "Company Inc.",
  "type": "lockbox"
}
```
### Attributes
- `account_id` (string)
  The identifier for the Account checks sent to this lockbox will be deposited into.

- `address` (dictionary)
  The mailing address for the Lockbox.

  - `address.city` (string)
    The city of the address.

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

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

  - `address.postal_code` (string)
    The postal code of the address.

  - `address.recipient` (string, nullable)
    The recipient line of the address. This will include the recipient name you provide when creating the address, as well as an ATTN suffix to help route the mail to your lockbox. Mail senders must include this ATTN line to receive mail at this Lockbox.

  - `address.state` (string)
    The two-letter United States Postal Service (USPS) abbreviation for the state of the address.

- `check_deposit_behavior` (enum)
  Indicates if checks mailed to this lockbox will be deposited.
  Cases:
  * `enabled` (Checks mailed to this Lockbox will be deposited.)
  * `disabled` (Checks mailed to this Lockbox will not be deposited.)
  * `pend_for_processing` (Checks mailed to this Lockbox will be pending until actioned.)

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

- `description` (string, nullable)
  The description you choose for the Lockbox.

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

- `recipient_name` (string, nullable)
  The recipient name you choose for the Lockbox.

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

## List Lockboxes
GET /lockboxes

### Example
```curl
curl \
  --url "${INCREASE_URL}/lockboxes" \
  -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 Lockboxes to those associated with the provided Account.

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

- `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 Lockbox List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "address": {
        "city": "San Francisco",
        "line1": "1234 Market St",
        "line2": "Ste 567",
        "postal_code": "94114",
        "recipient": "Company Inc. ATTN: VRE6P",
        "state": "CA"
      },
      "check_deposit_behavior": "enabled",
      "created_at": "2020-01-31T23:59:59Z",
      "description": "Lockbox 1",
      "id": "lockbox_3xt21ok13q19advds4t5",
      "idempotency_key": null,
      "recipient_name": "Company Inc.",
      "type": "lockbox"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Lockbox
POST /lockboxes

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/lockboxes" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky",
    "description": "Rent payments"
  }'
```

### Body Parameters
- `account_id` (string, required)
  The Account checks sent to this Lockbox should be deposited into.

- `description` (string, optional)
  The description you choose for the Lockbox, for display purposes.

- `recipient_name` (string, optional)
  The name of the recipient that will receive mail at this location.

## Retrieve a Lockbox
GET /lockboxes/{lockbox_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/lockboxes/lockbox_3xt21ok13q19advds4t5" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `lockbox_id` (string, required)
  The identifier of the Lockbox to retrieve.

## Update a Lockbox
PATCH /lockboxes/{lockbox_id}

### Example
```curl
curl -X "PATCH" \
  --url "${INCREASE_URL}/lockboxes/lockbox_3xt21ok13q19advds4t5" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "check_deposit_behavior": "disabled"
  }'
```
### Path Parameters
- `lockbox_id` (string, required)
  The identifier of the Lockbox.

### Body Parameters
- `check_deposit_behavior` (enum, optional)
  This indicates if checks mailed to this lockbox will be deposited.
  Cases:
  * `enabled` (Checks mailed to this Lockbox will be deposited.)
  * `disabled` (Checks mailed to this Lockbox will not be deposited.)
  * `pend_for_processing` (Checks mailed to this Lockbox will be pending until actioned.)

- `description` (string, optional)
  The description you choose for the Lockbox.

- `recipient_name` (string, optional)
  The recipient name you choose for the Lockbox.