API Reference

As an alternative to uploading a CSV file, device manufacturers can use this endpoint to upload the identifiers and SKUs of newly manufactured devices to Verizon. The request returns a synchronous response that indicates that the data has been received, and returns any errors in the request format. When the request has been fully processed, Verizon sends a report to the email address provided in the request body. Users can submit up to 10,000 device IDs per request.

All devices in an upload must be of the same type and have the same SKU.

Please wait at least 5 minutes after receiving an Upload response to submit an Activation request.

Uploads new device identifiers from OEMs to Verizon. The devices can then be added to accounts and activated for service. The information is returned in a callback response, so you must register a URL endpoint to receive DeviceService callback messages using POST /callbacks.

NOTE: To use this API method, your company must be registered on the Open Development portal with the ability to upload devices to Verizon. Additionally, users can submit up to 10,000 device IDs per request. SKUs are case-sensitive and must be upper case.

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/upload

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name	Data Type	Description
Authorization required	string	HTTP Authorization bearer token.
VZ-M2M-Token required	string	A valid session token returned by POST /session/login.
Content-Type required	string	Must be application/json.

Request Body

The request body identifies the devices to upload.

Parameter Name	Data Type	Description
accountName (optional but recommended)	string	The billing account that is being used to upload the devices. *If contact has access to only one account, `accountName` is not required. If contact has access to multiple accounts, `accountName` is required. By coding for the `accountName` today, you may prevent future code from breaking if you ever add a new sub-account.
emailAddress (required)	string	Email address that the report should be sent to after the uploaded device list is processed. This email address must be registered as part of the account profile in the Open Development portal before devices are uploaded.
deviceSku (required)	string	The stock keeping unit that identifies the type of devices in the upload. NOTE Use upper case only because lower case letters within the SKU may result in the "Device SKU is not present in DMD" error.
uploadType (required)	string	The format of the device identifiers in the upload. Use one of these values: IMEI , IMEI/ICCID Pair , IMEI/ICCID Embedded SIM Pair , IMEI/EID pair
devices (required)	array	The devices to upload, specified by `deviceIds` using a `kind` and `id`.

Example Request Body

Upload devices by IMEI:

{
  "accountName":"1223334444-00001",
  "emailAddress":"bob@mycompany.com",
  "deviceSku":"VZW123456",
  "uploadType":"IMEI",
  "devices":[
    {
      "deviceIds":[  
        {
          "kind":"IMEI",
          "id":"15-digit IMEI"
        }
      ]
    },
    {
      "deviceIds":[  
        {
          "kind":"IMEI",
          "id":"15-digit IMEI"
        }
      ]
    },
    {
      "deviceIds":[  
        {
          "kind":"IMEI",
          "id":"15-digit IMEI"
        }
      ]
    }
  ]
}

Upload devices by IMEI/ICCID Pair:

{
  "accountName":"1223334444-00001",
  "emailAddress":"bob@mycompany.com",
  "deviceSku":"VZW123456",
  "uploadType":"IMEI ICCID Pair",
  "devices":[
    {
      "deviceIds":[  
        {
          "kind":"IMEI",
          "id":"15-digit IMEI"
        },
        {  
          "kind":"ICCID",
          "id":"20-digit ICCID"
        }
      ]
    },
    {
      "deviceIds":[  
        {
          "kind":"IMEI",
          "id":"15-digit IMEI"
        },
        {  
          "kind":"ICCID",
          "id":"20-digit ICCID"
        }
      ]
    },
    {
      "deviceIds":[  
        {
          "kind":"IMEI",
          "id":"15-digit IMEI"
        },
        {  
          "kind":"ICCID",
          "id":"20-digit ICCID"
        }
      ]
    }
  ]
}

Success Response

Status 200

Parameter Name	Data Type	Description
requestId	string	A unique string that associates the request with the results that are sent via a callback message. ThingSpace sends a separate callback message for each device that was in the request indicating whether the operation succeeded for that device. All of the callback messages have the same requestId.

Example Success Response Body

{
  "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d"
}

Callback Response

The callback contains an array of devices objects, one for each device in the request and a lineStatus that describes whether the upload was successful or the error indicating why the device upload failed. Example Callback Response

{
   "username":"",
   "password":"",
   "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d",
   "deviceResponse":{
      "deviceUploadResponse":{
         "devices":[
            {
               "deviceIds":[
                  {
                     "id":"20-digit ICCID",
                     "kind":"ICCID"
                  },
                  {
                     "id":"15-digit IMEI",
                     "kind":"IMEI"
                  }
               ],
               "lineStatus":"Device upload successful."
            },
            {
               "deviceIds":[
                  {
                     "id":"20-digit ICCID",
                     "kind":"ICCID"
                  },
                  {
                     "id":"15-digit IMEI",
                     "kind":"IMEI"
                  }
               ],
               "lineStatus":"Device upload successful"
            },
            {
               "deviceIds":[
                  {
                     "id":"20-digit ICCID",
                     "kind":"ICCID"
                  },
                  {
                     "id":"15-digit IMEI",
                     "kind":"IMEI"
                  }
               ],
               "lineStatus":"SIM Id is invalid"
            }
         ],
         "accountName":"1223334444-00001",
         "deviceSku":"VZW123456",
         "totalLineCount":"3",
         "failedLineCount":"1",
         "successLineCount":"2"
      }
   },
   "status":"null",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Error Messages and Status Messages

Error Level	Error Text	Notes
Package	Device SKU is not present in ODI	The SKU is not recognized.
Package	Device SKU is not present in DMD	The SKU is not recognized. The SKU is case-sensitive, verify that your SKU is upper case.
Package	Device SKU is not Certified	The SKU is for a device that is not yet certified for use on the Verizon network.
Package	Device SKU is CDMA Type and only exception request is supported	The SKU is for CDMA devices, which can no longer be activated on the Verizon network.
Package	Device SKU is missing status in DMD	The SKU is for a device type that is not fully configured in Verizon systems.
Package	Device SKU is certified but not present in DMD	The SKU is for a device type that is not fully configured in Verizon systems.
Package	No Profile found for email address (odiPortalEmailAddress)	The email address is not registered to an Open Development account.
Package	There are no active/approved devices	The request did not contain a list of devices.
Package	Device SKU (deviceSku) not provided	The request did not contain a deviceSku value.
Package	Upload Type (uploadType) not provided	The request did not contain an uploadType value.
Package	Upload Type (uploadType) is invalid. (Must be one of ESN HEX, MEID, IMEI, IMEI ICCID Pair, IMEI ICCID Embedded SIM Pair or IMEI EID Pair)	The UploadType value was not recognized. You must use one of the valid values.
Package	Email Address (odiPortalEmailAddress) not provided	The request did not contain an emailAddress value.
Package	Email Address (odiPortalEmailAddress) is invalid	The emailAddress value is not in a valid format.
Package	Number of upload lines exceeds threshold of 10000	The request contains more than 10,000 devices.
Package	Processing failed due to an unknown error
Line	Device upload request submitted	The device has been accepted for processing. The email report indicates whether the device was added to the Verizon database.
Line	Duplicate Device ID (deviceId) found in the request	The upload contained more than one entry with the specified IMEI.
Line	Duplicate EID (eid) found in the request	The upload contained more than one entry with the specified EID.
Line	Duplicate ICCID (iccid) found in the request	The upload contained more than one entry with the specified ICCID.
Line	EID (eId) is invalid	The EID provided is not valid.
Line	EID (eId) not provided	The request did not include an EID for this device.
Line	IMEI (deviceId) is invalid	The IMEI provided is not valid.
Line	IMEI (deviceId) not provided	The request did not include an IMEI for this device.
Line	SIM Id (iccId) is invalid	The ICCID provided is not valid.
Line	SIM Id (iccId) not provided	The request did not include an ICCID for this device.

HTTP RequestCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Example Request BodyCopy Anchor Link

Success ResponseCopy Anchor Link

Example Success Response BodyCopy Anchor Link

Callback ResponseCopy Anchor Link

Error Messages and Status MessagesCopy Anchor Link

On this page