GET /v5/shipment/list/ searches your Shipments and returns each match’s key information plus its latest event. For a single Shipment’s full record, use Retrieve Shipment Details. All parameters: API reference.
The date range is required
Every request must include exactly one of these pairs — they cannot be combined:created_date_from+created_date_toupdated_date_from+updated_date_tolatest_event_date_from+latest_event_date_to
_from ≤ _to, format yyyy-mm-ddThh:mm:ss (processed as UTC), and _from at most 13 months in the past — Perform.AI’s search retention window.
Filters and AND/OR conditions
Filters include identifiers and references,carrier_id / carrier_reference, status, current_phase, tags, notification contacts, from_country_code / to_country_code, issue_state, issue_types, and shipping_type — the reference lists them all with their limits.
Most filters accept AND/OR bracket syntax. String values must be quoted, and one bracket level means AND while two mean OR:
Pagination
Pagination is cursor-based:- First request:
next_page=0(or omit it).limitis 25–100, default 25. - Each response returns a
next_pagecursor — pass it into the next request unchanged. - You’re on the last page when the response no longer contains
next_page.
total_result reports the total match count on every page.
Read the response
A valid search with zero matches returns HTTP 404 with
api_response "4041" — not an empty array. Treat it as “no shipments matched”, not as a failure. (Document, label, PUDO, and carrier-config listings behave differently and return 200 with empty data.)Common validation failures
Next steps
- Fetch full records with Retrieve Shipment Details.
- Replace polling loops with webhooks — the list API is for search and reconciliation, not change detection.