Skip to content
Virtual Mail - API Documentation

Get Shipments

GET
/inboxes/{inbox_id}/shipments

Returns shipments for the given inbox. Supports filtering by status and other criteria.

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

Query Parameters

Section titled “Query Parameters ”
page
integer

The desired page from the result set. Defaults to 1.

per_page
integer

The number of items per page. Defaults to 100.

operation_status
string

Filter by shipment status. Comma-separated list. Allowed values: pending, in_progress, complete, problem.

piece_id
string

Filter by piece IDs. Comma-separated list of integers.

shipping_address_id
string

Filter by shipping address IDs. Comma-separated list of integers.

carrier
string

Filter by carrier. Comma-separated list of strings.

class
string

Filter by carrier service class. Comma-separated list of strings.

is_insured
boolean

Filter by insurance status.

signature_on_delivery
boolean

Filter by signature requirement.

country_abbreviations
string

Filter by destination country. Comma-separated list of ISO 3166-1 alpha-2 country codes.

postal_codes
string

Filter by destination postal code. Comma-separated list of strings.

tracking_number
string

Filter by tracking number. Comma-separated list of strings.

sort_by
string

The field to sort results by. Allowed values: id, requested_at, shipped_at, ship_after, item_count.

sort_direction
string

The direction to sort results. Allowed values: asc, desc.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success

object
total

Total number of items across all pages.

integer
15
per_page

Number of items per page.

integer
100
current_page

The current page number (1-based).

integer
1
last_page

The last available page number.

integer
1
from

The index of the first item on this page (1-based).

integer
1
to

The index of the last item on this page (1-based).

integer
15
data
Array<object>
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
Example
{
  "current_page": 1,
  "data": [
    {
      "id": 123456,
      "created_at": "2024-02-01T10:00:00Z",
      "updated_at": "2024-02-02T10:00:20Z",
      "operation_action": "ship",
      "operation_status": "complete",
      "tags": [],
      "aes_itn": null,
      "completed_at": "2024-07-03T00:00:00Z",
      "contents_type": null,
      "custom_items": [],
      "customs_description": null,
      "declared_value_in_cents": null,
      "estimated_shipped_at": "2024-07-02T10:00:00Z",
      "is_insured": false,
      "is_shared": false,
      "items": [
        {
          "customs_description": null,
          "declared_value_in_cents": null,
          "has_complete_scan": true,
          "piece_id": 123456
        }
      ],
      "owner_user_id": "123456",
      "rate": {
        "carrier_service": "Express",
        "carrier_type": "USPS - Express",
        "created_at": "2024-04-01T12:00:00Z",
        "expired_at": "2024-04-04T12:00:00Z",
        "id": null,
        "price_in_cents": 3000,
        "tracking_available": false
      },
      "rate_id": null,
      "return_address": {
        "address_line_1": "9450 SW Gemini Dr",
        "address_line_2": null,
        "addressee": "John Smith PMB #123456",
        "country": "United States",
        "country_abbreviation": "US",
        "locality": "Beaverton",
        "postal_code": "97008-7105",
        "region": "Oregon",
        "region_abbreviation": "OR"
      },
      "ship_after": "2024-07-02T10:00:00Z",
      "shipped_at": "2024-07-02T00:00:00Z",
      "shipping_address": {
        "id": 123456,
        "created_at": "2022-10-10T10:00:00Z",
        "updated_at": "2022-10-10T10: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": 123456,
        "is_authorized": null,
        "locality": "Siloam Springs",
        "phone": "(111) 111-1111",
        "postal_code": "11111",
        "region": "Arizona",
        "region_abbreviation": "AZ",
        "requires_hs_tariff_codes": false,
        "requires_itn": false,
        "tags": [
          "domestic"
        ]
      },
      "shipping_address_id": 123456,
      "shipping_comment": null,
      "signature_on_delivery": false,
      "tracking_number": "00000000000000000000"
    }
  ],
  "from": 1,
  "to": 1,
  "last_page": 1,
  "per_page": 100,
  "total": 1
}

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"
  }
}

© 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