Request Piece Shredding

POST

/pieces/{piece_id}/disposal

Requests that a piece be shredded. Since shredding requires human action, the piece is not shredded immediately. The expected shredding time is included in the response payload.

Physical pieces are always shredded. The request body must be a JSON object; an empty object ({}) is accepted.

Returns 409 if the piece is no longer active or another operation is already in progress for it.

Authorizations

Send your API key in the x-api-key header. See Authentication.

Parameters

Path Parameters

piece_id

required

string

Request Body^required

object

delete_scans

When true, the piece’s digital scans are deleted along with the physical piece. When false, they are kept. When omitted, existing scans are kept.

boolean

true

Examples

{
  "delete_scans": true
}

{
  "delete_scans": false
}

Responses

200

Success

object

integer

created_at

string format: date-time

updated_at

string format: date-time

operation_action

string

shred

tags

Array<string>

piece_id

integer

estimated_completed_at

string | null format: date-time

completed_at

string | null format: date-time

delete_scans

boolean | null

piece

One of:

object
null

object

integer

14460059

created_at

string format: date-time

updated_at

string format: date-time

inbox_id

integer

barcode

string

0000000101 0016615290

license_plate

integer

433808312186

recipient

object

integer

name

string

Bruce Wayne

inbox_id

integer | null

type

string

mailbox_folder_id

integer

tags

Array<string>

[
  "unscanned",
  "read",
  "inbox",
  "stored"
]

attributes

Array<string>

[
  "unscanned",
  "read",
  "inbox",
  "stored"
]

sender

One of:

object
null

object

name

string

address

string

received_at

string format: date-time

date_arrived_in_mailbox

string format: date-time

weight_in_ounces

number

0.16

facility_name

string

page_count_estimate

integer

page_count_actual

integer | null

height_in_inches

number

3.9

depth_in_inches

number

0.1

length_in_inches

number

8.88

carrier

object

name

string

Unknown

class

string

Unknown

media

Array

object

string

1_1_2_0_0

url

string

content_type

string

image/jpg

tags

Array<string>

[
  "color",
  "large",
  "enclosure",
  "front"
]

url_valid_until

string format: date-time

file_size_in_bytes

integer

piece_id

integer | null

14460059

scan_id

integer | null

page_count

integer | null

sequence_number

integer | null

ocr_data

string

envelope_ocr_data

string

piece_type

string

mail

piece_sub_type

string

letter

insights

Array<object>

object

type

string

confidence

number

user_defined_tags

Array<object>

object

integer

created_at

string format: date-time

updated_at

string format: date-time

label

string

Urgent

parent_tag_id

integer | null

piece_counts

integer | null

matched_by

Array<string>

operation_action

string | null

end_user_operation_status

string | null

storage_fee_amount_in_cents

integer

can_delete_scan_only

boolean

available_actions

Array<string>

name

string

detected_checks_count

integer | null

recipient_type

string

Example

{
  "id": 100001,
  "created_at": "2018-05-21T13:57:09Z",
  "updated_at": "2018-05-21T13:57:09Z",
  "operation_action": "shred",
  "tags": [],
  "piece_id": 293086,
  "estimated_completed_at": "2018-05-24T13:57:09Z",
  "completed_at": null,
  "delete_scans": true,
  "piece": null
}

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.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

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.

object

key

additional properties

Array<string>

Examples

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

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

{
  "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.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

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.

object

key

additional properties

Array<string>

Examples

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

404

The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can’t access, or that don’t exist at all, return 401 instead.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

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.

object

key

additional properties

Array<string>

Example

{
  "error": {
    "code": 404,
    "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.",
    "type": "REST"
  }
}

409

The request conflicts with the current state of the resource.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

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.

object

key

additional properties

Array<string>

422

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

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

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.

object

key

additional properties

Array<string>

Example

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

Request Piece Shredding

Authorizations

Parameters

Path Parameters

Request Body required

Examples

Responses

200

Example

401

Examples

403

Examples

404

Example

409

422

Example

Request Body^required