# Get tracking link

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)

Endpoint: POST /shipments/track
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `searches` (array, required)
    Array of search queries. Results are returned in the same order as the input searches.
Maximum 100 searches per request.
    Example: [{"query":"MAWB123456"},{"query":"BOL789"}]

  - `searches.query` (string, required)
    Reference value to search for (minimum 4 characters)
    Example: "MAWB123456"

  - `referenceFields` (array)
    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.
    Enum: "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"

## Response 200 fields (application/json):

  - `results` (array, 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.
    Example: [{"query":"MAWB123456","id":"550e8400-e29b-41d4-a716-446655440000","key":"SHIP-001","friendlyId":"SHP-12345","status":"IN_TRANSIT","field":"MASTER_AIRWAYBILL_NUMBER","value":"MAWB123456","origin":"Los Angeles, CA 90210","destination":"New York, NY 10001","pickUpDate":"2025-01-15","deliveryDate":"2025-01-20","trackingUrl":"https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"},{"query":"NOTFOUND123","id":null,"key":null,"friendlyId":null,"status":null,"field":null,"value":null,"origin":null,"destination":null,"pickUpDate":null,"deliveryDate":null,"trackingUrl":null}]

  - `results.query` (string, required)
    Original search query (always present, even when no match found)
    Example: "MAWB123456"

  - `results.id` (string,null)
    Shipment UUID (null if not found)
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `results.key` (string,null)
    Client-defined key (null if not found or not set)
    Example: "SHIP-001"

  - `results.friendlyId` (string,null)
    Human-readable shipment ID (null if not found)
    Example: "SHP-12345"

  - `results.status` (any)
    Current shipment status (null if not found)
    Example: "IN_TRANSIT"

  - `results.field` (any)
    Reference field type that matched the query (null if not found)

  - `results.value` (string,null)
    The actual value stored in the matched reference field (null if not found)
    Example: "MAWB123456"

  - `results.origin` (string,null)
    Origin city, state/region, and zip code (null if not found).
Format: "City, ST" or "City, ST ZIP" if zip code is available.
    Example: "Los Angeles, CA 90210"

  - `results.destination` (string,null)
    Destination city, state/region, and zip code (null if not found).
Format: "City, ST" or "City, ST ZIP" if zip code is available.
    Example: "New York, NY 10001"

  - `results.pickUpDate` (string,null)
    Scheduled or actual pickup date in ISO 8601 date format (YYYY-MM-DD).
Null if not found or not set.
    Example: "2025-01-15"

  - `results.deliveryDate` (string,null)
    Scheduled or actual delivery date in ISO 8601 date format (YYYY-MM-DD).
Null if not found or not set.
    Example: "2025-01-20"

  - `results.trackingUrl` (string,null)
    Direct URL to view shipment details in MVMNT (null if not found).
Uses the organization's configured domain or defaults to app.mvmnt.io.
    Example: "https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message