Device Manager API Request

Administrators for the company that owns Smart Inventory Tracker send the Device Manager Request to provide information for devices that need authentication. Administrators can also update data attributes and configuration details for previously authenticated devices or delete device information.

See the Body guidelines, Errors, and Body example for this message below.

Body guidelines

Element Type

Update

 Description
deviceInformationList List Begin – Required. The list of devices that require authentication certificates.
The request must contain a maximum of 40 devices.
  deviceInformation Section Begin – Required. The information about each device.
    deviceName String Yes Required. The name of the device. Must be unique across all names defined for a single locationId.
    deviceUniqueIdentifier String No Required. The Machine (e.g. MAC) address for the device. Must be 6 sets of 2 characters separated by colons or hyphens (e.g. 00:23:68:CF:A4:D8 or 00-23-68-CF-A4-D8). Acceptable characters are numbers 0-9 and letters A-F.
    deviceType Enum No Required. The type of device. Valid values:
  • Handheld
  • SmartPhone
    deviceMake Enum No

Required. The brand of the device.

Valid values:

  • Zebra (Only allowed if the deviceType is Handheld.)
  • Honeywell (Only allowed if the deviceType is Handheld.)
  • Google (Only allowed if the deviceType is SmartPhone.)
  • Samsung (Only allowed if the deviceType is SmartPhone.)
    deviceModel Enum No

Required. The model of the device.

Valid values:

  • MC3300 (Only allowed if the deviceMake is Zebra.)
  • TC70x (Only allowed if the deviceMake is Zebra.)
  • TC51 (Only allowed if the deviceMake is Zebra.)
  • TC52 (Only allowed if the deviceMake is Zebra.)
  • CN80L1N (Only allowed if the deviceMake is Honeywell.)
  • Pixel2 (Only allowed if the deviceMake is Google.)
  • GalaxyS9 (Only allowed if the deviceMake is Samsung.)
    action Enum –

Required. The action that the Device Manager must take with the specified deviceUniqueIdentifier.

Valid values:

  • add – Register a new device, and add the new device information.
  • update – Update the device information for an existing device.
  • delete – Delete all information stored for an existing device.
    companyExternalId String Yes Required. The External ID for the company registering the device. Must match a valid company in the Track & Trace Services. Contact TraceLink Support or the company's TraceLink Technical Consultant for the External ID.
    locationId String Yes Required. The identifier value for the device's specific location. Must match a valid location in the Track & Trace Services.
    locationType Enum Yes Required. The identifier type for the device's specific location.
  • AR_CUIT – 11-character Argentina Tax ID. Format is 00-00000000-0 (e.g. 33-56899856-8). Cannot be set as the Primary Identifier.
  • AM_TIN – 8-character Armenia Taxpayer Identification Number (e.g. 53663456). Cannot be set as the Primary Identifier.
  • BR_CNES – Brazil National Registry of Health Facilities Number (e.g. 3868249).
  • BR_CNPJ – 14-character Brazil Tax/Legal Entity ID. Format is 00.000.000/0001-00 (e.g. 71.116.165/0001-71).
  • BR_CPF – 11-character Brazil Individual Taxpayer Registration Number. Format is 000.000.000-00 (e.g. 605.085.153-00). The first 8 digits identify the company, the next 4 digits identify the branch or subsidiary ("0001" designates the headquarters), and the last 2 are check digits.
  • BR_PROF_REG – Brazil Professional Registration Number (e.g. CRODFCD9952).
  • BY_TIN – 9-character Belarus Taxpayer Identification Number (e.g. 004893223). Cannot be set as the Primary Identifier.
  • CN_CHINA_ID – Alphanumeric China identifier (e.g. 352J685B548N).
  • CN_FOREIGN_MAH – China Foreign MAH ID (e.g. 0678645).
  • CN_FOREIGN_MFR – China Foreign Manufacturer ID (e.g. 665S55D).
  • CN_USCID – China Unified Social Credit Identifier (e.g. 9771221453).
  • COMPANYID – Alphanumeric internal company identifier (e.g. KENDALL).
  • COMPANYSITEID – Alphanumeric internal location, plant, or site identifier (e.g. 465MEMPHIS).
  • DE_IFA_REG_NUM – 6-character Informationsstelle für Arzneispezialitäten (IFA) Registration Number (e.g. 548726). Cannot be set as the Primary Identifier.
  • DEA – 9-character US Drug Enforcement Agency Number (e.g. F92547851).
  • DUNS – 9-character Dunn and Bradstreet Number (e.g. 82-759-6961).
  • DUNS4 – 13-character Dunn and Bradstreet Number, which includes a 4 digit extension (e.g. 82-759-6961-KP89).
  • DUNS_PLUS_FOUR – 13-character Dunn and Bradstreet Number, which includes a 4 digit extension (e.g. 82-759-6961-KP89).
  • GCP – 6- to 12-character GS1 Global Company Prefix (e.g. 8856277).
  • GLN – 13-character Global Location Number (e.g. 8856277233311). To send and receive EPCIS messages, companies and locations need a GLN.
  • HIN – Maximum 9-alphanumeric character Health Industry Number assigned by HIBCC (e.g. 214Z65H00).
  • ID_BPOM_FACILITYID – Indonesia Facility ID (e.g. 45764574).
  • IN_COMPANY_ID – India Company ID (e.g. 5423695784236).
  • IN_GSTN – India Goods and Services Tax ID (e.g. 55876215).
  • IN_IEC – 10-character India Importer Exporter Code (e.g. 0255411222). Cannot be set as the Primary Identifier.
  • IN_LOCATION_ID – India Location ID (e.g. 65874532).
  • IN_MFR – India Manufacturing Code (e.g. 00552101).
  • IN_MRCH – India Merchant Exporter Code (e.g. 601227644).
  • IN_PAN – 10-character India Permanent Account Number. The first five characters are letters, next four numbers, last character is a letter (e.g. AFZPK7190K). Cannot be set as the Primary Identifier.
  • IN_TIN – 11-character India Taxpayer Identification Number (e.g. 95684444523). Cannot be set as the Primary Identifier.
  • KG_TIN – 14-character Kyrgyzstan Taxpayer Identification Number (e.g. 56200044505998). Cannot be set as the Primary Identifier.
  • KR_BUS_REG_NUMBER – 10-character South Korea Corporate Registration Number. Format is xxx-xx-xxxxx (e.g. 324-84-22451).
  • KR_PROVIDER_CODE – 8-character South Korea Provider Code (e.g. 45632196).
  • KZ_BIN – 12-character Kazakhstan Business Identification Number (e.g. 220110668755). Cannot be set as the Primary Identifier.
  • RU_ACCOUNT_NUMBER – 14- to 36-character Russia Account Number (e.g. 19527400000001 or 19406412-0001-000a-0000-000000000022). Cannot be set as the Primary Identifier.
  • RU_INN_FOREIGN_ENTITY – 10-character Russia Foreign Business Taxpayer Identification Number (e.g. 7744000912). Cannot be set as the Primary Identifier. Only one of the following identifier types can be assigned to an entity: RU - INN Local, RU - IN Foreign, and RU - INN Individual.
  • RU_INN_INDIV – 12-character Russia Individual Taxpayer Identification Number (e.g. 123456789001). Cannot be set as the Primary Identifier. Only one of the following identifier types can be assigned to an entity: RU - INN Local, RU - IN Foreign, and RU - INN Individual.
  • RU_INN_KPP_TAX_CODE – 9-character Russia KPP Registration Code (e.g. 771301001). Cannot be set as the Primary Identifier.
  • RU_INN_LOCAL_ENTITY – 10-character Russia Local Business Taxpayer Identification Number (e.g. 7728640746). Cannot be set as the Primary Identifier. Only one of the following identifier types can be assigned to an entity: RU - INN Local, RU - IN Foreign, and RU - INN Individual.
  • SGLN – 15-character SGLN format representation of Global Location Number:
    • Format for company entities is [CompanyPrefix].[LocationRef].0 or [CompanyPrefix]..0. The LocationRef segment is optional. If the LocationRef is included, the first two segments contain only digits separated by the dot, and must be 13 characters in total. If the LocationRef is not included, then the first segment must be 12 digits, followed by two dot seperators. The third segment should always be the digit 0. For example, 539885451928..0 or urn:epc:id:sgln:0614141.12345.0.
    • Format for location entities is [CompanyPrefix].[LocationRef].[sub-location identifier] or [CompanyPrefix]..[sub-location identifier].The LocationRef segment is optional. If the LocationRef is included, the first two segments contain only digits separated by the dot, and must be 13 characters in total. If the LocationRef is not included, then the first segment must be 12 digits, followed by two dot seperators. The third segment is always alphanumeric and can be any length, with at least one character in it preceded by the dot separator. For example, 8856277.23331.6 or 539885451928..11.
  • TRACELINK_ID – TraceLink Identification Number (e.g. KENDALLPHARM).
  • UZ_TIN – 9-character Uzbekistan Taxpayer Identification Number (e.g. 000181244). Cannot be set as the Primary Identifier.
    countryCode String Yes Conditionally required if the serialNumberEventManager is SEM, defaultSOM, or defaultSEM.

The default market for reporting serial numbers to. Must be an ISO Alpha 2-digit code.
    environment Enum Yes Required. The Smart Inventory Tracker environment that the device must be authenticated within.

Valid values:

  • beta
  • itest
  • production
If a device updates to a different environment, the authentication certificates must be retrieved from the response and installed on the device again.
    port Enum Yes

The firewall port that the individual device uses to communicate with the TraceLink Track & Trace Services.

Valid values:

  • 8883 – The standard port that the device uses to communicate with the TraceLink Track & Trace Services.
  • 443 – Devices can use this port to communicate with the TraceLink Track & Trace Services if the company blocks port 8883.

If a device is currently registered with 8883 as the port element, the company must keep their 8883 firewall port open until the device is successfully updated to the 443 port.

If the port element is not present, the device defaults to 8883.
    serialNumberEventManager Enum Yes

Required. The serial number event manager that Smart Inventory Tracker integrates with.

Valid values:

  • SOM – The device can integrate with Serialized Operations Manager only.
  • SEM – The device can integrate with Smart Event Manager only.
  • defaultSOM – The device can integrate with Serialized Operations Manager or Smart Event Manager, and Serialized Operations Manager is the default integration when logging in.
  • defaultSEM – The device can integrate with Serialized Operations Manager or Smart Event Manager, and Smart Event Manager is the default integration when logging in.
    active Boolean Yes

Required. Indicates whether the device can be used.

Valid values:

  • true – Users can log in to Smart Inventory Tracker on the device.
  • false – Users cannot log in to Smart Inventory Tracker on the device. Users that attempt to log in will receive an error.

Errors

Errors display in the Device Manager Response. Only the specified device fails authentication, not the entire list.

Element Error Description
username User is not authorized to access this resource with an explicit deny The username is not present, or the username and password pairing cannot be authenticated.
user [username] does not have the Devices permission The username can be authenticated, but the user is not an Administrator for the company where the device is being registered, or the user is not assigned a role with the Devices permission enabled.
password User is not authorized to access this resource with an explicit deny The password is not present or the username and password pairing cannot be authenticated.
deviceInformationList More than 40 devices defined within the request. Limit request to 40 devices. The request must contain a maximum of 40 devices. Separate the request into multiple messages to add, update, or remove more than 40 devices.

deviceName

 The device [deviceName] is not unique within the associated location [locationId] At least one other device at that locationId exists with the same deviceName.
deviceName for [deviceUniqueIdentifier] is required The deviceUniqueIdentifier is present, but the deviceName is not.
deviceName is required Neither the deviceName nor the deviceUniqueIdentifier are present.
deviceName must not contain spaces The deviceName contains a space, which is an invalid character.
deviceName contains invalid characters The deviceName contains a character that is not alphanurmeric or one of the following special characters: _ . , @ / : # -
deviceUniqueIdentifier Device [deviceUniqueIdentifier] must be 6 sets of two characters, separated by a colon ":" or a hyphen "-" and containing numbers 0-9 and letters A-F The deviceUniqueIdentifer does not follow the format requirements.
Device [deviceUniqueIdentifier] already exists Another device registered with the Device Manager uses the same deviceUniqueIdentifier, and the action specified in the request is add.
deviceUniqueIdentifier is a required field The deviceUniqueIdentifier is not present.
Device [deviceUniqueIdentifier] does not exist in your company The specified device exists at another company on the TraceLink network and cannot be added to, updated, or removed from the company of the user that sent the request.
deviceType deviceType must be one of the supported values The deviceType is not present, or is not Handheld or SmartPhone.
deviceMake deviceMake must be one of the supported values The deviceMake is not specified, or is not Zebra, Google, or Samsung.
Invalid deviceMake based on deviceType, deviceMake must be Zebra or Honeywell when deviceType is Handheld The deviceType is Handheld, but the deviceMake is not Zebra or Honeywell.
Invalid deviceMake based on deviceType, deviceMake must either be Google or Samsung when deviceType is SmartPhone The deviceType is SmartPhone, but the deviceMake is not Google or Samsung.
deviceModel deviceModel must be one of the supported values The deviceModel is not specified, or is not MC3300, TC50x, TC51, TC52, CN80L1N, Pixel2, or GalaxyS9.
Invalid deviceModel based on deviceMake, deviceModel must be MC3300, TC70x, TC51, or TC52 when deviceMake is Zebra The deviceMake is Zebra, but the deviceModel is not MC3300, TC50x, TC51, or TC52.
Invalid deviceModel based on deviceMake, deviceModel must be CN80L1N when deviceMake is Honeywell The deviceMake is Honeywell, but the deviceModel is not CN80L1N.
Invalid deviceModel based on deviceMake, deviceModel must be Pixel 2 when deviceMake is Google The deviceMake is Google, but the deviceModel is not Pixel2.
Invalid deviceModel based on deviceMake, deviceModel must be GalaxyS9 when deviceMake is Samsung The deviceMake is Samsung, but the deviceModel is not GalaxyS9.
action Device [deviceUniqueIdentifier] does not exist and cannot be deleted The Device Manager does not have record of the device specified and cannot delete it.
action is a required field An action is not present.
[action] failed The Device Manager did not successfully store the device information.
companyExternalId companyExternalId is a required field The companyExternalId is not present.
locationId lnvalid locationId [locationId] The locationId does not exist in the Track & Trace Services.
locationId is a required field The locationId is not present.
locationType locationType is a required field The locationType is not present.
Invalid locationType [locationType] The locationType is not one of the supported values (see Guidelines above).
locationType does not match expected locationType for locationID [locationID] The locationId is found in the Track & Trace Services, but the locationType value does not match the locationType associated with that locationId.
countryCode countryCode is a required field when serialNumberEventManager is SEM The serialNumberEventManager is SEM, but the countryCode is not present.
countryCode must be a valid ISO 3166 Alpha 2-Code The countryCode is not a valid ISO 3166 Alpha 2-Code.
environment environment is a required field The environment is not present or is not Beta, Test, or Production.
port port must be one of the supported values, '8883' or '443' The port is entered, but is not 8883 or 443.
serialNumberEventManager serialNumberEventManager is a required field The serialNumberEventManager is not present.
serialNumberEventManager must be one of the supported values, 'SOM', 'SEM', 'defaultSOM', or 'defaultSEM The serialNumberEventManager is not SOM, SEM, defaultSOM, or defaultSEM.
active active is a required field The active value is not present.
active value must be true or false The active value is not true or false.

Body example

Copy 
{"deviceInformationList":
[{"deviceName": "HH_QE_OMICRON-C5",
    "deviceType": "Handheld",
    "deviceMake": "Zebra",
    "deviceModel": "MC3300",
    "action": "add",
    "deviceUniqueIdentifier": "94:FB:29:29:0C:C5",
    "companyExternalId": "kendallpharm",
    "locationId": "MUNICHWOBURN-326",
    "locationType": "COMPANYSITEID",
    "countryCode": "DEUS,
    "environment": "itest",
    "port": "8883",
    "serialNumberEventManager": "defaultSEM",
    "active": "true"
}]}