# Request Check Deposit

> `POST /pieces/{piece_id}/check-deposit-requests`

Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/requestcheckdeposit/

URL: `POST https://api.earthclassmail.com/v1/pieces/{piece_id}/check-deposit-requests`

Requests a deposit of the checks in a piece to one of the inbox's bank accounts. A deposit needs human action, so the response describes the new request, not a completed deposit: the mailroom extracts the checks and ships them to the bank, and the request's `status` follows those steps.

Get the bank account ID from [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md). Use `post_operation_action` to shred the rest of the piece once the checks are out. Without it, the piece is kept.

Returns `409` if another operation is in progress for the piece or its checks have already been requested for deposit, and `400` if the account is not active.

## Authorization

Send your API key in the `x-api-key` header.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `piece_id` | path | yes | string |  |

## Request body

Required.

Content type: `application/json`

Type: `CreateCheckDepositRequest`

Example — Deposit and keep the piece:

```json
{
  "check_deposit_bank_account_id": 500
}
```

Example — Expedited deposit, then shred:

```json
{
  "check_deposit_bank_account_id": 500,
  "expedited": true,
  "post_operation_action": {
    "type": "shred"
  }
}
```

## Responses

### 200

Success

Content type: `application/json`

Type: `PieceCheckDepositRequest`

Example:

```json
{
  "id": 100001,
  "created_at": "2020-05-10T09:41:00Z",
  "updated_at": "2020-05-10T09:41:00Z",
  "operation_action": "check-deposit",
  "operation_status": "pending",
  "status": "Opened",
  "check_deposit_bank_account_id": 500,
  "piece_id": 100002,
  "inbox_id": 100003,
  "expedited": true,
  "post_operation_action": {
    "type": "shred"
  },
  "checks": [],
  "piece": {
    "id": 100002
  }
}
```

### 400

The request could not be processed, for example an international shipment without customs information.

Content type: `application/json`

Type: `Error`

### 401

The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access.

Content type: `application/json`

Type: `Error`

Example — Missing API key:

```json
{
  "error": {
    "code": 401,
    "message": "The request does not include a valid access token. Please provide a valid access token.",
    "type": "Authorization"
  }
}
```

Example — Invalid API key:

```json
{
  "error": {
    "code": 401,
    "message": "x-api-key: x-api-key is invalid",
    "type": "REST"
  }
}
```

Example — No access to resource:

```json
{
  "error": {
    "code": 401,
    "message": "User does not have access to requested resource.",
    "type": "Authorization"
  }
}
```

### 403

Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`.

Content type: `application/json`

Type: `Error`

Example — Piece actions blocked:

```json
{
  "error": {
    "code": 403,
    "message": "piece: Mail actions for piece with ID 123456 has been blocked.",
    "type": "REST"
  }
}
```

### 409

The request conflicts with the current state of the resource.

Content type: `application/json`

Type: `Error`

### 422

The request body failed validation. The message names the invalid field.

Content type: `application/json`

Type: `Error`

Example:

```json
{
  "error": {
    "code": 422,
    "message": "label: must have a value",
    "type": "REST",
    "fields": {}
  }
}
```

## Schemas

### CreateCheckDepositRequest

- `check_deposit_bank_account_id` (integer, required): The bank account to deposit to, from [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md).
- `expedited` (boolean): Ship the checks to the bank overnight instead of by standard mail, for a fee; see [Virtual Mail detailed pricing](https://www.legalzoom.com/business/business-operations/lz-virtual-mail-detailed-pricing.html). Overnight deposits typically reach the bank in 1 business day; allow one more for requests made after 5 PM. Skip it when the bank account's `financial_institution.expedited` is `true`: those banks get overnight delivery for free on every deposit. When the bank has no street address a courier can deliver to, the checks go by the fastest postal service instead. Default: `false`.
- `post_operation_action` (`PostDepositOperationAction` or null): What to do with the rest of the piece once the checks are out. Without it, the piece is kept.

### Error

Error envelope returned with 4xx and 5xx responses.

- `error` (object)
  - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.
  - `message` (string): Human-readable description of the error.
  - `type` (string): The kind of error, for example `Authorization` or `REST`.
  - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

### PieceCheckDepositRequest

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `operation_action` (string)
- `operation_status` (string)
- `tags` (array of string)
- `check_deposit_bank_account_id` (integer or null)
- `status` (string): `Opened` while the request is in progress, then `Shipped` once the checks are on their way to the bank. `Cancelled` and `Error` end a request without a deposit.
- `expedited` (boolean): Whether overnight delivery to the bank was requested. See `expedited` in Request Check Deposit.
- `bank_account` (`InboxCheckDepositBankAccount`)
- `resubmittable` (boolean)
- `checks` (array of `DepositCheck`)
- `shipment` (`PieceCheckDepositShipment` or null)
- `inbox_id` (integer or null)
- `post_operation_action` (`PostDepositOperationAction` or null)
- `piece_id` (integer)
- `deposit_slips` (array of `Media`)
- `requested_at` (string<date-time>)
- `extracted_at` (string<date-time>)
- `check_processing_system_type` (integer)
- `validate_only` (boolean)
- `scan_page_number` (integer)
- `piece` (`Piece` or null)
- `date_arrived_at` (string<date-time>)
- `deposit_slip_ids` (array of integer)

### DepositCheck

- `id` (integer)
- `amount_in_cents` (integer)
- `check_number` (string)
- `piece_id` (integer)
- `media` (array of `Media`)

### InboxCheckDepositBankAccount

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `inbox_id` (integer or null)
- `routing_number` (string)
- `check_processing_system_type` (integer)
- `account_number` (string)
- `account_display_name` (string)
- `account_type` (string)
- `financial_institution` (`BankingInstitution`)
- `contact_name` (string)
- `contact_business` (string)
- `contact_address` (string)
- `contact_phone` (string)
- `rdc` (boolean)

### Media

- `id` (string)
- `url` (string)
- `content_type` (string)
- `tags` (array of string)
- `url_valid_until` (string<date-time>)
- `file_size_in_bytes` (integer)

### Piece

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `inbox_id` (integer)
- `barcode` (string)
- `license_plate` (integer)
- `recipient` (`PieceRecipient`)
- `mailbox_folder_id` (integer)
- `tags` (array of string)
- `attributes` (array of string)
- `sender` (`PieceSender` or null)
- `received_at` (string<date-time>)
- `date_arrived_in_mailbox` (string<date-time>)
- `weight_in_ounces` (number)
- `facility_name` (string)
- `page_count_estimate` (integer)
- `page_count_actual` (integer or null)
- `height_in_inches` (number)
- `depth_in_inches` (number)
- `length_in_inches` (number)
- `carrier` (`PieceCarrier`)
- `media` (array of `PieceMedia`)
- `ocr_data` (string)
- `envelope_ocr_data` (string)
- `piece_type` (string)
- `piece_sub_type` (string)
- `insights` (array of `PieceInsight`)
- `user_defined_tags` (array of `Tag`)
- `matched_by` (array of string)
- `operation_action` (string or null)
- `end_user_operation_status` (string or null)
- `storage_fee_amount_in_cents` (integer)
- `can_delete_scan_only` (boolean)
- `available_actions` (array of string)
- `name` (string)
- `detected_checks_count` (integer or null)
- `recipient_type` (string)

### PieceCheckDepositShipment

- `id` (integer or null)
- `carrier` (string)
- `carrier_service` (string)
- `tracking_number` (string)
- `external_id` (string or null)
- `shipped_at` (string<date-time>)
- `expected_delivery_at` (string<date-time>)
- `delivered_at` (string<date-time>)

### PostDepositOperationAction

- `type` (string, required): `store` keeps the piece, `shred` shreds it. One of: `store`, `shred`.

### BankingInstitution

- `id` (integer)
- `name` (string)
- `routing_number` (string)
- `has_shipping_address` (boolean)
- `shipping_banking_institution_id` (integer or null)
- `expedited` (boolean): When `true`, every deposit to this bank ships overnight at no extra cost, so there's no need to request `expedited`.
- `shipping_addresses` (array of `ShippingAddress`)
- `rdc` (boolean)
- `rdcVerified` (boolean)

### PieceCarrier

- `name` (string)
- `class` (string)

### PieceInsight

- `type` (string)
- `confidence` (number)

### PieceMedia

- `id` (string)
- `url` (string)
- `content_type` (string)
- `tags` (array of string)
- `url_valid_until` (string<date-time>)
- `file_size_in_bytes` (integer)
- `piece_id` (integer or null)
- `scan_id` (integer or null)
- `page_count` (integer or null)
- `sequence_number` (integer or null)

### PieceRecipient

- `id` (integer)
- `name` (string)
- `inbox_id` (integer or null)
- `type` (string)

### PieceSender

- `name` (string)
- `address` (string)

### Tag

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `label` (string)
- `parent_tag_id` (integer or null)
- `piece_counts` (integer or null)

### ShippingAddress

- `id` (integer)
- `created_at` (string<date-time>)
- `updated_at` (string<date-time>)
- `addressee` (string)
- `address_line_1` (string)
- `address_line_2` (string)
- `locality` (string)
- `region_abbreviation` (string)
- `region` (string)
- `country_abbreviation` (string)
- `country` (string)
- `postal_code` (string)
- `phone` (string)
- `tags` (array of string)
- `delivery_confidence_percent` (number or null)
- `inbox_id` (integer or null)
- `company` (string or null)
- `is_authorized` (boolean or null)
- `requires_hs_tariff_codes` (boolean or null)
- `requires_itn` (boolean or null)