Identifiers

A DeviceIdentifier encapsulates hardware IDs to identify a manufactured device. This document explains how to work with identifiers in the zero-touch enrollment API.

A DeviceIdentifier combines a hardware metadata or IDs, with the name of the device's manufacturer. This combination of device identifiers helps stop provisioning the wrong device through data entry errors.

Your organization includes the device identifier values when uploading device data through the portal or calling the API. Because DeviceIdentifier instances are immutable, you can't use the API to change the field values.

Required fields

Zero-touch enrollment typically identifies devices by the IMEI (or MEID) cellular modem IDs. But to support devices without cellular modems, such as tablets, you can also identify devices using a different set of fields. The following table shows the fields required for each type of device:

Identifier Cellular Wi‑Fi only Notes
hardware_id This field must be an IMEI or MEID number. Zero-touch enrollment validates the format of IMEI values when you pass them in API arguments. For devices with more than one cellular modem, see Dual-SIM devices.
serialNumber The manufacturer’s serial number for the device. The serial number is case sensitive and is the same value that’s returned from Build.getSerial().
model The device model value must match the device's built-in value returned from Build.MODEL. See the model names reference for a list of allowed values for each manufacturer.
manufacturer For zero-touch enrollment to work for a device, the manufacturer field value must match the device's built-in value returned from Build.MANUFACTURER. See the manufacturer names reference for a list of allowed values.

If the device doesn’t include a cellular modem, for example a tablet or warehouse inventory scanner, use the Wi-Fi only fields. For all other devices, use the cellular fields.

Dual-SIM devices

A dual-SIM device includes two discrete modems and has two IMEI numbers. Use the first hardware ID because zero-touch enrollment identifies devices by modem 1. If you mistakenly claim a device using another IMEI or MEID number, the portal shows a new, separate device. However, zero-touch enrollment doesn't provision the device.

Refer to a device

Use a DeviceIdentifier when finding or claiming devices. You need to include the device manufacturer, as well as the hardware metadata or an ID.

The following snippet shows an IMEI number used to search for a specific device by calling partners.devices.findByIdentifier:

Java

// Create a DeviceIdentifier.
DeviceIdentifier deviceIdentifier = new DeviceIdentifier();
deviceIdentifier.setManufacturer("Google");
deviceIdentifier.setImei("123456789012347");

// Perform the search using the zero-touch enrollment API.
FindDevicesByDeviceIdentifierRequest body = new FindDevicesByDeviceIdentifierRequest();
body.setLimit(1L);
body.setDeviceIdentifier(deviceIdentifier);

FindDevicesByDeviceIdentifierResponse response = service
    .partners()
    .devices()
    .findByIdentifier(PARTNER_ID, body)
    .execute();

.NET

// Create a DeviceIdentifier.
var deviceIdentifier = new DeviceIdentifier
{
    Manufacturer = "Google",
    Imei = "123456789012347"
};

// Perform the search using the zero-touch enrollment API.
var body = new FindDevicesByDeviceIdentifierRequest
{
    Limit = 1,
    DeviceIdentifier = deviceIdentifier
};
var response = service.Partners.Devices.FindByIdentifier(body, PartnerId).Execute();

Python

# Create a DeviceIdentifier.
device_identifier = {'manufacturer':'Google', 'imei':'123456789012347'}

# Perform the search using the zero-touch enrollment API.
response = service.partners().devices().findByIdentifier(
    partnerId=PARTNER_ID, body={'deviceIdentifier':device_identifier, \
    'limit':1}).execute()

The following snippet shows how to create a Wi-Fi-only device identifier:

Java

// Create a device identifier to find a Wi-Fi-only device.
DeviceIdentifier deviceIdentifier = new DeviceIdentifier();
deviceIdentifier.setManufacturer("Honeywell");
deviceIdentifier.setModel("VM1A");
deviceIdentifier.setSerialNumber("ABcd1235678");

.NET

// Create a device identifier to find a Wi-Fi-only device.
var deviceIdentifier = new DeviceIdentifier
{
    Manufacturer = "Honeywell",
    Model = "VM1A",
    SerialNumber = "ABcd1235678"
};

Python

# Create a device identifier to find a Wi-Fi-only device.
device_identifier = {'manufacturer':'Honeywell', \
    'model':'VM1A', 'serialNumber':'ABcd1235678'}

Learn more