--- title: "Get tracking link" method: POST path: "/shipments/track" tags: ["Shipments"] --- # Get tracking link `POST /shipments/track` Search for shipments by reference field values (BOL #, PRO #, MAWB #, etc.) and return tracking information. ## Usage 1. Provide an array of search queries in the `searches` field 2. Optionally filter which reference field types to search using `referenceFields` 3. Results are returned in the same order as input searches 4. If no match is found, the result contains only the original `query` (other fields are null) ## Matching Behavior - Searches are case-insensitive - If multiple shipments match a query, the most recently created shipment is returned - If `referenceFields` is omitted, all reference field types are searched ## Example Use Cases - **Customer portal**: Look up shipment status by BOL or PRO number - **EDI integration**: Validate shipment references before sending updates - **Bulk status check**: Query multiple shipments in a single request ## Rate Limits - Maximum 100 searches per request - Standard API rate limits apply (see Rate Limiting documentation) ## Request body - ShipmentTrackRequest - `searches` ShipmentTrackSearch[], required — Array of search queries. Results are returned in the same order as the input searches. Maximum 100 searches per request. - `query` string, required — Reference value to search for (minimum 4 characters) - `referenceFields` ShipmentReferenceField[] — Optional filter for reference field types to search. If omitted, searches all reference field types. Common use: limit search to specific field types for faster results or to avoid false matches across different reference types. ## Response `200` Track results returned successfully - ShipmentTrackResponse - `results` ShipmentTrackResult[], required — Array of tracking results in the same order as input searches. Each result contains the original query plus matching shipment data. If no match is found, only the `query` field is populated (all other fields are null). If multiple shipments match a query, the most recently created shipment is returned. - `query` string, required — Original search query (always present, even when no match found) - `id` string, uuid, nullable — Shipment UUID (null if not found) - `key` string, nullable — Client-defined key (null if not found or not set) - `friendlyId` string, nullable — Human-readable shipment ID (null if not found) - `status` 'DRAFT' | 'TENDER_PENDING' | 'ON_HOLD' | 'PLANNING' | 'SELECTED' | 'BOOKED' | 'DISPATCHED' | 'LOADING' | 'PICKED_UP' | 'IN_TRANSIT' | 'UNLOADING' | 'ARRIVED_AT_DELIVERY_TERMINAL' | 'OUT_FOR_DELIVERY' | 'RECOVERED' | 'DELIVERED' | 'CANCELED' | 'TENDER_REJECTED' — Current status of the shipment. Lifecycle stages: - `DRAFT`: Shipment is being created, not yet ready for processing - `TENDER_PENDING`: Awaiting carrier tender acceptance - `TENDER_REJECTED`: Carrier rejected the tender - `ON_HOLD`: Shipment is temporarily paused - `PLANNING`: Shipment is being planned/scheduled - `SELECTED`: Carrier has been selected - `BOOKED`: Carrier has confirmed the booking - `DISPATCHED`: Shipment has been dispatched to carrier In-transit stages: - `LOADING`: Freight is being loaded at pickup - `PICKED_UP`: Freight has been picked up - `IN_TRANSIT`: Shipment is in transit - `UNLOADING`: Freight is being unloaded at delivery - `ARRIVED_AT_DELIVERY_TERMINAL`: Arrived at delivery terminal (LTL) - `OUT_FOR_DELIVERY`: Out for final delivery - `RECOVERED`: Shipment has been recovered Final stages: - `DELIVERED`: Shipment has been delivered - `CANCELED`: Shipment has been canceled - `field` 'BOL_NUMBER' | 'PICKUP_NUMBER' | 'DELIVERY_NUMBER' | 'PURCHASE_ORDER_NUMBER' | 'GENERAL_LEDGER_CODE' | 'CUSTOMER_REFERENCE_NUMBER' | 'PRO_NUMBER' | 'ITEM_IDENTIFICATION' | 'PART_NUMBER' | 'ACCOUNT_NUMBER' | 'CONSIGNEE_ACCOUNT_NUMBER' | 'PICKUP_LOCATION_IDENTIFICATION' | 'DELIVER_LOCATION_IDENTIFICATION' | 'PRODUCT_IDENTIFICATION' | 'OTHER_IDENTIFICATION' | 'CONTAINER_NUMBER' | 'MACROPOINT_REFERENCE_NUMBER' | 'DROP_TRAILER_NUMBER' | 'APPOINTMENT_NUMBER' | 'MASTER_BILL_OF_LADING_NUMBER' | 'HOUSE_BILL_OF_LADING_NUMBER' | 'LOCATION_IDENTIFICATION' | 'TENDER_METHOD' | 'ROUTE_NUMBER' | 'SHOW_DECORATOR_NAME' | 'SHOW_BOOTH_NUMBER' | 'CARE_OF' | 'TENDER_ID' | 'ORDER_NUMBER' | 'SHOW_NAME' | 'AES_ITN' | 'FIRMS_CODE' | 'IT_NUMBER' | 'JOB_NUMBER' | 'TMS_ID' | 'MASTER_AIRWAYBILL_NUMBER' | 'HOUSE_AIRWAYBILL_NUMBER' | 'AMS_HOUSE_BILL_OF_LADING_NUMBER' — Reference field types for shipment tracking. Common field types: - `BOL_NUMBER`: Bill of Lading Number - `PRO_NUMBER`: PRO Number (carrier tracking number) - `PURCHASE_ORDER_NUMBER`: Purchase Order Number - `CUSTOMER_REFERENCE_NUMBER`: Customer Reference Number - `CONTAINER_NUMBER`: Container Number - `MASTER_BILL_OF_LADING_NUMBER`: Master Bill of Lading Number - `HOUSE_BILL_OF_LADING_NUMBER`: House Bill of Lading Number - `MASTER_AIRWAYBILL_NUMBER`: Master Airway Bill Number - `HOUSE_AIRWAYBILL_NUMBER`: House Airway Bill Number Additional field types: - `PICKUP_NUMBER`: Pickup Number - `DELIVERY_NUMBER`: Delivery Number - `GENERAL_LEDGER_CODE`: GL Code - `ITEM_IDENTIFICATION`: Item ID - `PART_NUMBER`: Part Number - `ACCOUNT_NUMBER`: Account Number - `CONSIGNEE_ACCOUNT_NUMBER`: Consignee Account Number - `PICKUP_LOCATION_IDENTIFICATION`: Pickup Location ID - `DELIVER_LOCATION_IDENTIFICATION`: Delivery Location ID - `PRODUCT_IDENTIFICATION`: Product ID - `OTHER_IDENTIFICATION`: Other ID - `MACROPOINT_REFERENCE_NUMBER`: MacroPoint Reference Number - `DROP_TRAILER_NUMBER`: Drop Trailer Number - `APPOINTMENT_NUMBER`: Appointment Number - `LOCATION_IDENTIFICATION`: Location ID - `TENDER_METHOD`: Tender Method - `ROUTE_NUMBER`: Route Number - `SHOW_DECORATOR_NAME`: Show Decorator Name - `SHOW_BOOTH_NUMBER`: Show Booth Number - `CARE_OF`: Care Of - `TENDER_ID`: EDI Tender ID - `ORDER_NUMBER`: Order Number - `SHOW_NAME`: Show Name - `AES_ITN`: AES ITN (Automated Export System Internal Transaction Number) - `FIRMS_CODE`: FIRMS Code (Facility Information and Resources Management System) - `IT_NUMBER`: IT Number (Immediate Transportation) - `JOB_NUMBER`: Job Number - `TMS_ID`: TMS ID - `AMS_HOUSE_BILL_OF_LADING_NUMBER`: AMS House Bill of Lading Number - `value` string, nullable — The actual value stored in the matched reference field (null if not found) - `origin` string, nullable — Origin city, state/region, and zip code (null if not found). Format: "City, ST" or "City, ST ZIP" if zip code is available. - `destination` string, nullable — Destination city, state/region, and zip code (null if not found). Format: "City, ST" or "City, ST ZIP" if zip code is available. - `pickUpDate` string, date, nullable — Scheduled or actual pickup date in ISO 8601 date format (YYYY-MM-DD). Null if not found or not set. - `deliveryDate` string, date, nullable — Scheduled or actual delivery date in ISO 8601 date format (YYYY-MM-DD). Null if not found or not set. - `trackingUrl` string, uri, nullable — Direct URL to view shipment details in MVMNT (null if not found). Uses the organization's configured domain or defaults to app.mvmnt.io. ## Other responses - `400` — Bad request - invalid input - `401` — Unauthorized - invalid or missing access token - `422` — Validation error - invalid field values - `429` — Rate limit exceeded --- [API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/53b310bb74a0/schema)