Search References

Search shipments and orders matching an exact reference value at a given facility. Shipments match on id, reference id, BOL, PRO, any one of their POs or of their linked orders' POs, customer reference or a custom reference; orders on id, order number, name, PO, SO, customer reference or a custom reference. A custom reference is a custom field of any type of the facility owner that the caller may see: any one for the owner's own users, only those visible to carriers for anyone else. A text value matches as is, a number by its text; a true/false value never matches. matches names, per returned shipment and order, the field that matched. Shipment custom_data is whole for the owner's own users and holds only custom fields visible to carriers for anyone else. incomplete says whether matches may be missing because part of the search could not run.

SecurityAPIKeyHeader
Request
path Parameters
facility_id
required
string (Facility Id) = 26 characters
query Parameters
q
required
string (Q) [ 1 .. 255 ] characters ^\s*\S

Exact value (case-sensitive, whole value) to match against shipment and order reference fields

Responses
200

Successful Response

Response Schema: application/json
required
Array of objects (Shipments)
required
Array of objects (Orders)
object (Matches)

Per returned shipment id and order id, the field that matched q. Every returned shipment and order has an entry.

object (Shipment Appointments)

Per matched shipment id, its appointments at the searched facility. Every matched shipment has an entry; an empty list means it has no appointment here.

incomplete
boolean (Incomplete)
Default: false

True when matches may be missing because part of the search could not run: the shipment PO / customer-reference lookup or the shipment custom-reference lookup failed or timed out, or the facility owner's custom field definitions could not be loaded (so results matched only by a custom field were dropped and, for a caller outside the facility owner's company, all custom data was withheld), or a matching shipment could not be read, or a lookup returned its maximum number of results, so more matches may exist. Everything returned is still an exact match. False when every lookup answered in full and every result was read; an empty result with incomplete false means nothing matched.

400

Validation Error

get/facilities/{facility_id}/references/search
Request samples
Response samples
application/json
{
  • "shipments": [
    ],
  • "orders": [
    ],
  • "matches": {
    },
  • "shipment_appointments": {
    },
  • "incomplete": false
}
Copyright © Shipwell 2025. All right reserved.