1. Trackers
  2. Retrieve Trackers

Trackers

Retrieve Trackers

When working with trackers, you can retrieve a single tracker using its ID.

GET
`/v1/trackers/:tracker`

Retrieves detailed information about a specific tracker using its ID. The response includes comprehensive data about the tracker including its shipments, destination details, contact information, and tracking history.

js 
        const res = await fetch("https://api.packagex.io/v1/trackers/track_czhgjrk5JaVvyATPDbyURp", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const tracker = res.data;

The response includes the tracker's complete information with associated data including:

  • Shipment details with rates, parcels, and provider information
  • Up to 100 most recent tracking updates, ordered chronologically
  • Destination information including address, layout, and location details
  • Sender and recipient contact information
  • Associated addresses and location groups

If the tracker ID doesn't exist or belongs to a different organization, the API will return a 404 error.

List Trackers

Retrieve a paginated list of trackers in your organization. The endpoint returns tracker details including shipments, destinations, contacts, and tracking updates. The response includes a data array of trackers (even when empty), pagination information, and a result count message.

By default, returns 25 trackers sorted by creation date in descending order. Results can be filtered by location, status, contacts, shipping details, and other criteria. When using the search parameter without a specified sort order, results are automatically sorted by relevance score.

For multi-shipment trackers, updates are chronologically ordered to show the complete tracking journey.

GET
`/v1/trackers`
js 
        const response = await fetch("https://api.packagex.io/v1/trackers", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const trackers = response.data;
const pagination = response.pagination;

Pagination

The response includes a pagination object with the following properties:

  • has_more - Indicates if there are more trackers available
  • page - Current page number (default: 1)
  • limit - Number of results per page (default: 25)
  • total_count - Total number of trackers in the database.

To retrieve the next page of results:

js 
        const response = await fetch("https://api.packagex.io/v1/trackers?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());
const trackers = response.data;
const pagination = response.pagination;

Filtering

The API supports comprehensive filtering of trackers through query parameters. Multiple filters can be combined to refine your results.

Contact and Group Filters:

  • destination_contact_id (or destination_contact, recipient_contact, recipient_contact_id): Filter by recipient contact ID
  • sender_contact_id (or sender_contact): Filter by sender contact ID
  • recipient_groups: Filter by recipient contact groups
  • sender_groups: Filter by sender contact groups
  • groups: Filter by general contact groups

Location Filters:

  • location_id (or location): Filter by current location
  • destination_location_id (or destination_location): Filter by destination location
  • destination_layout_id: Filter by specific layout at destination

Status and Type Filters:

  • status or statuses: Filter by one or more tracking statuses (comma or space-separated)
  • type (or tracker_type): Filter by tracker type
  • filter: Quick filter by predefined states: "completed", "outstanding", "exception", "refunded"

Shipping Details:

  • providers (or provider): Filter by shipping provider IDs
  • service_levels: Filter by service level IDs
  • tags: Filter by shipment tags
  • shipping_label_inference_id: Filter by inference ID

Time-based Filters:

  • start_at: Filter by creation date starting point
  • created_at: Filter by creation date
  • updated_at: Filter by last update date
  • updated_by: Filter by user IDs (user_xxx), API key IDs, or organization IDs (org_xxx), using comma or space-separated values

Custom Filters:

Metadata Filtering

  • metadata.[field_name] - Filter trackers by custom metadata field values. For example, to find trackers where the metadata field "customer_id" equals "12345", use metadata.customer_id=12345. Only one metadata field can be filtered at a time, with the last specified metadata filter taking precedence.
js 
        const response = await fetch(
  "https://api.packagex.io/v1/trackers?metadata.customer_id=12345",
  {
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
  }
);

const trackers = response.data;
const pagination = response.pagination;

Example with multiple filters:

js 
        const response = await fetch(
  "https://api.packagex.io/v1/trackers?location_id=loc_xxx&statuses=delivered,picked_up&destination_contact_id=ctct_xxx&type=inbound",
  {
    method: "GET",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
  }
).then((res) => res.json());

const trackers = response.data;
const pagination = response.pagination;

Sorting

Control the order of results using:

  • order_by: Sort by a specific field
    • Available fields: created_at, updated_at, estimated_delivery_at
  • direction: Sort direction (asc or desc)

If no sorting parameter is specified, the system defaults to sorting by created_at in descending order desc

Example with sorting:

js 
        const response = await fetch("https://api.packagex.io/v1/trackers?order_by=created_at&direction=desc", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());
const trackers = response.data;
const pagination = response.pagination;

The API provides advanced full-text search capabilities through the search parameter, allowing you to locate specific trackers using fuzzy, typo-tolerant matching across multiple fields. The search functionality examines key tracker properties including:

  • recipient_names
  • sender_names
  • recipient_emails
  • sender_emails
  • destination_contact_group
  • sender_contact_group
  • tracking_number
js 
        const response = await fetch(
  "https://api.packagex.io/v1/trackers?search=jamie%20jones",
  {
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
  }
).then((res) => res.json());

Each tracker in the search results includes a special _search object that provides detailed information about the match:

js 
        "_search": {
  "recipient_names": ["<mark>jamie</mark> <mark>jones</mark>"],
  "sender_names": ["shipping department"],
  "recipient_emails": ["jamie.jones@email.com"],
  "sender_emails": ["shipping@company.com"],
  "destination_contact_group": [],
  "sender_contact_group": [],
  "tracking_number": "PKGX-123456",
  "relevance_score": 0.92,
  "query": "jamie jones"
}

The _search object includes highlighted matches using <mark> tags, making it easy to emphasize matching text in user interfaces. It also provides a relevance score between 0 and 1, where higher values indicate better matches. By default, search results are ordered by relevance score to show the best matches first. However, you can override this by specifying an order_by parameter to sort by other fields like created_at, updated_at, or estimated_delivery_at. The search functionality can be combined with other filter parameters to refine your results further.

Previous <- Statuses & Events
Next Create Trackers ->