Retrieve the Global Device List

POST /v2/devices/actions/list

Retrieves a list of all devices on an account.

Bulk operation: Supported (The callback would be one for each profile). Bulk operations have a limit of 10,000 requests.

eSIM profiles: Both Verizon US and Global.

Contents

Request Components

Header Parameters

The request header must set the content-type to JSON, contain a current ThingSpace authorization token and a current VZ-M2M session token. For more details on how to get these tokens, visit  Getting Started.

Parameter Name Data Type Description
Authorization
required
string

HTTP Authorization bearer token:
Authorization: Bearer {token}

VZ-M2M-Token
required
string

A valid session token:
VZ-M2M-Token: {M2Mtoken}

Content-Type
required
string

Must be application/json:
Content-Type: application/json

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v2/devices/actions/list

Request Parameters

Parameter Data Type Description
accountName
required
string The name of the account.
provisioningStatusFilter string

Filter by provisioning status. Values include:

  • DEACTIVATED
  • ACTIVATED
  • DEACTIVE
  • ACTIVE
  • SUSPEND
  • PENDING_ACTIVATION
  • PENDING_DEACTIVATION
  • PRE_ACTIVE
  • ACTIVATION_READY
  • INVENTORY
  • PURGED
  • REPLACED
  • RETIRED
  • TEST_READY
  • UNKNOWN
profileStatusFilter
string

Filter by profile status. Values include:

  • DISABLE
  • ENABLE
  • DOWNLOAD_DISABLE
  • DOWNLOAD_ENABLE
  • NOT_DOWNLOADED
  • UNKNOWN
  • DELETE
carrierName string The carrier providing cellular network access. This is set to "Verizon Wireless" for US profiles and removed for Global profiles. 
devices
array

An array of deviceIds. Each deviceId will contain:

  • id
  • kind
   id
string The numeric ID of the device.
   kind
string

The the type of device ID represented by the ID value. This could be:

  • imei
  • iccid
  • mdn
  • eid

Request Body

Example request:

{
   "accountName":"0000123456-00001",
   "provisioningStatusFilter":"ACTIVE",
   "profileStatusFilter":"UNKNOWN",
   "carrierNameFilter":"Verizon Wireless",
   "deviceFilter":[
      {
         "id":"15-digit IMEI",
         "kind":"imei"
      },
      {
         "id":"32-digit EID",
         "kind":"eid"
      }
   ]
}

Success Response

Status 200

A successful response shows a system generated request ID to track the request.

Example Response:

{
  "requestId": "d1f08526-5443-4054-9a29-4456490ea9f8"
}

Callback Response

These endpoints send responses asynchronously. In order to read the results a callback is required.To learn more about callback, please visti About Callback Services.

Example callback response:

{
   "requestId":"d1f08526-5443-4054-9a29-4456490ea9f8",
   "deviceResponse":{
      "getDeviceListWithProfiles":{
         "complete":true,
         "total":1,
         "results":[
            {
               "accountName":"0000123456-00001",
               "profiles":[
                  {
                     "carrierInformation":{
                        "carrierName":"VerizonWireless",
                        "servicePlan":"Name of the service plan"
                     },
                     "billingCycleEndDate":"2021-08-31T11:59:59.0000000Z",
                     "connected":false,
                     "createdAt":"2021-08-23T22:14:54.7700000Z",
                     "profileIdentifiers":[
                        {
                           "kind":"iccid",
                           "identifier":"20-digit ICCID"
                        },
                        {
                           "kind":"imsi",
                           "identifier":"15-digit IMEI"
                        },
                        {
                           "kind":"mdn",
                           "identifier":"10-digit MDN"
                        },
                        {
                           "kind":"msisdn",
                           "identifier":"1 + 10-digit MDN"
                        }
                     ],
                     "extendedAttributes":[
                        {
                           "key":"PrimaryPlaceOfUseFirstName",
                           "value":"First name"
                        },
                        {
                           "key":"PrimaryPlaceOfUseLastName",
                           "value":"Surname"
                        },
                        {
                           "key":"PrimaryPlaceOfUseSuffix",
                           "value":"Jr."
                        },
                        {
                           "key":"PrimaryPlaceOfUseAddressLine1",
                           "value":"line 1 of address"
                        },
                        {
                           "key":"PrimaryPlaceOfUseAddressLine2",
                           "value":"line 2 of address"
                        },
                        {
                           "key":"PrimaryPlaceOfUseCity",
                           "value":"city of address"
                        },
                        {
                           "key":"PrimaryPlaceOfUseState",
                           "value":"state of address"
                        },
                        {
                           "key":"PrimaryPlaceOfUseCountry",
                           "value":"country of address"
                        },
                        {
                           "key":"PrimaryPlaceOfUseZipCode",
                           "value":"5 digit zip code of address"
                        },
                        {
                           "key":"PrimaryPlaceOfUseZipCode4",
                           "value":"+4 digit of zip code"
                        },
                        {
                           "key":"PrimaryPlaceOfUseCBRPhone",
                           "value":"10-digit phone number"
                        },
                        {
                           "key":"PrimaryPlaceOfUseEmailAddress",
                           "value":"abc@gmail.com"
                        }
                     ],
                     "groupNames":[
                        "Default: 0000123456-00001"
                     ],
                     "lastActivationBy":"user name",
                     "lastActivationDate":"2021-08-23T22:14:56.0000000Z",
                     "lastConnectionDate":"",
                     "provisioningStatus":"active",
                     "profileStatus":"unknown"
                  }
               ],
               "extendedAttribute":[
                  {
                     "key":"AccountNumber",
                     "value":"0000123456-00001"
                  },
                  {
                     "key":"LeadId",
                     "value":"LEAD"
                  },
                  {
                     "key":"CustomerAddressLine1",
                     "value":"line 1 of address"
                  },
                  {
                     "key":"CustomerAddressLine2",
                     "value":"line 2 of address"
                  },
                  {
                     "key":"CustomerAddressCity",
                     "value":"city of address"
                  },
                  {
                     "key":"CustomerAddressState",
                     "value":"state of address"
                  },
                  {
                     "key":"ServiceZipCode",
                     "value":"5 digit zip code"
                  },
                  {
                     "key":"DeviceId",
                     "value":"user assigned ID"
                  }
               ],
               "deviceIdentifiers":[
                  {
                     "id":"15-digit IMEI",
                     "kind":"imei"
                  },
                  {
                     "id":"32-digit EID",
                     "kind":"eid"
                  }
               ]
            }
         ]
      }
   }
}

Callback Parameters

Parameter Data Type Description
requestId string The requestId being viewed. This is a system generated value from the request above.
deviceResponse
object Contains the getDeviceListWithProfiles.
   getDeviceListWithProfiles array Shows if the request is complete, how many records matched the request and the results of the request.
      accountName string The name of the account being queried.
      profiles array The profile information of the account and the devices matching the request.
      carrierInformation array The carrier name and service plan name for the profile.
         carrierName string The name of the carrier providing cellular network access.
         servicePlan string The service plan subscribed to. This drives billing rates for usage.
      billingCycleEndDate string($date-time) The timestamp used for the end of a billing period.
      connected boolean
  • True - Device is connected
  • False - Device is not connected
      createdAt string($date-time) The timestamp of the profile's creation.
      profileIdentifiers
array

The ID information for the device(s) in the profile. Each will contain:

  • identifier
  • kind
         identifier
string The numeric ID of the device.
         kind
string

The the type of device ID represented by the ID value. This could be:

  • imei
  • iccid
  • mdn
  • eid
      extendedAttributes array This is the priamry name, address, phone number and email address of the account holder.
      groupNames  array

Contains the names of the groups the profile is associated with.

      lastActivationBy string The user name that made the most recent change.
      lastActivationDate string($date-time) The timestamp of the most recent change.
      provisioningStatus string

Status of provisioning. Will be one of the following:

  • Active
  • Pending
  • Disable
  • Unknown
   extendedAttribute string

Alternate contact information for the account holder.

   deviceIdentifiers
array

An array of device identifiers being matched by the request. Each device identifier will contain:

  • id
  • kind
      id
string The numeric ID of the device.
      kind
string

The the type of device ID represented by the ID value. This could be:

  • imei
  • iccid
  • mdn
  • eid

Failure Responses

All error responses will be in the following format

{
  "errorCode": "The 3-digit HTML error code",
  "errorMessage": "string"
}