Inferences

Shipping Label Inference

You can have the inference via the API or the vision-SDK while the vision-SDK will do the network request for you, the responses from this document will remain the same.

# New Inference

To create a new inference for shipping-labels, you'll need to pass the image_url as a base64 encoded data URL or public web URL. There's a soft cap of about 7.5MB per image for the base64 URL.

You're also able to specify what type of image the parser is looking at, so it can better extract data accurately along with other helpful information listed below:

image_url string (required)
Base64 encoded data URL.

barcode_values Array.<String>
Any existing values you've already extracted from the barcode.

location_id String
The ID of the location you want to attribute to this scan.

layout_id String
The ID of the layout to attribute to this scan. The layout must be associated with the specified location_id.

child_shipments Array.<String>
An array of shipment IDs to attach as child shipments to the parent shipment created from this inference. This enables the parent-child shipment hierarchy where a parent shipment (e.g., a pallet or consolidated box) contains multiple child shipments. Can also be an object with add, remove, or set arrays for updating an existing inference. Only applies when the tracker type is "outbound". Child shipments must be at the same location and have a status of created, delivered, or return_to_sender.

options Object
Option contains different other optional parameters you can provide along with the image. Those parameters are described below

        enum TrackingStatusOutstanding {
  provider_at_pickup
  package_accepted
  out_for_delivery
  provider_at_dropoff
  scheduled
  driver_dispatched
  package_at_waypoint
  in_transit
  pickup_available
  recipient_at_pickup
  added_to_container
  removed_from_container
  added_to_vehicle
  removed_from_vehicle
  delivered_to_provider
}

      

        enum TrackerCloseShipmentsOption {
  on_provider_updates
  on_all_updates
  off
}

      

        enum TrackerCloseShipmentsStatus {
  delivered
  picked_up
}

      

        const data = {
  image_url: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASA...", //truncated
  barcode_values: [], //If you have already extracted any barcode values from a shipping label
  location_id: null, //You an optionally pass the location ID to later filter scans by location
  layout_id: null, //You can optionally pass the layout ID. The layout must be associated with the specified location_id
  child_shipments: ["ship_abc123", "ship_def456"], //Optional array of child shipment IDs to attach to the parent shipment (outbound only)
  options: {
    tracker: {
      status: "pickup_available",
      create_automatically: false,
      type: "inbound",
      parcel: "always_create",
      chained_status: "in_transit",
      auto_close_shipments_option: "on_all_updates",
      auto_close_shipments_status: "picked_up",
      create_destination_shipment: false,
      destination_shipment_location_id: null,
    },
    postprocess: {
      parse_addresses: ["sender", "recipient"],
    },
    match: {
      location: false,
      search: ["recipient"],
    },
  },
};

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

const scan = response.data;

      

# Inbound Rerouting (Multi-Hop)

When inbound multi-hop rerouting is enabled at the organization or location level, the system can automatically detect when a package does not have a recipient match at the scanned location and attempt to find the correct recipient across all locations in the organization.

If a match is found at a different location, the inference response will include a destination_location object indicating where the package should be rerouted to.

If the system matches a recipient but cannot determine the destination location, the inference will include a destination_location_unknown error. You can resolve this by updating the inference with a destination_location_id:

        const data = {
  destination_location_id: "loc_..."  // Must be one of the matched recipient's associated locations
};

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

const scan = res.data;
// scan.destination_location => { id: "loc_..." }
// scan.errors => [] (destination_location_unknown resolved)

      

# Inference Exceptions

The Exceptions feature allows us to flag specific shipping label inferences that contain anomalies or irregularities detected during processing. When an inference is in exception state, it can not be transformed however it can be reviewd and resolved out of the exception state and then it can be transformed.

This capability is useful in scenarios where the OCR model successfully processes the label image but encounters issues that affect the quality or reliability of the extracted data. Examples include:

unknown_contact – Contact information cannot be reliably identified.

addressed_generically – The label is addressed to a generic title (e.g., "Customer" or "Resident").

damaged_label – The physical label appears partially destroyed or unreadable.

suspicious – The label contains patterns that may indicate fraud or tampering.

arrived_opened – The package is detected to have been opened prior to delivery.

We can update an existing inference record and set it to exception, along with appropriate exceptions type.

        const data = {
  exceptions: {
    unknown_contact: true,
    suspicious: true
  }
};

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

const scan = response.data;