API Reference Information
The following sections provide input values for various parameters used when working in the Enterprise Console as well as using the YubiEnterprise API.
Country Codes
Creating shipment requests to multiple addresses (bulk shipments) or through the API requires entering a two-letter country code as part of the shipment address. You can download a CSV file containing country codes for all countries available for shipments for an organization. You can also use the API GET /countries/csv to get the correct country codes.
USPS Region/State Codes
Shipments going to the US and Canada require a standardized two-letter USPS region code. For more information, see USPS Region/State Codes.
Product and Inventory Identifiers
The product_id and inventory_product_id parameters are both used with /shipments_exact.
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 |
| 152 | YubiKey Bio - Multi-protocol Edition |
| 153 | YubiKey C Bio - Multi-protocol Edition |
Product Inventory Type Mapping
Input values for the inventory_type parameter used with /inventory.
| 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.
Shipment Status Codes
Shipment state codes and associated status messages.
shipment_state_code
shipment_state_id
|
Status description
(shipment_state_description)
|
Status message in Console
(shipment_state_message)
|
|---|---|---|
ShipmentStateIncomplete
1
|
Shipment request received
by YubiEnterprise Delivery
system but contained some
data that could not be
processed.
(2), (3) |
Incomplete Shipping
Request
|
ShipmentStateDraft
2
|
Shipment request is being
edited and is not ready for
processing.
|
Draft |
ShipmentStateAwaitingValidation
3
|
Shipment request received,
no validation done yet.
|
Awaiting Validation |
ShipmentStateProcessingAddress
4
|
Shipment request locked as
it undergoes country check,
address validation, sales
tax rate lookup (US), DPL
check.
|
Processing |
ShipmentStateAddressValid
5
|
Shipment request address has
been validated, ready to be
picked up by fulfillment
processor.
|
Accepted for Fulfillment |
ShipmentStateAddressInvalid
6
|
Shipment request address is
invalid but an alternative
address has been found and
suggested.
(2), (3) |
Incomplete |
ShipmentStateAddressFail
7
|
Shipment request address
could not be validated and
no alternative could be
found for suggesting.
(2), (3) |
Address Validation Failed
(Previously: Address
is undeliverable
or could not be
understood)
|
ShipmentStateError
8
|
Shipment request has failed
processing due to
insufficient credits
or insufficient inventory.
|
Error: Processing Error,
contact Support
|
ShipmentStateDPLMatch
9
|
Shipment request recipient
found on DPL, therefore it
is illegal to fulfill this
shipment request.
(4) |
Error: DPL Match |
ShipmentStateRequested
12
|
Used for manual shipments
that are requested but have
not yet been shipped.
|
Requested |
ShipmentStateUnableToFormatAddress
14
|
The shipment request was not
accepted due to the recipient
address exceeding the maximum
character length set by
the carrier.
|
Address Not Accepted
by Carrier
|
ShipmentStateShipmentError
99
|
Shipment request rejected
from ShipmentState-
ProcessingFulfillment
with “%s” error message;
could not be fulfilled by
processor.
|
Error: Shipping error,
contact Support
|
ShipmentStateProcessingShipment
100
|
Shipment request was locked
at 1000hrs UTC to calculate
and deduct tax, inventory,
and credits.
(1) |
Processing: Inventory &
Tax Deductions
|
ShipmentStateFulfillmentReady
101
|
Shipment request ready to be
queued for fulfillment.
|
Processing: Ready for
Fulfillment
|
ShipmentStateProcessingFulfillment
102
|
Shipment sent for fulfill-
ment at 10:00am (or cutoff
time.
(1) |
Processing: Sent for
Fulfillment
|
ShipmentStateShipped
103
|
Shipment sent out by
fulfillment processor and is
in transit.
|
Shipped: In transit |
ShipmentStateShipped
104
|
Shipment delivered.
|
Delivered |
ShipmentStateLost
105
|
Shipment lost and delivery
is no longer expected.
|
Shipment Lost/Missing |
ShipmentStateDeliveryException
106
|
Customs hold or undelivered
or returned shipment to
sender or any other shipping
exceptions.
|
Delivery Exception |
ShipmentStateDPLConfirmed
107
|
A shipment that was
automatically detected as a
DPL match has been reviewed
by Yubico and found to be a
confirmed match (not false
positive). The shipment will
not be processed.
|
DPL Confirmed
|
ShipmentStateCancelled
108
|
The shipment has been
cancelled, for example
because a logistics partner
is not able to ship the
order. Cancelling is a manual
action done by Yubico.
|
Cancelled
|
ShipmentStateReturnedToSender
110
|
Shipment has bounced and
been returned to sender
(Yubico or one of Yubico’s
logistics partners).
|
Returned to Sender
|
ShipmentStateShippingQueue
1025
|
Shipment queued for
fulfillment.
|
Processing:
Queued for Fulfillment
|
ShipmentStateManualFulfillment
2000
|
Shipment is being fulfilled
manually. No further action
by shipment requestor is
required.
|
Manual Processing |
(1) Refer to Time Frames 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 Validation Failed (previously “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 by the address validation service.
(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 Error Messages
Error messages accessible via the API. The Explanation column provides the message source: YubiEnterprise Delivery system for internal messages, US Validation for the US Postal Service, and International Validation. Messages originating from the last two are passed on by YubiEnterprise Delivery.
| Message | Explanation |
|---|---|
InventoryProductId not specified forProductId %d - ShipmentStateError
|
YubiEnterprise Delivery system
|
Too many keys in shipment -
TotalKeysShipped %d > %d - ShipmentStateError
|
YubiEnterprise Delivery system
|
Not enough Inventory for Shipment -
ShipmentStateError
|
See Purchase Orders
YubiEnterprise Delivery system
|
Re-enter the address differently; some parts
of it are invalid.
|
See Troubleshooting
US Validation
|
The address is invalid.
|
See Troubleshooting
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 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, for example
the “185” in “185 Berry Street” is missing.
US Validation
|
Enter a valid street number.
|
The number on the primary line, for example
the “185” in “185 Berry Street” not valid.
US Validation
|
Enter a PO Box, Rural Route, or Highway
Contract 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 > 0.
YubiEnterprise Delivery system
|
US Address is missing the state
name/abbrevation 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
|
Shipment of these products to this country
using this delivery type is not supported
For more information, see Delivery Policies.
|
Shipment request contravenes one or more
business rules.
YubiEnterprise Delivery system
|
Response Request Status Codes
Explanations of common status codes in responses from the YubiEnterprise API.
| 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 |
Deprecated APIs: Overview
The following tables list deprecated APIs and recommended replacements if available. Deprecated APIs will eventually be removed, and it is therefore recommended that existing implementations be updated. Ensure that your implementation is not using a deprecated version of the API. New implementations should use the recommended replacement methods.
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/bulkPOST /v1/shipments/bulkPOST /v1/shipments/bulkvalidate |
From July 2024, the only method to create
bulk shipment requests is to use the
There is no replacement API for this functionality.
|
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 |
User Management
Starting with release 2.11.0 new APIs for user management were introduced. The old APIs are deprecated and will be available until November 23, 2024.
| Deprecated | Replacement |
|---|---|
POST /v1/users/{userId} |
POST /v1/users/{userId}body
{"roles": ["org-owner","distributor","reseller"]} |
POST /v1/organization/users/reset/{email} |
POST /v1/users/{userId}body
{"action": "reset-user"} |
POST /v1/organization/users/reset-password/{email} |
POST /v1/users/{userId}body
{"action": "reset-password"} |
DELETE /v1/organization/users/{email} |
DELETE /v1/users/{userId} |
To file a support ticket for YubiEnterprise Delivery, click Support.