# Checkbooks
> Checkbooks are sets of blank checks that Increase prints and mails on your behalf.

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

## The Checkbook object
### Example
```json
{
  "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
  "created_at": "2020-01-31T23:59:59Z",
  "id": "checkbook_7iudxhxum6vlkcjxmi8y",
  "idempotency_key": null,
  "mailing_address": {
    "city": "New York",
    "line1": "33 Liberty Street",
    "line2": null,
    "name": "Ian Crease",
    "postal_code": "10045",
    "state": "NY"
  },
  "payer": [
    {
      "contents": "National Phonograph Company"
    },
    {
      "contents": "33 Liberty Street"
    },
    {
      "contents": "New York, NY 10045"
    }
  ],
  "return_address": {
    "city": "San Francisco",
    "line1": "244 Kearny St",
    "line2": "Floor 8",
    "name": "Undeliverable Mail",
    "postal_code": "94108",
    "state": "CA"
  },
  "status": "mailed",
  "tracking_updates": [
    {
      "category": "in_transit",
      "country": "US",
      "created_at": "2020-01-31T23:59:59Z",
      "postal_code": "10045"
    },
    {
      "category": "delivered",
      "country": "US",
      "created_at": "2020-01-31T23:59:59Z",
      "postal_code": "10045"
    }
  ],
  "type": "checkbook"
}
```
### Attributes
- `account_number_id` (string)
  The identifier of the Account Number the Checkbook is attached to.

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

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

- `mailing_address` (dictionary)
  The destination address that the Checkbook will be mailed to.

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

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

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

  - `mailing_address.name` (string)
    The recipient at the destination address.

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

  - `mailing_address.state` (string)
    The state of the destination address.

- `payer` (array of objects)
  The payer information printed on the top-left corner of each check.

  - `payer.contents` (string)
    The contents of the line.

- `return_address` (dictionary)
  The address where the Checkbook will return to if there is a delivery issue.

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

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

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

  - `return_address.name` (string)
    The recipient at the return address.

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

  - `return_address.state` (string)
    The state of the return address.

- `status` (enum)
  The lifecycle status of the Checkbook.
  Cases:
  * `pending_submission` (The Checkbook is pending submission to the printer.)
  * `pending_mailing` (The Checkbook has been submitted to the printer and is pending mailing.)
  * `mailed` (The Checkbook has been mailed.)
  * `stopped` (The Checkbook has been stopped and its checks can no longer be deposited.)

- `tracking_updates` (array of objects)
  Tracking updates relating to the Checkbook's delivery.

  - `tracking_updates.category` (enum)
    The type of tracking event.
    Cases:
    * `in_transit` (The checkbook is in transit.)
    * `processed_for_delivery` (The checkbook has been processed for delivery.)
    * `delivered` (The checkbook has been delivered. Note that some couriers track delivery status based on driver location data rather than an explicit scan. While uncommon, a single checkbook may have more than one delivered event.)
    * `delivery_issue` (There is an issue preventing delivery. The delivery will be attempted again if possible. If the issue cannot be resolved, the checkbook will be rerouted to the return address.)
    * `returning_to_sender` (The checkbook has been rerouted to the return address.)
    * `returned_to_sender` (The checkbook has been delivered to the return address.)

  - `tracking_updates.country` (string)
    The ISO 3166-1 alpha-2 country code for the country where the event took place.

  - `tracking_updates.created_at` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the tracking event took place.

  - `tracking_updates.postal_code` (string)
    The postal code where the event took place.

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

## List Checkbooks
GET /checkbooks

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

- `account_number_id` (string, optional)
  Filter Checkbooks to those attached to the specified Account Number.

- `status.in` (array of enums, optional)
  Filter Checkbooks for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.

  Cases:
  * `pending_submission` (The Checkbook is pending submission to the printer.)
  * `pending_mailing` (The Checkbook has been submitted to the printer and is pending mailing.)
  * `mailed` (The Checkbook has been mailed.)
  * `stopped` (The Checkbook has been stopped and its checks can no longer be deposited.)

- `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 Checkbook List object:
```json
{
  "data": [
    {
      "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
      "created_at": "2020-01-31T23:59:59Z",
      "id": "checkbook_7iudxhxum6vlkcjxmi8y",
      "idempotency_key": null,
      "mailing_address": {
        "city": "New York",
        "line1": "33 Liberty Street",
        "line2": null,
        "name": "Ian Crease",
        "postal_code": "10045",
        "state": "NY"
      },
      "payer": [
        {
          "contents": "National Phonograph Company"
        },
        {
          "contents": "33 Liberty Street"
        },
        {
          "contents": "New York, NY 10045"
        }
      ],
      "return_address": {
        "city": "San Francisco",
        "line1": "244 Kearny St",
        "line2": "Floor 8",
        "name": "Undeliverable Mail",
        "postal_code": "94108",
        "state": "CA"
      },
      "status": "mailed",
      "tracking_updates": [
        {
          "category": "in_transit",
          "country": "US",
          "created_at": "2020-01-31T23:59:59Z",
          "postal_code": "10045"
        },
        {
          "category": "delivered",
          "country": "US",
          "created_at": "2020-01-31T23:59:59Z",
          "postal_code": "10045"
        }
      ],
      "type": "checkbook"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Checkbook
POST /checkbooks

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/checkbooks" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
    "mailing_address": {
      "city": "New York",
      "line1": "33 Liberty Street",
      "name": "Ian Crease",
      "postal_code": "10045",
      "state": "NY"
    },
    "payer": [
      {
        "contents": "National Phonograph Company"
      },
      {
        "contents": "33 Liberty Street"
      },
      {
        "contents": "New York, NY 10045"
      }
    ]
  }'
```

### Body Parameters
- `account_number_id` (string, required)
  The identifier of the Account Number that the checks will draw from. The Account Number must be active.

- `mailing_address` (dictionary, required)
  The destination address that the Checkbook will be mailed to.

  - `mailing_address.city` (string, required)
    The city of the destination address.

  - `mailing_address.line1` (string, required)
    The first line of the destination address.

  - `mailing_address.line2` (string, optional)
    The second line of the destination address.

  - `mailing_address.name` (string, required)
    The recipient at the destination address.

  - `mailing_address.postal_code` (string, required)
    The postal code of the destination address.

  - `mailing_address.state` (string, required)
    The US state of the destination address.

- `payer` (array of objects, required)
  The payer of the checks. This will be printed on the top-left corner of each check. This should be an array of up to 4 elements, each of which represents a line of the payer.

  - `payer.contents` (string, required)
    The contents of the line.

## Retrieve a Checkbook
GET /checkbooks/{checkbook_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/checkbooks/checkbook_7iudxhxum6vlkcjxmi8y" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `checkbook_id` (string, required)
  The identifier of the Checkbook.

## Stop a Checkbook
POST /checkbooks/{checkbook_id}/stop
> Stop a Checkbook. Stopping a Checkbook stops all of its checks that have not yet been deposited.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/checkbooks/checkbook_7iudxhxum6vlkcjxmi8y/stop" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `checkbook_id` (string, required)
  The identifier of the Checkbook to stop.

## Sandbox: Mail a Checkbook
POST /simulations/checkbooks/{checkbook_id}/mail
> Simulates the mailing of a [Checkbook](#checkbooks), which happens periodically throughout the day in production but can be sped up in sandbox. This Checkbook must have a `status` of `pending_submission` or `pending_mailing`.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/checkbooks/checkbook_7iudxhxum6vlkcjxmi8y/mail" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `checkbook_id` (string, required)
  The identifier of the Checkbook you wish to mail.