API Shipment Requests

The following sections describe how to create shipment requests using the YubiEnterprise API. Before starting, it is recommended that you review the information in Shipment Requests and Working with Shipments to get an understanding of how shipment requests work. See also the YubiEnterprise API Reference.

Note

Using the API you can create requests for shipping keys to a single address. Shipping keys to multiple addresses can only be done through the Console, as described in Shipping to Multiple Addresses: Bulk Shipments.

Shipping to Single Address

Use the /shipments_exact API to ship products to a single address as illustrated in the following examples. The API can be used to handle shipment requests both directly from Yubico, or through resellers (channel partners).

The API includes:

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

For more information, see the YubiEnterprise API Reference.

Example: Single Shipment Input

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

curl "https://api.console.yubico.com/v1/shipments_exact" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhb..." \
--data '{
{
    "channelpartner_id": 0,
    "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 the delivery_type is set to 1 indicating 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.

Important

To avoid delivery issues to addresses with long street names, for all shipments to India the maximum combined character limit is 120 characters between Address line 1 and 2. For shipments to other destinations the combined address line character limit is 105. For more information, see Recipient Information.

Shipments going to the US and Canada require a standardized two-letter USPS region code, see USPS Region/State Codes. The country code lookup in the API returns all countries in the world, not only the countries to which Yubico can ship. To see which countries Yubico can ship, see Delivery Policies.

For input values for shipment items, see Product and Inventory Identifiers.

Important

Starting with release 2.8.0, the street_line3 field in the recipient address information will be deprecated and will only be available until September 2024. There is no replacement API for this functionality.

Every shipping request is sent for address validation. “Pre-qualifying” the address using /validate-address does not eliminate the address validation step. Status is updated when address validation is complete. Once the request reaches the “Accepted for Fulfillment” status, it has passed the address validation phase.

A shipment request can be edited at any of the states between 1 and 9. From this point on, a shipment request is either processed through to an end state, or set back to state 99. The states are reflected in the messages displayed in the Console. For more information, see Shipment Status Codes.

Example: Single Shipment 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
}

Identifying Products and Inventories

The product_id and inventory_product_id parameters are both used with /shipments_exact.

product_id is the unique identifier for a product, for example “4” represents the YubiKey 5C Nano. inventory_product_id specifies which inventory you are drawing from in a shipment request, and relates to the different types of purchasing tier options.

The inventory_product_id can also be thought of as the ID for a “bucket” containing credits your organization bought to cover the purchase of keys, lanyards, etc. Typically organizations with subscriptions have multiple “buckets”, while organizations without a subscription only have a single “bucket”. The inventory “buckets” correspond to the inventories displayed in the Console.

For product_id and inventory_product_id input values, see Product and Inventory Identifiers.

To get the complete list of products and inventories available to your organization, make a call to GET /inventory. If your organization has custom-programmed keys, the returned list will also include those.

To make a shipment request for custom-programmed keys, ensure to use the /inventory /products API to get the specific inventory_product_id and product_id. Using standard product_id codes in shipment requests will result in errors.

Example: Without Subscription

A non-subscription purchase means an outright purchase of physical keys on a perpetual basis.

For example, if you bought outright a number of YubiKey 5C Nanos, when creating the shipment request the product_id and inventory_product_id values are the same in the shipment request, “4” for “YubiKey 5C Nano”.

The 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": 4,
         "shipment_product_quantity": 6
      }
   ]
}

Example: With Subscription

With a subscription, a specific value for the inventory_product_id identifies from which purchased subscription tier to draw the keys in the shipment request. The combination of product_id and inventory_product_id values defines which key model to include in the shipment, and which inventory the keys should be drawn from.

For example, a shipment request for two “YubiKey 5C Nano” (product_id = 4) from a “Primary Subscription - Advanced Tier: Initial” inventory (inventory_product_id = 15) 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": 2
      }
   ]
}

For more input values, see Product and Inventory Identifiers. See also the YubiEnterprise API Reference.

Verifying Inventory

Inventory Type relates to the type of purchase such as subscription or non-subscription. As an example, if you purchased Subscription (2.0) you will be selecting from Inventory Type 3 or 5. If you purchased keys on the perpetual mode you will use Inventory Type 1. For more information, see Subscriptions and Inventories.

Input values for the inventory_type parameter used with /inventory are provided in Product Inventory Type Mapping.

Example: Inventory Output

Before creating a shipment request, you can verify that all the products you intend to ship are currently available in your inventory. This is useful to avoid shipping errors caused by lack of inventory.

• /inventory 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.

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

For more information, see the YubiEnterprise API Reference.

Verifying Custom Inventory

You can also verify any custom configured inventory if your organization is using customized keys. Custom configuration includes for example pre-programmed keys. You can ensure desired key models are available for shipment by verifying the number of remaining custom configured keys through the API before requesting a shipment.

After Yubico configures your customized key inventory allocation, you can use GET /inventory-allocations to find out how many customized keys of different form factors remain in your current inventory.

Example: Custom Configured Inventory

The inventory-allocations response in the example below provides a simple view of remaining inventory to ship. There is an entry for each product and the remaining_allocated_inventory value represents the amount of customized keys left which can be shipped. For product input values, see Product and Inventory Identifiers.

{
"allocations": [
    {
        "product_id": 1,
        "product_name": "YubiKey 5 NFC",
        "remaining_allocated_inventory": 25
    },
    {
        "product_id": 4,
        "product_name": "YubiKey 5C Nano",
        "remaining_allocated_inventory": 25
    },
    {
        "product_id": 5,
        "product_name": "YubiKey 5Ci",
        "remaining_allocated_inventory": 2
    }
 ]
}

For more information, see the YubiEnterprise API Reference.

Shipping to Multiple Addresses

Shipping keys to multiple addresses can only be done through the Console. For more information, see Shipping to Multiple Addresses: Bulk Shipments.

Deprecated APIs

The following tables list deprecated APIs related to shipment requests. For more information, see Deprecated APIs: Overview.

Shipment Request Creation: Address Information

Deprecated	Replacement
street_line3	Starting with release 2.8.0 this field in the recipient address information will be deprecated and will only be available until September 2024. There is no replacement API for this functionality.

Shipping Requests: Bulk Shipment to Multiple Addresses

Deprecated	Replacement
GET /v1/shipments/bulk POST /v1/shipments/bulk POST /v1/shipments/bulkvalidate	From July 2024, the only method to create bulk shipment requests is to use the YubiEnterprise Console There is no replacement API for this functionality.

Deprecated: Bulk Shipment Requests via API

Important

The API for bulk shipment requests was deprecated and has been removed. The recommended method for submitting bulk shipment requests to multiple addresses is to use the YubiEnterprise Console. The documentation in the following is no longer maintained and is only for reference.

Bulk Shipment API

Bulk orders using the API are handled through the following APIs:

• GET /shipments/bulk
• POST /shipments/bulk
• POST /shipments/bulkvalidate
• POST /shipments/bulkdelete

Note

Use the CSV file for bulk shipments via API. To ensure you are using the latest CSV file format, download the template file each time you prepare to upload a new batch of shipment requests.

Shipment Request Fields in CSV File

Note

Although Console users can specify the inventory they want to draw from for individual shipment requests, this option is not available for bulk shipments. Bulk shipment requests for Subscription (1.0) allow only the selection of initial, replacement, or buffer stock. When inventory is not specified or cannot be specified, the system uses the “first in, first out” rule, which means it will deduct from the oldest purchase order first.

In the table below, all fields not marked as required 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	Description	Limit
	Country code country_code_2	Required. Country code from available_countries.csv	2
1	Company recipient	Required if name of recipient is not provided.	20
	First name recipient_firstname	Name of recipient. Required if company name is not provided.	15
	Last name recipient_lastname	Recipient’s family name. Required, if company name is not provided.	20
	Address 1 street_line1	Required. First line of address	60
	Address 2 street_line2	Required if address is undeliverable without (for example suite #)	60
	Address 3 street_line3	Not supported for expedited/rush orders	60
	City	Required. City, town, or township.	60
2	Region/State region	For the US and Canada, USPS codes are required. See USPS Region/State Codes. (Console users: Select code from dropdown). For other countries, region or state is required if the address is not deliverable without it. To check address availability, see table footnote.	50
	Postcode postal_code	Zip or postal code	50
	RecipientEmail recipient_email	Recipient’s email address	80
3	Contact Phone RecipientTelephone recipient_telephone	Required. Telephone number of the shipment recipient. The limit is 40 of the alphanumeric characters “0-9+-( )” unless the country code is IN, in which case the limit is 255. Any format is acceptable, with or without spaces.	40
4	DeliveryType delivery_type	Type of shipping, “Normal” (1) or “Expedited” (2). Integers (required for API) OR words	–
5	InventoryType	Required. Console users select from dropdown. For bulk orders and API users, see Product ID and Inventory Product ID.	–
6	ChannelPartnerId channel_partner_ID	Required. If inventory was purchased directly from Yubico, enter “1”; if not, enter the ChannelPartnerId.	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 5Ci FIPS	Number of keys to be shipped	3
	YubiKey 5C NFC FIPS	Number of keys to be shipped	3
	YubikKy 5C Nano FIPS	Number of keys to be shipped	3
	YubiKey 5C FIPS	Number of keys to be shipped	3
	YubiKey 5 NFC FIPS	Number of keys to be shipped	3
	YubiKey 5 Nano FIPS	Number of keys to be shipped	3
	YubiKey C Bio - FIDO Edition	Number of keys to be shipped	3
	YubiKey Bio - FIDO Edition	Number of keys to be shipped	3
	Security Key NFC by Yubico (Black)	Number of keys to be shipped	3
	Security Key C NFC by Yubico (Black)	Number of keys to be shipped	3
	Security Key NFC by Yubico - Enterprise Edition	Number of keys to be shipped	3
	Security Key C NFC by Yubico - Enterprise Edition	Number of keys to be shipped	3

Note

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.

C. and D. Names

Names and Addresses: First Line

First name and Last name in the Console and in the CSV file for bulk shipments, map to the first line on the shipping label.

Long recipient names can be problematic for all methods of requesting shipment, because the shipment request will fail if the contents of the First name and Last name fields and/or Company or recipient fields exceed the maximum number of characters permitted in these fields (shown in the table below).

Workaround: When a recipient’s full name or company name exceeds the fields’ maximum lengths, split the names across the three fields, as in this example:

Location	Field (limit=15)	Field (limit=20)	Field (limit=20)
API	recipient_firstname	recipient_lastname	recipient
CSV	First name	Last name	Company
Console	First name	Last name	Company
Example of an overly long name before adjustment to fit the fields
	Johannes-Maximilian	von Derschowitz-Dampfloch zu Querdenker
Example after adjustment
	Joh.-Maximilian	v.DerschowitzDampfloch	zu Querdenker

Company Name: Second Line

The second line on the shipping label maps to the name of the recipient’s company if the address is not residential. For example, the system’s address verification function recognizes that Yubico’s Santa Clara facility is in a commercial building, therefore the company name is expected in:

• The Company field/table cell in the Console and in the CSV file.

• The recipient field in the API

  Note

  API: Do not use the /shipments recipient field to specify the name of the individual to whom products are to be shipped. For this, use the recipient_firstname and recipient_last name fields instead.

If the address is residential, leave empty:

• The Company field/table cell in the Console and in the CSV file.
• The recipient field in the API.

Address Information

Incomplete or incorrect address information might cause validation errors. For example, entering the following information for a shipment request would result in failure because USPS recognizes that there are multiple companies in the building whose address is 530 Lytton Avenue:

Jan Lindberg
530 Lytton Avenue
Palo Alto, CA 94301
USA

Similarly, entering the following information for a shipment request would result in failure because a residential address would not be associated with a company.

Jan Lindberg
Yubico Inc.
6 Lea Rd
Dronfield S18 1SB
UK

When adding address information, you can for example use the address formats provided by Google Maps, see note in Troubleshooting. The limits on the various fields and the options for the dropdown are given in Shipment Request Form Fields.

E. Post Office Boxes

Although the system can deliver to Post Office (PO) Boxes within the United States, delivery to the equivalent elsewhere in the world is unlikely to succeed.

I. Region/State

For shipments going to the US and Canada, the region field requires the standardized two-letter USPS code listed below.

USPS Codes for US and Canada

State (US) / Province or Territory (Canada)	Code
Alabama	AL
Alaska	AK
Alberta	AB
Arizona	AZ
Arkansas	AR
British Columbia/Colombie-Britannique	BC
California	CA
Colorado	CO
Connecticut	CT
Delaware	DE
District of Columbia	DC
Florida	FL
Georgia	GA
Hawaii	HI
Idaho	ID
Illinois	IL
Indiana	IN
Iowa	IA
Kansas	KS
Kentucky	KY
Louisiana	LA
Maine	ME
Manitoba	MB
Maryland	MD
Massachusetts	MA
Michigan	MI
Minnesota	MN
Mississippi	MS
Missouri	MO
Montana	MT
Nebraska	NE
Nevada	NV
New Brunswick/Nouveau-Brunswick	NB
New Hampshire	NH
New Jersey	NJ
New Mexico	NM
New York	NY
Newfoundland/Terre-Neuve	NF
North Carolina	NC
North Dakota	ND
Northwest Territories/Territoires du Nord-Ouest	NT
Nova Scotia/Nouvelle-Écosse	NS
Nunavut	NU
Ohio	OH
Oklahoma	OK
Ontario	ON
Oregon	OR
Pennsylvania	PA
Prince Edward Island/Île-du-Prince-Édouard	PE
Puerto Rico	PR
Quebec/Québec	QC
Rhode Island	RI
Saskatchewan	SK
South Carolina	SC
South Dakota	SD
Tennessee	TN
Texas	TX
Utah	UT
Vermont	VT
Virginia	VA
Washington	WA
West Virginia	WV
Wisconsin	WI
Wyoming	WY
Yukon	YK

L. Telephone Number

It is required that the recipient_telephone field be populated. This is the number at which the recipient of the shipment can be reached, designated on the Console as Contact Phone.

The permissible content of this, [+()\-0-9\s]+, should match regular expressions.

For /v1/shipments_exact the API validates the existence of recipient_telephone in the request body. For CSV upload via /v1/bulkvalidate, the API validates the existence of recipient_telephone on each row. In both cases, if the country code is IN, the limit is 255 of the alphanumeric characters specified above while all other country codes limit recipient_telephone to 40.

M. Delivery Type

ShipmentDeliveryTypeEnum specifies the method of shipping:

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

N. InventoryType

The inventory_type requires one of the values given in the Inventory Types (Stock) table below.

Product <> inventory type mapping

Product or Inventory Name shown on Purchase Order	Value to use for inventory_type
YubiKey Lanyard	1
Security Key C NFC by Yubico (Black)	1
Security Key C NFC by Yubico - Enterprise Edition	1
Security Key NFC by Yubico (Black)	1
Security Key NFC by Yubico - Enterprise Edition	1
YubiKey 5 Nano	1
YubiKey 5 Nano FIPS	1
YubiKey 5 NFC	1
YubiKey 5 NFC FIPS	1
YubiKey 5C	1
YubiKey 5C FIPS	1
YubiKey 5C Nano	1
YubiKey 5C Nano FIPS	1
YubiKey 5C NFC	1
YubiKey 5C NFC FIPS	1
YubiKey 5Ci	1
YubiKey 5Ci FIPS	1
YubiKey Bio - FIDO Edition	1
YubiKey C Bio - FIDO Edition	1
Advanced - Plus - Backup	3
Advanced - Plus - Backup - Replacement	5
Advanced - Plus - Primary	3
Advanced - Plus - Primary - Replacement	5
Advanced - Standard - Backup	3
Advanced - Standard - Backup - Replacement	5
Advanced - Standard - Primary	3
Advanced - Standard - Primary - Replacement	5
Advanced/Bio - Plus - Backup	3
Advanced/Bio - Plus - Backup - Replacement	5
Advanced/Bio - Plus - Primary	3
Advanced/Bio - Plus - Primary - Replacement	5
Advanced/Bio - Standard - Backup	3
Advanced/Bio - Standard - Backup - Replacement	5
Advanced/Bio - Standard - Primary	3
Advanced/Bio - Standard - Primary - Replacement	5
Backup Subscr - Adv. Tier: Buffer	4
Backup Subscr - Adv. Tier: Initial	3
Backup Subscr - Adv. Tier: Replacement	5
Backup Subscr - Base Tier: Buffer	4
Backup Subscr - Base Tier: Initial	3
Backup Subscr - Base Tier: Replacement	5
Backup Subscr - FIPS Tier: Buffer	4
Backup Subscr - FIPS Tier: Initial	3
Backup Subscr - FIPS Tier: Replacement	5
Backup Subscr - Prem. Tier: Buffer	4
Backup Subscr - Prem. Tier: Initial	3
Backup Subscr - Prem. Tier: Replacement	5
Base - Plus - Backup	3
Base - Plus - Backup - Replacement	5
Base - Plus - Primary	3
Base - Plus - Primary - Replacement	5
Base - Standard - Backup	3
Base - Standard - Backup - Replacement	5
Base - Standard - Primary	3
Base - Standard - Primary - Replacement	5
Base/Bio - Plus - Backup	3
Base/Bio - Plus - Backup - Replacement	5
Base/Bio - Plus - Primary	3
Base/Bio - Plus - Primary - Replacement	5
Base/Bio - Standard - Backup	3
Base/Bio - Standard - Backup - Replacement	5
Base/Bio - Standard - Primary	3
Base/Bio - Standard - Primary - Replacement	5
Compliance - Plus - Backup	3
Compliance - Plus - Backup - Replacement	5
Compliance - Plus - Primary	3
Compliance - Plus - Primary - Replacement	5
Compliance - Standard - Backup	3
Compliance - Standard - Backup - Replacement	5
Compliance - Standard - Primary	3
Compliance - Standard - Primary - Replacement	5
Non-subscription - Advanced Tier	2
Non-subscription - Base Tier	2
Non-subscription - FIPS Tier	2
Non-subscription - Premium Tier	2
Primary Subscr - Adv. Tier: Buffer	4
Primary Subscr - Adv. Tier: Initial	3
Primary Subscr - Adv. Tier: Replacement	5
Primary Subscr - Base Tier: Buffer	4
Primary Subscr - Base Tier: Initial	3
Primary Subscr - Base Tier: Replacement	5
Primary Subscr - FIPS Tier: Buffer	4
Primary Subscr - FIPS Tier: Initial	3
Primary Subscr - FIPS Tier: Replacement	5
Primary Subscr - Prem. Tier: Buffer	4
Primary Subscr - Prem. Tier: Initial	3
Primary Subscr - Prem. Tier: Replacement	5

• Customers who have purchased Subscription (2.0) will be selecting only Inventory Type 3 or 5.
• 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.
• Subscription (1.0) customers: Use Inventory Types 3, 4, and/or 5.

Stock: Initial, Buffer, Replacement

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.

O. Channel Partners

The CSV file used in the upload includes 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.

To order keys via API from inventory purchased through channel partners (distributors/resellers), the new /shipments_exact APIs must be used; see Deprecated APIs below. The older, deprecated /shipments API only supports ordering keys from inventory purchased directly from Yubico.

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.

Product ID and Inventory Product ID

The product_id is the unique identifier for the product, e.g., 4 is the YubiKey 5C Nano. 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 without a subscription might have only a single “bucket.”

Both product_id and inventory_product_id are required fields.

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 Stock/Inventory 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, calling GET /inventory will return a list that also contains your custom products (see also Custom-programmed YubiKeys).

• When making requests, use the /inventory end point to find the product_id to use for that and/or inventory_product_id.

  Note

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

Stock/Inventory: product_id and inventory_product_id mapped to Product Name

product_id and/or inventory_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
68	YubiKey C Bio - FIDO Edition
69	YubiKey Bio - FIDO Edition
82	Security Key NFC by Yubico (Black)
83	Security Key C NFC by Yubico (Black)
84	Security Key NFC by Yubico - Enterprise Edition
85	Security Key C NFC by Yubico - Enterprise Edition
86	Base - Standard - Primary
87	Base - Standard - Backup
88	Base - Standard - Primary - Replacement
89	Base - Standard - Backup - Replacement
90	Base - Plus - Primary
91	Base - Plus - Backup
92	Base - Plus - Primary - Replacement
93	Base - Plus - Backup - Replacement
94	Base/Bio - Standard - Primary
95	Base/Bio - Standard - Backup
96	Base/Bio - Standard - Primary - Replacement
97	Base/Bio - Standard - Backup - Replacement
98	Base/Bio - Plus - Primary
99	Base/Bio - Plus - Backup
100	Base/Bio - Plus - Primary - Replacement
101	Base/Bio - Plus - Backup - Replacement
102	Advanced - Standard - Primary
103	Advanced - Standard - Backup
104	Advanced - Standard - Primary - Replacement
105	Advanced - Standard - Backup - Replacement
106	Advanced - Plus - Primary
107	Advanced - Plus - Backup
108	Advanced - Plus - Primary - Replacement
109	Advanced - Plus - Backup - Replacement
110	Advanced/Bio - Standard - Primary
111	Advanced/Bio - Standard - Backup
112	Advanced/Bio - Standard - Primary - Replacement
113	Advanced/Bio - Standard - Backup - Replacement
114	Advanced/Bio - Plus - Primary
115	Advanced/Bio - Plus - Backup
116	Advanced/Bio - Plus - Primary - Replacement
117	Advanced/Bio - Plus - Backup - Replacement
118	Compliance - Standard - Primary
119	Compliance - Standard - Backup
120	Compliance - Standard - Primary - Replacement
121	Compliance - Standard - Backup - Replacement
122	Compliance - Plus - Primary
123	Compliance - Plus - Backup
124	Compliance - Plus - Primary - Replacement
125	Compliance - Plus - Backup - Replacement

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.

Error Messages

In the API

The following response is sent if recipient_telephone is not included in the request to create shipment at shipments_exact as per POST /v1/shipments_exact:

400 Bad Request {
  code: 'validation_error',
  message: 'We were unable to create the shipment',
  errors: [
    {
      field: 'recipient_telephone',
      message: 'recipient_telephone is a required field'
    }
  ]
}

In the CSV

When uploading a CSV file with no recipient_telephone provided in one or more rows:

YRIEIXLECHAT-01:shipments yrieix.lechat$ cat my-shipments.csv
Country code 2,Company,First name,Last name,Address 1,Address 2,Address 3,City,Region/State,Postcode,RecipientEmail,RecipientTelephone,DeliveryType,InventoryType,ChannelPartnerId,YubiKey 5 NFC,YubiKey 5 Nano,YubiKey 5C,YubiKey 5C Nano,YubiKey 5Ci,Security Key NFC by Yubico,YubiKey FIPS,YubiKey Nano FIPS,YubiKey C FIPS,YubiKey C Nano FIPS
US,My Company,Yrieix,LeChat,123 Home Ave,,,Brooklyn,NY,11111,y.lechat@yubico.com,,Normal,1,1,0,0,0,0,0,1,0,0,0,0
YRIEIXLECHAT-01:shipments yrieix.lechat$ curl -v -s -X POST -H "Authorization: Bearer ..." -F file=@./my-shipments.csv http://api.console.local/v1/shipments/bulkvalidate   | json_pp
...
> POST /v1/shipments/bulkvalidate HTTP/1.1
> Host: api.console.local
...
< HTTP/1.1 200 OK
...
{
   "csv_filename" : "my-shipments.csv",
   "failed_rows" : [
      {
         "fatal_messages" : "recipient_telephone is a required field",
         "row_number" : 2
      }
   ],
   "lines_in_file" : 2,
   "lines_not_parsable" : 1,
   "lines_read" : 1
}

The system chooses the stock (inventory) from which products are drawn.

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: Bulk Shipments.

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.

Examples of 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

---

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