# Lockbox Recipients
> Lockbox Recipients represent an inbox at a Lockbox Address. Checks received for a Lockbox Recipient are deposited into its associated Account.

[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 Recipient object
### Example
```json
{
  "account_id": "account_in71c4amph0vgo2qllky",
  "created_at": "2020-01-31T23:59:59Z",
  "description": null,
  "id": "lockbox_3xt21ok13q19advds4t5",
  "idempotency_key": null,
  "lockbox_address_id": "lockbox_address_lw6sbzl9ol5dfd8hdml6",
  "mail_stop_code": "VRE6P",
  "recipient_name": "Company Inc.",
  "status": "active",
  "type": "lockbox_recipient"
}
```
### Attributes
- `account_id` (string)
  The identifier for the Account that checks sent to this Lockbox Recipient will be deposited into.

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

- `description` (string, nullable)
  The description of the Lockbox Recipient.

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

- `lockbox_address_id` (string)
  The identifier for the Lockbox Address where this Lockbox Recipient may receive physical mail.

- `mail_stop_code` (string)
  The mail stop code uniquely identifying this Lockbox Recipient at its Lockbox Address. It should be included in the mailing address intended for this Lockbox Recipient.

- `recipient_name` (string, nullable)
  The name of the Lockbox Recipient.

- `status` (enum, nullable)
  The status of the Lockbox Recipient.
  Cases:
  * `active` (This Lockbox Recipient is active.)
  * `disabled` (This Lockbox Recipient is disabled. Checks mailed to this Lockbox Recipient will be rejected.)
  * `canceled` (This Lockbox Recipient is canceled and cannot be modified. Checks mailed to this Lockbox Recipient will be rejected.)

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

## List Lockbox Recipients
GET /lockbox_recipients

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

- `lockbox_address_id` (string, optional)
  Filter Lockbox Recipients to those associated with the provided Lockbox Address.

- `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 Recipient List object:
```json
{
  "data": [
    {
      "account_id": "account_in71c4amph0vgo2qllky",
      "created_at": "2020-01-31T23:59:59Z",
      "description": null,
      "id": "lockbox_3xt21ok13q19advds4t5",
      "idempotency_key": null,
      "lockbox_address_id": "lockbox_address_lw6sbzl9ol5dfd8hdml6",
      "mail_stop_code": "VRE6P",
      "recipient_name": "Company Inc.",
      "status": "active",
      "type": "lockbox_recipient"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Lockbox Recipient
POST /lockbox_recipients

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/lockbox_recipients" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_id": "account_in71c4amph0vgo2qllky",
    "lockbox_address_id": "lockbox_address_lw6sbzl9ol5dfd8hdml6",
    "recipient_name": "Ian Crease"
  }'
```

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

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

- `lockbox_address_id` (string, required)
  The Lockbox Address where this Lockbox Recipient may receive mail.

- `recipient_name` (string, optional)
  The name of the Lockbox Recipient

## Retrieve a Lockbox Recipient
GET /lockbox_recipients/{lockbox_recipient_id}

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

## Update a Lockbox Recipient
PATCH /lockbox_recipients/{lockbox_recipient_id}

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

### Body Parameters
- `description` (string, optional)
  The description you choose for the Lockbox Recipient.

- `recipient_name` (string, optional)
  The name of the Lockbox Recipient.

- `status` (enum, optional)
  The status of the Lockbox Recipient.
  Cases:
  * `active` (This Lockbox Recipient is active.)
  * `disabled` (This Lockbox Recipient is disabled. Checks mailed to this Lockbox Recipient will be rejected.)
  * `canceled` (This Lockbox Recipient is canceled and cannot be modified. Checks mailed to this Lockbox Recipient will be rejected.)