Get a List of Devices in an Account

Get a List of Devices in an Account

GET /devices/{acc}

Returns an array of all devices in the specified account. Each device object includes information needed for managing firmware, including the device make and model, MDN, FOTA eligibility, distribution type, and firmware installed on the device.

Uses and Requirements

Each response includes a maximum of 1,000 devices. If the report contains more than 1,000 devices (indicated by the hasMoreData parameter in each response), you must send additional requests to retrieve the remaining devices. Use the lastSeenDeviceId parameter to return a different set of devices in each response.

Request Components

HTTP Request

GET https://thingspace.verizon.com/api/fota/v3/devices/{acc}?protocol=LWM2M

Resource Path and Query Parameters

You must include the account name in the path.

Parameter Name Data Type Description
acc
required
string The billing name of the account. An account name is usually numeric, and must include any leading zeros.
lastSeenDeviceId
(query)
integer Only return devices with IMEIs larger than this value. Use 0 for the first request. If hasMoreData=true in the response, use the lastSeenDeviceId value from the response in the next request.
protocol
(query)
string Filter by the specified protocol of the distribution. Valid values include:
  • LWM2M
  • OMD-DM
  • HTTP
  • all

Header Parameters

The request header must contain a current ThingSpace authorization token and a current VZ-M2M-session token.

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization request header containing a valid Bearer token.
VZ-M2M-Token
required
string A valid session token returned by a Connectivity Management POST /session/login request.

Request Body

None.

Example Request

Request the list of devices for an account:

curl https://{{<hostUrl>}}/api/fota/v3/devices/$ACC  -H 'Authorization: Bearer $AUTH_TOKEN' -H 'VZ-M2M-Token: $M2M_TOKEN'

Success Responses

Status 200

A success response contains the account name and an array of device objects.

Parameter Name Data Type Description
accountName string The name (number) of the billing account.
hasMoreData Boolean Value="true" if there are more devices to retrieve.
lastSeenDeviceId integer If hasMoreData="true", use this value for the next request. 0 if hasMoreData=false.
maxPageSize integer Maximum number of results included in the response.
deviceList array   
   deviceId string The IMEI of the device.
   mdn string The MDN (phone number) of the device.
   model string FOTA model of the device.
   make string FOTA make of the device.
   firmware string The current firmware on the device.
   fotaEligible boolean Value="true" if the device software can be upgraded over the air using the Software Management Services API.
   appFotaEligible boolean Value="true" if the device software can be upgraded over the air using the v/3 Software Management Services APIs.
   licenseAssigned boolean Value="true" if an MRC license has been assigned to this device.
   protocol string The device management protocol supported by the device. Valid values include:
  • LWM2M
  • OMD-DM
  • HTTP
   softwareList array  
      name string The name of the software.
      version string Software version.
   filesList array  
      name string The name of the files.
createTime string($date-time) The date and time when the device is created.
upgradeTime string($date-time) The date and time when the device firmware or software is upgraded.
updateTime string($date-time) The system timestamp associated with this status.
refreshTime string($date-time) The date and time when the device is refreshed.

Example Success Response

This example response has been shortened to only show three devices, although there were over 1,000 devices in the original response, as indicated by hasMoreData = true.

{
    "accountName": "0642233522-00001",
    "maxPageSize": 1000,
    "hasMoreData": false,
    "lastSeenDeviceId": "0",
    "deviceList": [
        {
            "deviceId": "352656100378978",
            "mdn": "5779236395",
            "model": "NRF9160",
            "make": "NORDIC SEMICONDUCTOR ASA",
            "firmware": "fcb82d0b-2da7-4610-9107-49b0043983a8",
            "fotaEligible": false,
            "licenseAssigned": true,
            "status": "Active",
            "protocol": "LWM2M",
            "softwareList": [],
            "filesList": [],
            "createTime": "2020-06-15 05:29:25.352 +0000 UTC",
            "upgradeTime": "2021-07-30 06:10:01.33 +0000 UTC",
            "updateTime": "2021-09-24 07:10:19.396 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.181 +0000 UTC"
        },
        {
            "deviceId": "352656100388811",
            "mdn": "5247238567",
            "model": "NRF9160",
            "make": "NORDIC SEMICONDUCTOR ASA",
            "firmware": "e7f4d5d4-f607-43a6-b383-cfdb6d725c82",
            "fotaEligible": true,
            "licenseAssigned": true,
            "status": "Active",
            "protocol": "HTTP,LWM2M",
            "softwareList": [
                {
                    "name": "Sample OEM App",
                    "version": "nRF9160-2021-07-15-1.0",
                    "upgradeTime": "2021-07-15 16:47:52.43 +0000 UTC"
                },
                {
                    "name": "Sample OEM Application",
                    "version": "nRF9160-2021-08-13-1.0",
                    "upgradeTime": "2021-08-17 15:50:53.137 +0000 UTC"
                },
                {
                    "name": "Verizon MDM IoT Nordic nRF9160",
                    "version": "1.0.0.11",
                    "upgradeTime": "2021-07-15 14:28:08.138 +0000 UTC"
                }
            ],
            "filesList": [],
            "createTime": "2020-08-21 07:44:28.762 +0000 UTC",
            "upgradeTime": "2021-02-15 23:25:00.844 +0000 UTC",
            "updateTime": "2021-09-16 07:15:30.745 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.276 +0000 UTC"
        },
        {
            "deviceId": "354658090353977",
            "mdn": "5252177673",
            "model": "GM01Q",
            "make": "SEQUANS COMMUNICATIONS",
            "firmware": "SR1.2.0.0-10512",
            "fotaEligible": true,
            "licenseAssigned": false,
            "status": "Active",
            "protocol": "LWM2M",
            "softwareList": [],
            "filesList": [],
            "createTime": "2020-11-10 15:35:00.122 +0000 UTC",
            "upgradeTime": "1900-01-01 00:00:00 +0000 UTC",
            "updateTime": "2021-08-11 17:19:42.892 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.27 +0000 UTC"
        },
        {
            "deviceId": "860536040874085",
            "mdn": "5242785928",
            "model": "BG96",
            "make": "QUECTEL",
            "firmware": "BG96MAR04A04M1G",
            "fotaEligible": true,
            "licenseAssigned": true,
            "status": "Active",
            "protocol": "HTTP,LWM2M",
            "softwareList": [
                {
                    "name": "VZ_MDM_IOT",
                    "version": "0.14",
                    "upgradeTime": "2021-08-11 17:16:29.617 +0000 UTC"
                },
                {
                    "name": "configfile-Quectel_QUECTEL BG96_hello-world.txt",
                    "version": "1.0",
                    "upgradeTime": "2021-07-12 14:49:18.123 +0000 UTC"
                },
                {
                    "name": "configfile-Quectel_QUECTEL BG96_imei-mdn.txt",
                    "version": "1.0",
                    "upgradeTime": "2021-05-18 18:19:17.954 +0000 UTC"
                }
            ],
            "filesList": [],
            "createTime": "2020-09-16 23:26:39.542 +0000 UTC",
            "upgradeTime": "1900-01-01 00:00:00 +0000 UTC",
            "updateTime": "2021-09-08 07:56:50.251 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.3 +0000 UTC"
        },
        {
            "deviceId": "860536040885263",
            "mdn": "5263578386",
            "model": "BG96",
            "make": "QUECTEL",
            "firmware": "BG96MAR04A04M1G",
            "fotaEligible": true,
            "licenseAssigned": false,
            "status": "Active",
            "protocol": "HTTP,LWM2M",
            "softwareList": [
                {
                    "name": "VZ_MDM_IOT",
                    "version": "0.14",
                    "upgradeTime": "2021-08-11 17:16:29.603 +0000 UTC"
                }
            ],
            "filesList": [],
            "createTime": "2021-03-24 15:06:56.813 +0000 UTC",
            "upgradeTime": "1900-01-01 00:00:00 +0000 UTC",
            "updateTime": "2021-08-11 17:19:42.767 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.218 +0000 UTC"
        },
        {
            "deviceId": "862061049670002",
            "mdn": "7327121144",
            "model": "BG96",
            "make": "QUECTEL",
            "firmware": "BG96MAR02A10M1G",
            "fotaEligible": true,
            "licenseAssigned": false,
            "status": "Active",
            "protocol": "LWM2M",
            "softwareList": [],
            "filesList": [],
            "createTime": "0001-01-01 00:00:00 +0000 UTC",
            "upgradeTime": "1900-01-01 00:00:00 +0000 UTC",
            "updateTime": "2021-08-11 17:19:42.603 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.158 +0000 UTC"
        },
        {
            "deviceId": "864508030167099",
            "mdn": "5224361151",
            "model": "BG96-NA",
            "make": "QUECTEL",
            "firmware": "BG96NAMAR02A09M1G_O_BETA0423A",
            "fotaEligible": false,
            "licenseAssigned": true,
            "status": "Active",
            "protocol": "LWM2M",
            "softwareList": [],
            "filesList": [],
            "createTime": "0001-01-01 00:00:00 +0000 UTC",
            "upgradeTime": "1900-01-01 00:00:00 +0000 UTC",
            "updateTime": "2021-08-11 17:19:43.056 +0000 UTC",
            "refreshTime": "2021-09-29 07:43:08.314 +0000 UTC"
        }
    ]
}

Failure Responses

Status 400

All error messages are returned in this format:

 {
   "errorCode": "error code string",
   "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.