Using the API to Execute a Shipping Request

The information in Requesting Shipment applies to this method.

Channel Partners

To order keys via API from inventory purchased through channel partners, the new /shipments_exact APIs must be used. The older, deprecated /shipments API only supports ordering keys from inventory purchased directly from Yubico.

The following APIs are a) deprecated and b) do not support channel partners.

  • GET /shipments
  • POST /shipments
  • GET /shipments/{shipmentId}
  • PUT /shipments/{shipmentId}
  • DELETE /shipments/{shipmentId}

To manage shipment orders that utilize inventory purchased through channel partners, use the corresponding shipments_exact APIs:

  • GET /shipments_exact
  • POST /shipments_exact
  • GET /shipments_exact/{shipmentId}
  • PUT /shipments_exact/{shipmentId}
  • DELETE /shipments_exact/{shipmentId}

The following APIs related to bulk shipments have been updated to handle channel partners:

  • POST /shipments/bulk
  • GET /shipments/bulk
  • POST /shipments/bulkvalidate
  • POST /shipments/bulkdelete - For the sake of completeness, this is included in the list, but it has not changed.

The GET /shipments/csv API will also be updated to support channel partners.

Single Orders

To order keys via API from inventory purchased through channel partners, the new /shipments_exact APIs must be used. The GET /shipments_exact, POST /shipments_exact, GET /shipments_exact/{shipmentId}, and PUT /shipments_exact APIs have all been modified to handle channel partners. The corresponding (and deprecated) /shipments APIs have not been modified and can only handle direct sales orders.

Bulk Orders

Bulk orders using the API are still handled through the GET /shipments/bulk, POST /shipments/bulk, POST /shipments/bulkvalidate, and POST /shipments/bulkdelete APIs. The API parameters and request body themselves did not change to work with channel partners. Instead, it is the content of the .csv file that is used in the upload that has been changed to include the new channel_partner_ID field. The channel partner ID is a non-zero integer shown as a field on the purchase order table and on the purchase order details page.

Note

To ensure you are using the latest .csv file format, make a practice of downloading the template file anew each time before uploading a new set of orders.

Verifying Products to be Shipped

Verify that all the products you intend to ship are currently available in inventory.

  • /shippablekeys returns all products associated with your organization’s account, including any products that have a current available inventory of 0.
  • When inventory_type is 1, products that have zero inventory are not listed. The quantities of the products available are shown next to the names of the products. Therefore, even if a product is shown on a PO, if its inventory is exhausted by the time you want to request it be shipped, this API will not return it.

Shipping Products to a Single Address

This method uses a suite of /shipments_exact APIs made available to enable more granularity in specifying the stock (inventory) from which the products are drawn. The original /shipments APIs are deprecated starting in the 1.6.0 release but they will continue to be available until at least May 2021. Use the /shipments_exact APIs for any new development and to update existing clients.

Specifying the stock/inventory to be used for single shipment requests thus provides a much larger range of options than the options available for bulk shipments. For these, see Shipping Products to Multiple Addresses.

Inventory Product ID and Product ID

Both of these values need to be supplied, product_id and inventory_product_id. The product_id is the unique identifier for the product, e.g., 4 is the YubiKey 5C Nano, while the inventory_product_id can be thought of as the ID for a “bucket” containing credits that your organization bought to cover the purchase of keys, lanyards, etc. Typically organizations with subscriptions have multiple “buckets”, while organizations that have bought physical keys outright might have only a single “bucket.”

Use the inventory_product_id to specify which inventory you are pulling from. The inventories correspond exactly to:

  • The inventories shown on the YubiEnterprise Console Dashboard and
  • The options in the Choose from stock dropdown on the Single shipment tab accessed by clicking Create Shipment Request on the Shipments screen.

The table below lists both product_id and inventory_product_id in the same column, and contains all inventories and products except custom products. To get the complete list of products and inventories available to your organization, make a call to GET /inventory. If you have custom products, that will return a list that also contains your custom products.

Product Name, Stock/Inventory, product_id, and inventory_product_id
inventory _product_id product_id product_name
1 YubiKey 5 NFC
2 YubiKey 5 Nano
3 YubiKey 5C
4 YubiKey 5C Nano
5 YubiKey 5Ci
7 Security Key NFC by Yubico
8 YubiKey FIPS
9 YubiKey Nano FIPS
10 YubiKey C FIPS
11 YubiKey C Nano FIPS
12 Primary Subscr - Base Tier: Initial
13 Primary Subscr - Base Tier: Buffer
14 Primary Subscr - Base Tier: Replacement
15 Primary Subscr - Adv. Tier: Initial
16 Primary Subscr - Adv. Tier: Buffer
17 Primary Subscr - Adv. Tier: Replacement
18 Primary Subscr - Prem. Tier: Initial
19 Primary Subscr - Prem. Tier: Buffer
20 Primary Subscr - Prem. Tier: Replacement
21 Primary Subscr - FIPS Tier: Initial
22 Primary Subscr - FIPS Tier: Buffer
23 Primary Subscr - FIPS Tier: Replacement
24 Non-subscription - Base Tier
25 Non-subscription - Advanced Tier
26 Non-subscription - Premium Tier
27 Non-subscription - FIPS Tier
28 YubiKey Lanyard
29 YubiKey 5C NFC
38 Backup Subscr - Base Tier: Initial
39 Backup Subscr - Base Tier: Buffer
40 Backup Subscr - Base Tier: Replacement
41 Backup Subscr - Adv. Tier: Initial
42 Backup Subscr - Adv. Tier: Buffer
43 Backup Subscr - Adv. Tier: Replacement
44 Backup Subscr - Prem. Tier: Initial
45 Backup Subscr - Prem. Tier: Buffer
46 Backup Subscr - Prem. Tier: Replacement
47 Backup Subscr - FIPS Tier: Initial
48 Backup Subscr - FIPS Tier: Buffer
49 Backup Subscr - FIPS Tier: Replacement
54 YubiKey 5 NFC FIPS
55 YubiKey 5C NFC FIPS
56 YubiKey 5Ci FIPS
57 YubiKey 5 Nano FIPS
58 YubiKey 5C FIPS
59 YubiKey 5C Nano FIPS

The inventory_product_id can have the same value as the product_id field in the individual inventory_records.

Example 1: Without Subscription

For example, if you do not have a subscription and simply bought outright a number of YubiKey 5C Nanos (no virtual keys, no tiers), your request for a single shipment would look like this:

{
   "delivery_type": 1,
   "country_code_2": "US",
   "recipient": "string",
   "recipient_email": "string",
   "recipient_firstname": "string",
   "recipient_lastname": "string",
   "recipient_telephone": "string",
   "street_line1": "string",
   "street_line2": "string",
   "street_line3": "string",
   "city": "string",
   "region": "string",
   "postal_code": "string",
   "shipment_items": [
      {
         "product_id": 4,
         "inventory_product_id": 4,
         "shipment_product_quantity": 1
      }
   ]
}

Example 2: With Subscription

With a subscription, your product_id value and your inventory_product_id value would not coincide, and your individual shipment request would look like this:

{
   "delivery_type": 1,
   "country_code_2": "US",
   "recipient": "string",
   "recipient_email": "string",
   "recipient_firstname": "string",
   "recipient_lastname": "string",
   "recipient_telephone": "string",
   "street_line1": "string",
   "street_line2": "string",
   "street_line3": "string",
   "city": "string",
   "region": "string",
   "postal_code": "string",
   "shipment_items": [
      {
         "product_id": 4,
         "inventory_product_id": 15,
         "shipment_product_quantity": 1
      }
   ]
}

Mapping

Use the product_id to map to the inventory_product_id of the shipments_exact request as shown in the /inventory example output below.

Custom-programmed YubiKeys

If your organization has custom-programmed YubiKeys, to make a shipment request, use the /inventory /products APIs to get the inventory_product_id and product_id. Using standard product_id codes in shipment requests will result in errors.

/inventory Example Output

{
   "count": 3,
   "total_count": 3,
   "organization_product_inventory": [
   {
      "organization_product_inventory_id": "Cym9ypJsmVEshX9qzSQc7S",
      "is_subscription_product": true,
      "is_virtual_product": true,
      "organization_id": "UEayb8v4LTHdAshpnk1gMd",
      "organization_product_quantity": 978,
      "product_id": 15,
      "inventory_type": 3,
      "product_name": "Primary Subscr - Adv. Tier: Initial",
      "product_tier": 2
      ,"product_mapping": [
         1,
         2,
         3,
         4,
         6,
         7]
   },
   {
      "organization_product_inventory_id": "Ky8VzJWpftEk2hiMsJDjVW",
      "is_subscription_product": true,
      "is_virtual_product": true,
      "organization_id": "UEayb8v4LTHdAshpnk1gMd",
      "organization_product_quantity": 10,
      "product_id": 44,
      "inventory_type": 3,
      "product_name": "Backup Subscr - Prem. Tier: Initial",
      "product_tier": 3,
      "product_mapping": [
         1,
         2,
         3,
         4,
         5,
         6,
         7]
   },
   {
      "organization_product_inventory_id": "UPjT3FU8oqCoHPCr9mNUzD",
      "is_subscription_product": true,
      "is_virtual_product": true,
      "organization_id": "UEayb8v4LTHdAshpnk1gMd",
      "organization_product_quantity": 964,
      "product_id": 18,
      "inventory_type": 3,
      "product_name": "Primary Subscr - Prem. Tier: Initial",
      "product_tier": 3,
      "product_mapping": [
         1,
         2,
         3,
         4,
         5,
         6,
         7]
      }
   ]
}

ShipmentDeliveryTypeEnum

ShipmentDeliveryTypeEnum specifies the method of shipping:

  • 1 - Normal (standard) shipping (default)
  • 2 - Expedited (rush) shipping.

Recipient Field

The recipient field requires the name of the recipient’s company (if applicable) in the shipment address. Do not use the /shipments recipient field to specify the name of the individual to whom products are to be shipped. Use the recipient_firstname and recipient_last name fields instead.

Shipment Request Fields

In the table below, all fields not marked as mandatory are optional. The Limit column displays the maximum number of alphanumeric characters permitted per field/table cell.

Shipment Request Fields
Console: Field Label
CSV: Column Heading
API
Description Limit
Country code
country_code_2
Mandatory. Country code from available_countries.csv 2
Company recipient Mandatory if name of recipient is not provided 20
First name
recipient_firstname
Name of recipient. Mandatory if company name not given 15
Last name
recipient_lastname
Recipient’s family name. Mandatory if company name not given 20
Address 1
street_line1
Mandatory. First line of address 60
Address 2
street_line2
Mandatory if address not deliverable without (e.g. suite #) 60
Address 3
street_line3
Not supported for expedited/rush orders 60
City Mandatory. City, town, or township 60
Region/State
Mandatory for US and Canada, and also mandatory if
address is not deliverable without. (See footnote A)
Abbreviations OR full names
50
Postcode
postal_code
Zipcode or postal code 50
RecipientEmail
recipient_email
Email address of recipient 40
RecipientTelephone
recipient_telephone
Telephone number of recipient 40
DeliveryType
delivery_type
Type of shipping, Normal (1) or Expedited (2).
Integers (mandatory for API) OR words
InventoryType Mandatory. See Step 4 in procedure below.
ChannelPartnerId
channel_partner_ID
Mandatory. If inventory was purchased directly from
Yubico, enter “1”; otherwise enter the ChannelPartnerID
shown on the PO, as described in Channel Partners
3
Security Key NFC by Yubico Number of keys to be shipped 3
Yubikey 5 NFC Number of keys to be shipped 3
YubiKey 5 Nano Number of keys to be shipped 3
YubiKey 5C Number of keys to be shipped 3
YubiKey 5C Nano Number of keys to be shipped 3
YubiKey 5Ci Number of keys to be shipped 3
YubiKey 5 Bio Number of keys to be shipped 3
YubiKey 5C Bio Number of keys to be shipped 3
YubiKey Lite Bio Number of keys to be shipped 3
YubiKey Lite C Bio Number of keys to be shipped 3
YubiKey FIPS Number of keys to be shipped 3
YubiKey Nano FIPS Number of keys to be shipped 3
YubiKey C FIPS Number of keys to be shipped 3
YubiKey C Nano FIPS Number of keys to be shipped 3

Footnote A: To find out if an address is deliverable, make a shipment request and see what status code or message it gets. Deliverability is determined by our shipping partners, and it is their codes and messages we display when it comes to questions of deliverability. For a fuller explanation, see Troubleshooting.

Single Shipment Example Input

The following Curl example sends an HTTP POST to the shipments_exact resource URI to ship a YubiKey 5 NFC to a fictional employee, Jan Lindberg:

curl "https://api.console.yubico.com/v1/shipments_exact" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhb..." \
--data '{
{
    "delivery_type": 1,
    "country_code_2": "US",
    "recipient": "Example Inc.",
    "recipient_email": "jan.lindberg@example.com",
    "recipient_firstname": "Jan",
    "recipient_lastname": "Lindberg",
    "recipient_telephone": "555-5555",
    "street_line1": "7788 Foxrun Street",
    "street_line2": "",
    "street_line3": "",
    "city": "Dedham",
    "region": "MA",
    "postal_code": "02026",
    "shipment_items": [
        {"product_id": 3,
        "inventory_product_id": 15,
        "shipment_product_quantity": 16}
    ]
}'

In the example above, you will notice the delivery_type is set to 1 which means it is a normal shipment. A value of 2 would request an expedited shipment. The recipient_email gives the address at which the recipient will receive an email with the tracking number of the shipment.

Single Shipment Example Output

{
    "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
}

Shipping Products to Multiple Addresses

The system chooses the stock (inventory) from which products are drawn. (Bulk shipment ordering will convert to the exact choice method used in shipping products to a single address in a future release).

inventory_type and InventoryTypeEnum

The inventory_type requires one of the values given in the InventoryTypeEnum table below.

InventoryTypeEnum

Integer inventory_type (Stock) Purchase Mode
1 YubiKey Shipment Outright purchase
2 YubiKey Tier SKU Shipment Purchase of virtual keys
3 Subscription - Initial Shipment Subscription
4 Subscription - Buffer Stock Shipment Subscription
5 Subscription - Replacement YubiKey Shipment Subscription
  • If you have purchased keys on the perpetual mode and/or lanyards, use Inventory Type 1.
  • If you are not a subscription customer, but have purchased one or more tiers of virtual keys instead of physical keys, use Inventory Type 2, YubiKey Tier SKU Shipment.
  • Subscription customers: Use Inventory Types 3, 4, and 5.

Tier Sub-categories

Initial
The stock in this category reflects the
total number of users on the subscription. This
lot can be drawn upon for 12 months from the
start of your subscription term.
Buffer
This category is made available to you free of
charge when your subscription begins. You can
draw on it throughout the term of your
subscription.
Replacement
This category is intended for those who have
lost their YubiKeys or want to upgrade. The
stock in this category is reset each year of
the subscription to the Replacement limit.
  • Use up all of your Inventory Type 3, Initial, within the first year of your subscription.
  • Use Inventory Type 4 at any time: Buffer stock expires only at the end of your subscription term.
  • Use Inventory Type 5, Replacement, for users who have lost their keys or want to upgrade. Any keys not used in a given year are forfeited at the end of that year.

Example

The following example of a Bash script calls Curl to upload a CSV file with multiple shipment requests. To scroll horizontally, click in the code box below.

#!/bin/bash

token="apitokengoeshere"

curl -F "file=@/path/to/file/bulk_shipment.csv" https://api.console.yubico.com/v1/shipments/bulkvalidate \
--header "x-authorization: Bearer ${token}"

For instructions on creating and populating the CSV file, see Shipping to Multiple Addresses.

Validating CSV Uploads

lines-in-file
Lines in the file, including header.
lines_read
Lines that were able to be read in as
CSV, excluding the header. lines_read
should thus be one less than lines_in_file
lines_parsable
Lines that passed basic validation.
lines_parsable + lines_not_parsable =
lines_read.

Example: If a file that is not in the CSV format is uploaded, even if it had 100 lines, 0 lines would be read, because the CSV reader function cannot read the lines in as CSV.

Example: If a file has too many columns - i.e., more columns than the header row has - 0 lines would be read.

Sample Error Messages

  • Error with GetCountryByTwoLetterCode for CountryCode2: TT
  • InventoryType not set for Shipment, defaulting to 1
  • DeliveryType not set for Shipment, defaulting to 1 - normal
  • Wrong number of fields

Tracking Shipment Requests

Single Shipment Request Tracking Example

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.

{
   "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
}

Tracking a Shipment Using the shipment_id

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

Deprecated APIs

Deprecated APIs and their Replacements
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}

Filtering and Pagination

Refer to the API docs for the GetShipmentsExact operation .

Status

Shipment Status Codes

At any of the states between 1 and 9, a shipment request can be edited. From this point on, a shipment request is either processed through to an end state, or set back to state 99.

For information on how address validation affects the success of a shipping request, see the Troubleshooting chapter.

This table is very wide; scroll horizontally to see all four columns.

Shipment State Codes
shipment_state_id shipment_state_code shipment_state_description shipment_state_message
1 ShipmentStateIncomplete
Shipment request received
by YubiEnterprise Delivery
system but contained some
data that could not be
processed. (2), (3)
Incomplete Shipping Request
2 ShipmentStateDraft
Shipment request is being
edited and is not ready for
processing.
Draft
3 ShipmentStateAwaitingValidation
Shipment request received,
no validation done yet.
Awaiting Validation
4 ShipmentStateProcessingAddress
Shipment request locked as
it undergoes country check,
address validation, sales
tax rate lookup (US), DPL
check.
Processing
5 ShipmentStateAddressValid
Shipment request address has
been validated, ready to be
picked up by fulfillment
processor.
Accepted for Fulfillment
6 ShipmentStateAddressInvalid
Shipment request address is
invalid but an alternative
address has been found and
suggested. (2), (3)
Incomplete
7 ShipmentStateAddressFail
Shipment request address
could not be validated and
no alternative could be
found for suggesting.
(2), (3)
Address is undeliverable
or could not be
understood
8 ShipmentStateError
Shipment request has failed
processing due to
insufficient credits
or insufficient inventory.
Error: Processing Error,
contact Support
9 ShipmentStateDPLMatch
Shipment request recipient
found on DPL, therefore it
is illegal to fulfill this
shipment request. (4)
Error: DPL Match
99 ShipmentStateShipmentError
Shipment request rejected
from ShipmentState-
ProcessingFulfillment
with “%s” error message;
could not be fulfilled by
processor.
Error: Shipping error,
contact Support
100 ShipmentStateProcessingShipment
Shipment request was locked
at 1600hrs UTC to calculate
and deduct tax, inventory,
and credits. (1)
Processing: Inventory &
Tax Deductions
101 ShipmentStateFulfillmentReady
Shipment request ready to be
queued for fulfillment.
Processing: Ready for
Fulfillment
102 ShipmentStateProcessingFulfillment
Shipment sent for fulfill-
ment at 10:00am (or cutoff
time). (1)
Processing: Sent for
Fulfillment
103 ShipmentStateShipped
Shipment sent out by
fulfillment processor and is
in transit.
Shipped: In transit
104 ShipmentStateDelivered Shipment delivered. Delivered
105 ShipmentStateLost
Shipment lost and delivery
is no longer expected.
Shipment Lost/Missing
106 ShipmentStateDeliveryException
Customs hold or undelivered
or returned shipment to
sender or any other shipping
exceptions.
Delivery Exception
1025 ShipmentStateShippingQueue
Shipment queued for
fulfillment.
Processing:
Queued for Fulfillment
2000 ShipmentStateManualFulfillment
Shipment is being fulfilled
manually. No further action
by shipment requestor is
required.
Manual Processing

(1) Refer to Timing for cutoff times.

(2) Incomplete Address: Secondary line information such as apartment (apt), suite, unit is missing. Therefore it is not possible to guarantee delivery to the correct recipient.

(3) Address is Undeliverable or could not be understood: The address is either not physically deliverable or it could not be resolved to a real location.

(4) Any shipping request with a recipient name and/or address found on the US government’s DPL (Denied Parties/Persons List) cannot be fulfilled.

Shipment Status Messages

Scroll horizontally to see the entire width of the table.

As the following table is wide, you may need to scroll horizontally. In the Explanation column, the source of the message is given: YubiEnterprise Delivery system for internal messages, US Validation for the US Postal Service, and finally, International Validation. Messages originating from the last two are simply passed on to you by YubiEnterprise Delivery.

YubiEnterprise Delivery API /shipment_exact Status Messages
Message Explanation
InventoryProductId not specified for ProductId %d - ShipmentStateError
YubiEnterprise Delivery system
Too many keys in shipment - TotalKeysShipped %d > %d - ShipmentStateError
YubiEnterprise Delivery system
Not enough Inventory for Shipment - ShipmentStateError
YubiEnterprise Delivery system
Re-enter the address differently; some parts of it are invalid. See
the YubiEnterprise documentation for more guidance.
US Validation
The address is invalid. See the YubiEnterprise documentation for more
guidance.
US Validation
The address is valid.
No further explanation required
US Validation
Remove the ‘secondary unit designator’ (apt, suite, department, etc.)
because it is superfluous.
Remove the apartment number, unit, etc.:
it is considered wrong or unnecessary
US Validation
Enter second line information (apartment, unit, etc.).
The information in the primary line is not specific enough.
Add the apartment number, unit, etc.
US Validation
The address is a valid military address.
No further explanation required
US Validation
The address is a valid General Delivery address where individuals without
permanent addresses can receive mail.
No further explanation required
US Validation
The address is valid. An organization such as a government agency can
can have its own zipcode because it receives a large volume of mail.
No further explanation required
US Validation
Enter a street number; for example, for Yubico ‘Lytton Ave’ alone is not
sufficient, it needs to be ‘530 Lytton Ave’.
The number on the primary line, e.g., the
“185” in “185 Berry Street” is missing
Enter a valid street number.
The number on the primary line, e.g., the
“185” in “185 Berry Street” is not valid
US Validation
Enter a PO Box, Rural Route, or Highway Contract box number.
US Validation
Enter a valid PO Box, Rural Route, or Highway Contract box number.
US Validation
Enter the Private Mailbox (PMB) identifier or the # sign, followed by the
PMB number.
PMB number is Private Mailbox Number
US Validation
This address is not eligible to receive mail.
US Validation
The address is that of a Commercial Mail Receiving Agency (CMRA) a private
business that accepts mail for recipients, and the required private
mailbox information is present.
US Validation
The address is missing some important secondary line information
(apartment, unit, etc).
No further explanation required
International Validation
Mail is unlikely to arrive at this destination - please verify input.
No further explanation required
International Validation
This street could not be found within the city or postal code.
No further explanation required
International Validation
Invalid OrganizationId for Shipment YubiEnterprise Delivery system
Country Code not set for Shipment YubiEnterprise Delivery system
Country could not be found from CountryCode2: %s
Country code entered is not in
YubiEnterprise Delivery system list
Shipment has no shipment items YubiEnterprise Delivery system
DeliveryType not set for Shipment, defaulting to 1 - normal YubiEnterprise Delivery system
Invalid DeliveryType %s for Shipment YubiEnterprise Delivery system
InventoryType not set for Shipment, defaulting to 1 YubiEnterprise Delivery system
InventoryType %s not valid set for Shipment
You cannot use this InventoryType for this
shipment - YubiEnterprise Delivery system
Negative quantity entered for ShipmentItem with ProductId=%d defaulting to 0
You set the quantity of the specified
ProductID to be shipped to less than zero.
YubiEnterprise Delivery system
Invalid ShipmentProductQuantity for ShipmentItem %d
You probably do not have sufficient
inventory - YubiEnterprise Delivery system
Invalid ShipmentProductLineCost for ShipmentItem %d YubiEnterprise Delivery system
Invalid Shipment - Total keys in shipment greater than 500
You cannot ship more than 500 items at
once - YubiEnterprise Delivery system
Shipment has zero total item quantity
The number of items to be shipped must be
> than 0 - YubiEnterprise Delivery system
US Address is missing the state name/abbreviation in region field
No further explanation required
YubiEnterprise Delivery system
Bad ProductId in ShipmentProduct for NewShipmentProduct
ProductID is wrongly specified or invalid
YubiEnterprise Delivery system
Input for %s exceeded limit of %d characters
Specified field cannot accept the number
of characters that were entered.
YubiEnterprise Delivery system

Response Request Status Codes

The responses to your requests indicate what is happening on the server side. Below are the common status codes in responses from the YubiEnterprise Delivery API, and what they mean.

Status Codes
Code Meaning Explanation
200 OK
The request was successful and the response
body contains the representation requested
302 FOUND
A common redirect response; this will
redirect to the OAUTH login page
400 BAD REQUEST API validation failed for the request
403 FORBIDDEN
API denied permission to fulfill the
requested resource
404 NOT FOUND The requested resource was not found

Dates and Times

All dates and times in requests from the API are UTC in the RFC-3339 format.

Users, Roles, and Organizations

Since API tokens are scoped to organizations, if an organization is shipping YubiKeys to both United States/Canada and to Europe, two API tokens are required: one for the US/CAN organization and one for the European organization.

An individual user can have one role in one organization and the same or a different role in another organization; for example, user Jan could be an owner in a company’s US/CAN organization and an Admin in the same company’s EU organization. However, because these are separate organizations, if Jan is logged in to the US/CAN YubiEnterprise, Jan cannot use that login to perform operations in the company’s EU YubiEnterprise.

Because it is possible to change the role of a user already in an organization, it is worth noting that deleting a user both:

  • Deletes that user’s association with the organization, and
  • Removes from that user the permissions associated with their role.

It is therefore possible in theory (though undesirable) for a user to be a member of an organization without having a role.

Best Practices

The following best practices are specific to API use; others are in Best Practices & Troubleshooting.

Control Access to your Accounts

  • Protect access to the API token, because whoever is in possession of the token is authorized to perform API operations for your organization.
  • For calling the REST API, we recommend creating a sub-account and scoping it to the YubiEnterprise Admin role as described above in step 3 of Using the REST API. API tokens can easily be issued and revoked, thus helping to assure the account’s security.
  • We recommend that accounts that use machine tokens have the Admin role, not the Owner role. That way, there is less risk if the token is compromised, since the token has only the permissions associated with the account to which it is tied.

Revoke and Delete an Active API Token

While logged in to YubiEnterprise Delivery Console, go to your profile page by clicking on your profile icon on the top right. Click Revoke and delete active API token.

Lifecycle Management

  • When you generate an API token, be sure to copy it as soon as it is displayed, and store it in a secure location. Once you navigate away from the page you will no longer be able to view the token.
  • API tokens expire after one year. Since a user can have only one API token at a time, you must have a plan to roll-over to a new API token before the old one expires.

API FAQ

Q. Who should use the API?

  1. Customers of YubiEnterprise Delivery.

Q. Does Yubico charge for API calls?

  1. No.

Q. How do I get access to the API?

  1. Get login credentials from the YubiEnterprise Delivery account owner in your organization, and get a YubiKey in order to log in.

Q. How should I set up an account to call the API?

  1. After you have been given a YubiEnterprise Delivery account, follow the instructions in Using the REST API.

Q. How do I test the API?

  1. In lieu of a sandbox, API customers can be given a test organization with a few test keys to ship.

Q. How do I revoke an API token?

  1. In the Console, go to the profile page for the API-caller’s account and click the button to revoke the current token.

Q. Where do I go if I need help?

  1. Get help now from our support team: to file a support ticket for YubiEnterprise Delivery, click Support, or reach out to your assigned customer success representative.

Q. Can I get notification of YubiEnterprise Delivery API changes?

  1. Subscribe to the Yubico Developer Program mailing list. Go to https://www.yubico.com/why-yubico/for-developers/developer-program/.

Q. Where do I find official Yubico product images and descriptions?

  1. On Yubico’s Press room images and logos page are the logo and product images.

Q. What is the maximum number of YubiKeys that can be included in a shipment request?

  1. 500

Q. Can a shipment request be cancelled?

  1. Shipment requests can be edited or deleted until 1600hrs UTC (8am PST / 9am PDT) on the day they were entered. At 1600hrs UTC shipment requests are locked for processing. Shipment requests put in after that time will not be processed until the following week-day.
    Normal (standard) shipping:
     Shipments typically will take 5-7 days for transit in N. America and Europe. Some parts of the world may incur longer transit times.
    Expedited (rush) shipping:
     Shipments typically will take 1 business day for transit in North America and Europe. Some parts of the world may incur longer transit times.

Q. Does the country code look-up API return the countries to which Yubico can ship, or does it return all countries in the world?

  1. It returns all the countries in the world. Currently we can ship only to EU countries, the US, and Canada.

Q. What do you do with the zip_code field if it is not applicable, for example, for Canada and the EU countries?

  1. Leave the zip_code field blank and use the postal_code field instead.

Q. Do I need to validate addresses via the API prior to submitting them?

  1. “Pre-qualifying” the address does not eliminate the address validation step. Every shipping request is sent for address validation. Status is updated when address validation is complete. Once the request reaches the “Accepted for Fulfillment” status, it has passed the address validation phase. If the status is “Incomplete Address”, edit or delete the request. See Reviewing Incompletes.

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