Utils

Detect Provider

Automatically identify the shipping provider (carrier) for a tracking number and get a link to its tracking page - no manual carrier selection required. This is a stateless lookup: it does not create a tracker.

# Request

Detect a single tracking number:

        const data = {
  tracking_number: "1Z999AA10123456784",
};

const response = await fetch("https://api.packagex.io/v1/utils/providers/detect", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const result = response.data[0];

      

Or detect several at once (a split shipment with multiple tracking numbers) - pass an array, or a single comma-separated string:

        const data = {
  tracking_number: ["1Z999AA10123456784", "9400111899223456789012"],
  // equivalently: tracking_number: "1Z999AA10123456784,9400111899223456789012"
};

const response = await fetch("https://api.packagex.io/v1/utils/providers/detect", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

const results = response.data;

      

# Parameters

Requires the trackers:read scope.

# Response

data is an array of results, one per unique tracking number (duplicate inputs are collapsed, and the order is not guaranteed to match the input):

        {
  "message": "1 tracking number processed",
  "data": [
    {
      "object": "provider_detection",
      "result": "external",
      "tracking_number": "1Z999AA10123456784",
      "tracking_url": "https://www.ups.com/track?loc=en_US&tracknum=1Z999AA10123456784",
      "detection_method": "aftership",
      "candidates": [{ "id": "ups", "name": "UPS" }]
    }
  ],
  "status": 200
}

      

# Response fields

• object string - always "provider_detection".
• result string - a summary of the match: "external" (a single provider matched), "ambiguous" (more than one candidate matched), or "unknown" (no provider could be identified - the candidate is the placeholder other).
• tracking_number string - the normalized tracking number (trimmed, uppercased, whitespace removed).
• tracking_url string \| null - a link to the tracking page: the carrier's own page when a template exists, otherwise a universal tracking page. null only for an unknown (other) result - a recognized provider always yields a link (its own page when templated, otherwise the universal tracking page).
• detection_method string - opaque provenance for how the result was obtained: "cache" (served from a previous lookup) or a live-resolution marker (currently "aftership"). Treat this value as informational only - do not branch on the specific live-resolver name, which may change as the underlying detection provider evolves.
• candidates array - the matching providers, each { id, name }. candidates[0] is the best match. For an unknown result this is [{ "id": "other", "name": "Unknown Provider" }].

# Unknown and ambiguous numbers

If more than one provider matches a number, result is "ambiguous" and every match is listed in candidates so you can let the user choose.

If no provider can be identified, result is "unknown", candidates is [{ "id": "other", "name": "Unknown Provider" }], and tracking_url is null.

# Error scenarios

tracking_number is required, and the resolved list must contain 1 to 50 numbers of at most 63 characters each, none starting with PKGX-. A missing field, an empty value, an empty array, more than 50 numbers, an over-long number, or any PKGX- number is rejected with a 400:

        {
  "message": "PKGX tracking numbers are not supported.",
  "data": {},
  "status": 400
}