Skip to content
Virtual Mail - API Documentation

Create Shipment

POST
/inboxes/{inbox_id}/shipments

Creates a shipment request for one or more pieces using a rate previously retrieved with getShippingRates. The shipping address is the one the rate was requested for.

The rate must not be expired, and items must list the same pieces the rate was requested for. All pieces must be stored at the same facility and must not be junk mail or have another operation in progress. Declared values and customs details given here replace the ones from the rate request.

International shipments need customs information (see getShippingRates). If it is missing, the request fails with 400.

Authorizations

Section titled “Authorizations”

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

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
inbox_id
required
string

Request Body required

Section titled “Request Body required ”
object
shipping_address_id

Ignored. The shipping address is taken from the rate.

integer
rate_id
required

The id of a rate returned by getShippingRates. Required.

string
items
required

The pieces to ship. Must match the pieces the rate was requested for.

Array<object>
>= 1 items
object
piece_id
integer
declared_value_in_cents
integer | null
customs_description
string | null
has_complete_scan
boolean
custom_items

Customs line items. Replaces the ones from the rate request.

Array<object>
object
declared_value_in_cents
integer
20000
description
string
men's cotton trousers
hs_tariff_code
string
620520
signature_on_delivery

Require a signature on delivery.

boolean
is_insured

Insure the shipment.

boolean
declared_value_in_cents

Total declared value of the shipment, in cents.

integer | null
customs_description

Description of the contents for customs.

string | null
aes_itn

AES Internal Transaction Number, for destinations whose shipping address has requires_itn.

string | null
contents_type

Kind of contents, for customs. With Documents, HS tariff codes are not required.

string | null
Allowed values: Merchandise Documents ReturnedGoods
ship_after

Earliest date to ship. Optional. If it is missing or not a valid shipping date, the next valid shipping date is used.

string format: date-time
Examples
{
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "items": [
    {
      "piece_id": 1234000
    },
    {
      "piece_id": 1234001
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success

object
id
integer
created_at
string format: date-time
updated_at
string format: date-time
operation_action
string
ship
operation_status
string
pending
tags
Array<string>
shipping_address_id
integer
shipping_address
object
id
integer
123456
created_at
string format: date-time
updated_at
string format: date-time
addressee
string
Molly Smith
address_line_1
string
1004 S Mt Olive St
address_line_2
string
locality
string
PHOENIX
region_abbreviation
string
AZ
region
string
Arizona
country_abbreviation
string
US
country
string
United States
postal_code
string
72761
phone
string
tags
Array<string>
[
  "domestic"
]
delivery_confidence_percent
number | null
inbox_id
integer | null
company
string | null
is_authorized
boolean | null
requires_hs_tariff_codes
boolean | null
requires_itn
boolean | null
rate_id
string | null
shipping_comment
string | null
rate
object
id
string | null
a1b2c3d4-e5f6-7890-abcd-ef1234567890
carrier_type
string
USPS - Express
carrier_service
string
Express
price_in_cents
integer
5335
created_at
string format: date-time
expired_at
string format: date-time
tracking_available
boolean
true
aes_itn
string | null
ship_after
string | null format: date-time
signature_on_delivery
boolean
items
Array<object>
object
piece_id
integer
declared_value_in_cents
integer | null
customs_description
string | null
has_complete_scan
boolean
custom_items
Array<object>
object
declared_value_in_cents
integer
20000
description
string
men's cotton trousers
hs_tariff_code
string
620520
is_insured
boolean
is_shared
boolean
tracking_number
string | null
declared_value_in_cents
integer | null
customs_description
string | null
delivered_at
string | null format: date-time
shipped_at
string | null format: date-time
estimated_shipped_at
string | null format: date-time
completed_at
string | null format: date-time
return_address
object
addressee
string
address_line_1
string
address_line_2
string | null
locality
string
region_abbreviation
string
region
string
country_abbreviation
string
country
string
postal_code
string
delete_scans
boolean
pieces
Array<object>
object
id
integer
14460059
created_at
string format: date-time
updated_at
string format: date-time
inbox_id
integer
97599
barcode
string
0000000101 0016615290
license_plate
integer
433808312186
recipient
object
id
integer
122028
name
string
Bruce Wayne
inbox_id
integer | null
97599
type
string
mailbox_folder_id
integer
0
tags
Array<string>
[
  "unscanned",
  "read",
  "inbox",
  "stored"
]
attributes
Array<string>
[
  "unscanned",
  "read",
  "inbox",
  "stored"
]
sender
One of:
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
2
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
id
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
1
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
id
integer
3001
created_at
string format: date-time
updated_at
string format: date-time
label
string
Urgent
parent_tag_id
integer | null
piece_counts
integer | null
12
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
contents_type
string | null
owner_user_id
string
Examples
{
  "created_at": "2024-11-01T10:00:00Z",
  "id": 60001,
  "updated_at": "2024-11-01T10:00:00Z",
  "operation_action": "ship",
  "operation_status": "pending",
  "tags": [],
  "aes_itn": null,
  "contents_type": null,
  "custom_items": [],
  "customs_description": null,
  "declared_value_in_cents": null,
  "estimated_shipped_at": "2024-11-05T20:00:00Z",
  "is_insured": false,
  "is_shared": false,
  "items": [
    {
      "customs_description": null,
      "declared_value_in_cents": null,
      "has_complete_scan": false,
      "piece_id": 1234000
    },
    {
      "customs_description": null,
      "declared_value_in_cents": null,
      "has_complete_scan": false,
      "piece_id": 1234001
    }
  ],
  "owner_user_id": "12345",
  "pieces": [],
  "rate": {
    "carrier_service": "GroundAdvantage",
    "carrier_type": "USPS - Ground Advantage",
    "created_at": "2024-11-04T10:00:00Z",
    "expired_at": "2024-11-07T10:00:00Z",
    "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
    "price_in_cents": 910,
    "tracking_available": true
  },
  "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342",
  "return_address": {
    "address_line_1": "",
    "address_line_2": null,
    "addressee": "",
    "country": "",
    "country_abbreviation": "",
    "locality": "",
    "postal_code": "",
    "region": "",
    "region_abbreviation": ""
  },
  "ship_after": "2024-11-05T20:00:00Z",
  "shipping_address": {
    "created_at": "2024-11-04T10:00:00Z",
    "id": 12345,
    "updated_at": "2024-11-04T10:00:00Z",
    "address_line_1": "1004 S Mt Olive St",
    "address_line_2": "",
    "addressee": "Molly Smith",
    "company": null,
    "country": "United States",
    "country_abbreviation": "US",
    "delivery_confidence_percent": null,
    "inbox_id": 97599,
    "is_authorized": null,
    "locality": "PHOENIX",
    "phone": "",
    "postal_code": "72761",
    "region": "Arizona",
    "region_abbreviation": "AZ",
    "requires_hs_tariff_codes": false,
    "requires_itn": false,
    "tags": [
      "domestic"
    ]
  },
  "shipping_address_id": 12345,
  "shipping_comment": null,
  "signature_on_delivery": false,
  "tracking_number": null
}

400

Section titled “400 ”

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

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
401
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>

401

Section titled “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
401
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"
  }
}

403

Section titled “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
401
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

Section titled “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
401
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"
  }
}

422

Section titled “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
401
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": {}
  }
}

© LegalZoom.com, Inc. All rights reserved.

LegalZoom provides access to independent attorneys and self-service tools. LegalZoom is not a law firm and does not provide legal advice, except where authorized through its subsidiary law firm LZ Legal Services, LLC. Use of our products and services is governed by our Terms of Use and Privacy Policy.

AI-readable documentation index: llms.txt