API Shipment Listing, Searching and Tracking

The following sections describe functionality useful when working with shipment requests through the YubiEnterprise API. For information on how to create shipment requests, see API Shipment Requests. See also the YubiEnterprise API Reference.

Listing Shipment Requests

GET /shipments_exact retrieves a list of all shipments. Because there is a 100-record limit on all API calls only the first 100 records are returned.

In cases where there are more than 100 shipments, iterate through the shipments based on the number of shipments provided by the total_count parameter.

Use the optional parameters to obtain more records. For example:

// get the first 100
/shipments_exact?limit=100&offset=0

// get the second 100
/shipments_exact?limit=100&offset=100

// get the third 100
/shipments_exact?limit=100&offset=200

For more information, see the YubiEnterprise API Reference.

Searching Shipments

You can get a list of shipments filtered by query parameters. The /shipments_exact/search-description route provides a description of the searchable fields on searchable resources.

For example: To look up a shipment using the parameter “Shipping error, contact support” state, set the search_field to shipment_state_id and set the ID to 99, which is the ID for that shipment state. For more shipment state codes, see Shipment Status Codes.

curl "https://api.console.yubico.com/v1/shipments_exact?search=99&search_field=shipment_state_id" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhb..."

The /shipments_exact/search-description route returns the type field as a filterable field. The /shipments_exact{id} route returns the shipment type (‘Automated’ or ‘Manual’) as part of the response. The field is sortable.

Advanced Search

To enable advanced search, add the query string parameter &advanced_search=true. The &search query parameters must follow the structure search=field_name::operation_type::value. An example search with curl --data-urlencode is used in the following example:

curl -H "$YED_AUTHORIZATION" -G --data-urlencode 'search=shipment_request_date::range::2020-05-10T00:00:00Z|2020-12-10T00:00:00Z' --data-urlencode 'search=organization_name::like::alpha comp' --data-urlencode 'search=organization_name::exact::demo_org' 'http://api.console.local/v1/shipments_exact?offset=0&limit=10&sort_by=shipment_request_date&sort_direction=DESC&advanced_search=true'

This is the encoded URL:

GET /v1/shipments_exact?offset=0&limit=10&sort_by=shipment_request_date&sort_direction=DESC&advanced_search=true&search=shipment_request_date%3A%3Arange%3A%3A2020-05-10T00%3A00%3A00Z%7C2020-12-10T00%3A00%3A00Z&search=organization_name%3A%3Alike%3A%3Aalpha%20comp&search=organization_name%3A%3Aexact%3A%3Ademo_org HTTP/1.1

Fields with different names will be searched in an “AND”, while fields with the same name will be searched using “OR”. The resulting query fragment will be the following:

WHERE (shipment_request_date BETWEEN ? AND ?) AND ((organizations.organization_name = ?) OR (organizations.organization_name LIKE ?)) ORDER BY shipment_request_date DESC LIMIT ?

The array to fill in the ? in the fragment will be the following:

[2020-05-10 00:00:00 +0000 UTC 2020-12-10 00:00:00 +0000 UTC demo_org %alpha comp% 10]

For more information, see the YubiEnterprise API Reference.

Tracking Shipments

A successful response from the shipments_exact resource will include a shipment_id which can be used to get the tracking information for this shipment request.

Example: Tracking

The following example describes how to track a shipment using the shipment_id.

{
   "shipment_id": "U89bvfKKCtQfhnqaFBrAZW",
   "shipment_items": [
      {
            "inventory_product_id": 15,
            "shipment_product_id": "MZ9bmEYFpKKviHe8nSiq4W",
            "shipment_id": "U89bvfKKCtQfhnqaFBrAZW",
            "product_id": 3,
            "product_name": "YubiKey 5C",
            "product_sku": "5060408461488",
            "product_tier": 2,
            "shipment_product_quantity": 16
      }
   ],
   "organization_id": "UEayb8v4LTHdAshpnk1gMd",
   "user_id": "WMktp3sgPSFt4zsgpLDF46",
   "country_code_2": "US",
   "is_delivered": false,
   "is_sent_to_fulfillment": false,
   "is_shipped": false,
   "recipient": "Example Inc.",
   "recipient_email": "jan.lindberg@example.com",
   "recipient_firstname": "Jan",
   "recipient_lastname": "Lindberg",
   "recipient_telephone": "555-5555",
   "street_line1": "7788 Foxrun Street",
   "city": "Dedham",
   "region": "MA",
   "postal_code": "02026",
   "delivery_type": 1,
   "shipment_state_code": "ShipmentStateAwaitingValidation",
   "shipment_state_id": 3,
   "shipment_state_message": "Awaiting Validation",
   "shipment_summary_description": "Total Keys: 16 yk5c:16",
   "shipment_request_date": "2020-12-10T19:56:57Z",
   "shipment_updated_date": "2020-12-10T19:56:57Z",
   "total_keys_shipped": 16
}

curl "https://api.console.yubico.com/v1/shipments_exact/U89bvfKKCtQfhnqaFBrAZW" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhb..." \

The response includes a tracking_number and a tracking_link for the shipment.

For more information, see the YubiEnterprise API Reference.

Deprecated APIs

The following table lists deprecated APIs related to listing, tracking, searching, and status for shipment requests. For more information, see Deprecated APIs: Overview.

Shipping Requests: Listing, Tracking, Searching, Status etc.

Deprecated	Replacement
`GET /shipments`	`GET /shipments_exact`
`POST /shipments`	`POST /shipments_exact`
`GET /shipments/{shipmentId}`	`GET /shipments_exact/{shipmentId}`
`PUT /shipments/{shipmentId}`	`PUT /shipments_exact/{shipmentId}`
`DELETE /shipments/{shipmentId}`	`DELETE /shipments_exact/{shipmentId}`
`/UpdateShipmentById`	`shipments_exact/{shipment_id}`
`/organization/update-setting`	None

To file a support ticket for YubiEnterprise Delivery, click Support.