Retrieve Information about Devices:

POST /devices/actions/list

Returns information about a single device or information about all devices that match the given parameters. Returned information includes device provisioning state, service plan, MDN, MIN, and IP address.

Contents

Uses and Requirements

If you request information for more than one device, each response includes up to 2000 devices, sorted by device ID or chronologically by the date the devices were added.

  • To get devices sorted by device ID (recommended), include the largestDeviceIdSeen parameter in the request. If the request matches more than 2000 devices (hasMoreData = true), you can send additional requests, adjusting the largestDeviceIdSeen value each time to start where the previous request finished.
  • To get devices sorted by the date they were added to the account, do not include the largestDeviceIdSeen parameter in the request. If the request matches more than 2000 devices (hasMoreData = true), you can send additional requests, adjusting the earliest timestamp in each request to start where the previous request finished.

Request Components

HTTP Request

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

Resource Path and Query Parameters

None.

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

In the request body you can either specify one device in the deviceId parameter, or you can use the other parameters to request a list of devices that match the parameter values. A request with no parameters returns all devices that the session user account has access to. A request with just an accountName returns all devices in that account. A request with an accountName and any combination of other parameters includes only those devices that match all criteria.

Parameter Name Data Type Description
deviceList
optional
array An array of deviceId objects to use when requesting information from multiple devices.
deviceId
optional
deviceId object An identifier for a single device.
deviceId.kind,
deviceId.id
required for deviceId
string The type and value of the device identifier.
  • ESN - decimal, 11 digits
  • EID - decimal, 32 digits
  • ICCID - decimal, up to 20 digits
  • IMEI - decimal, up to 16 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 hex digits
  • MSISDN - decimal, 11 digits
accountName
optional
*recommended
string The billing account for which a list of devices is returned. If you don’t specify an accountName, the list includes all devices to which you have access.
An account name is usually numeric, and must include any leading zeros.
* Coding the account number today prevents future code from breaking if you ever add a new sub-account.
filter
optional
filter object Find devices by partial identifier.
filter.deviceIdentifierFilters
required for filter
array Specify the kind of the device identifier, the type of match, and the string that you want to match.
filter.deviceIdentifierFilters.type
required for deviceIdentifierFilters
string The type of match that you’re looking for. Valid types of matches are:
  • contains - The string appears anywhere in the identifer
  • startswith - The identifer must start with the specified string
  • endswith - The identifier must end with the specified string
filter.deviceIdentifierFilters.kind
required for deviceIdentifierFilters
string The type of the device identifier to match. Valid types of identifiers are:
  • EID
  • ESN
  • ICCID
  • IMEI
  • MDN
  • MEID
  • MSISDN
contains
required for filter
string The string to match against device identifiers. The string can be as short as one character, but more characters narrow down the number of results and make it easier to find the device that you’re looking for.
groupName
optional
string Only include devices that are in this device group.
servicePlan
optional
string Only include devices that have this service plan.
currentState
optional
string The name of a device state, to only include devices in that state.
customFields
optional
list of customField objects Custom field names and values, if you want to only include devices that have matching values.
customFields.key
required for customFields
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
customFields.value
required for customFields
string The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported.
largestDeviceIdSeen
optional
long or string (Output buffering parameter) Only return information about devices that have an ID greater than this value. (These reference IDs are different from other device IDs, such as MEIDs, IMEIs, or ICCIDs.) Device IDs are returned as an extended attribute for each device.
  • For the first request, set this element to zero to retrieve the devices with the smallest IDs.
  • Check the hasMoreData value in the response.
  • If it’s “false” then you have received the complete list of devices.
  • If hasMoreData is “true,” send another request, putting the largest returned DeviceId value into this field. Continue sending requests with the largest DeviceId from the latest response until hasMoreData is “false.” This ensures that all devices are retrieved exactly once, with no gaps or overlaps in devices returned by multiple calls to this endpoint.
maxNumberOfDevices
optional
integer The maximum number of devices to be included in each response. The default value is 500, maximum value is 2000.
earliest
optional
string Only include devices that were added after this date and time.
latest
optional
string Only include devices that were added before this date and time.

Example Request Body

Request information for a single device

{
   "deviceId": {
      "id": "20-digit ICCID",
      "kind": "iccid"
   }
}

Request information for multiple devices

{
   "deviceList":[
      {
         "id":"10-digit MDN",
         "kind":"mdn"
      },
      {
         "id":"20-digit ICCID",
         "kind":"iccId"
      },
      {
         "id":"15-digit IMEI",
         "kind":"imei"
      },
      {
         "id":"20-digit ICCID",
         "kind":"iccId"
      },
      {
         "id":"32-digit EID",
         "kind":"eid"
      }
   ]
} 

Request information for all devices that contain a specified string in their ICCIDs

{
  "accountName": "0786890242-00001",
  "filter": {
    "deviceIdentifierFilters": [
      {
        "kind": "iccid",
        "contains": "4259"
      }
    ]
  }
}

Request information for all devices in a device group that have a specified service plan, and sort the devices in the response by device ID

{
  "groupName": "southwest",
  "accountName": "0000123456-00001",
  "servicePlan": "m2m4G",
  "largestDeviceIdSeen": 0
}

Success Responses

Status 200 or 202

An array of objects for each device that matched the request, sorted by the date and time when each device was added to the account (the createdAt value). If no devices match the request, the response is an empty array.

Parameter Name Data Type Description
hasMoreData boolean False for a status 200 response.
True for a status 202 response, indicating that there is more data to be retrieved. Send another request, adjusting the largestDeviceIdSeen value or the earliest value in the request based on thedeviceId or createdAt value for the last device in the current response.
accountName string The billing account that the device is associated with.
billingCycleEndDate string The date that the device’s current billing cycle ends.
carrierInformations   The carrier information associated with the device.
carrierInformations.carrierName string The name of the carrier.
carrierInformations.servicePlan string The service plan that the device is assigned to.
NOTE: Service plan changes made through other tools are synchronized with the M2M Platform once per day, so you may need to wait up to 24 hours before those changes are returned by the API.
carrierInformations.state string The current state of the device, which are one of these values:
  • pre-active
  • active
  • deactive
  • suspend
  • pending resume
  • pending MDN change
  • pending PRL Update
  • pending preactive
  • pending activation
  • pending deactivation
  • pending suspend
  • pending service plan change
  • pending ESN / MEID change
  • pending account update
connected boolean True if the device is connected; false if it is not.
createdAt dateTime The date and time that the device was added to the system.
customFields   The custom fields and values that have been set for the device.
customFields.key string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
customFields.value string The value of the custom field.
deviceIds   All identifiers for the device.
deviceIds.kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • EID
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
deviceIds.id string The value of the device identifier.
extendedAttributes   Any extended attributes for the device, as Key and Value pairs. The pairs listed below are returned as part of the response for a single device, but are not included if the request was for information about multiple devices.
extendedAttributes.key string PromoCodes
extendedAttributes.value string A comma-separated list of the names of any promotional codes active for the device.
A value of “Data=Machine to Machine 60KB” would indicate that a promotional code is associated with the device that allows for 60KB of complementary data traffic. Here are some example values:
  • Data=Machine to Machine 60KB
  • SMS=Machine to Machine 15 SMS
  • Voice=Machine to Machine 5 MOU
extendedAttributes.key string Additional extendedAttributes containing place-of-use information.
PrimaryPlaceofUseFirstName
PrimaryPlaceofUseMiddleName
PrimaryPlaceofUseLastName
PrimaryPlaceofUseSuffix
PrimaryPlaceofUseAddressLine1
PrimaryPlaceofUseAddressLine2
PrimaryPlaceOfUseCity
PrimaryPlaceofUseState
rimaryPlaceOfUseCountry
PrimaryPlaceofUseZipCode
PrimaryPlaceOfUseZipCode4
PrimaryPlaceOfUseCBRPhone
PrimaryPlaceOfUseCBRPhoneType
PrimaryPlaceOfUseEmailAddress
extendedAttributes.key string accountNumber
extendedAttributes.value string The billing account number that the device is associated with. It is usually the same as the AccountName.
extendedAttributes.key string smsrOid
extendedAttributes.value string For eUICC devices, the Object ID of the SMSR system.
extendedAttributes.key string profileStatus
extendedAttributes.value string

For eUICC devices, the current status of the local profile. Null for all other devices.

eUICC profiles can be in the following states:

  • DOWNLOAD_ENABLE: Profile was downloaded and enabled.
  • DOWNLOAD_DISABLE: Profile was downloaded successfully but not enabled (also known as Disabled)
  • ENABLE: Profile was downloaded and enabled in two steps: a) first it was only downloaded but not enabled–status would be DOWNLOAD_DISABLE, b) second, it was enabled–status would be ENABLE
  • DISABLE: Profile was downloaded but disabled because a profile DISABLE API call was explicitly made to disable a profile that was both downloaded and enabled.
  • DELETE: Profile was deleted from the device.
  • NOT DOWNLOADED: An operation profile does not exist; the device is still on bootstrap.
extendedAttributes.key string PromotionStartDate
extendedAttributes.value string($date-time) The date that the promotion started, such as

2021-05-31T00:00:00Z
extendedAttributes.key string PromotionScheduledEndDate
extendedAttributes.value string The date that the promotion is scheduled to end, such as

2021-06-31T00:00:00Z
extendedAttributes.key string Additional extendedAttributes containing lead-related information for devices provisioned under VPP partner accounts:
LeadId
CustomerName
CustomerAddressLine1
CustomerAddressLine2
CustomerAddressCity
CustomerAddressState
CustomerAddressZipCode
ServiceZipCode
extendedAttributes.value string The values for the VPP partner account for the current device.
extendedAttributes.key string SkuNumber
extendedAttributes.value string The SKU for the current device. This value object is not returned for null values.
extendedAttributes.key string CostCenterCode
extendedAttributes.value string The cost center code for the current device.
extendedAttributes.key string PreIMEI
extendedAttributes.value string The IMEI of the device prior to the most recent SIM OTA activation. This value object is not returned for null values.
extendedAttributes.key string PreSKU
extendedAttributes.value string The SKU of the device prior to the most recent SIM OTA activation. This value object is not returned for null values.
extendedAttributes.key string SIMOTADate
extendedAttributes.value string($date-time) The date and time of the most recent SIM OTA activation. The SIMOTADate key and value objects are not returned for null values.
extendedAttributes.key string RoamingStatus
extendedAttributes.value string True if the device is currently roaming.
extendedAttributes.key string LastRoamingStatusUpdate
extendedAttributes.value string The time and date that the last roaming status was updated.
extendedAttributes.key string RoamingCountry
extendedAttributes.value string The name of a country if RoamingStatus=true, or empty if false.
extendedAttributes.key string deviceId
extendedAttributes.value string A unique internal value for this device. This value is only present in the response when the request included largestDeviceIdSeen.
extendedAttributes.key string ServiceNameN
extendedAttributes.value string The name of the services and states active for a device in an account that has custom services and states. StateName1 belongs to ServiceName1, and StateName2 belongs to ServiceName2, etc.
extendedAttributes.key string StateNameN
extendedAttributes.value string The name of the services and states active for a device in an account that has custom services and states. StateName1 belongs to ServiceName1, and StateName2 belongs to ServiceName2, etc.
extendedAttributes.key string ServiceStateStartDateN
extendedAttributes.value string($date-time) Service start date, such as 2021-05-24T19:20:05Z. ServiceStateStartDate1 belongs to ServiceName1 and StateName1 , and ServiceStateStartDate2 belongs to ServiceName2 and StateName 2, etc.,
extendedAttributes.key string subscriptionTypeCodeN
extendedAttributes.value string Valid values include the following:
  • GPX - Garage Swap with Pre-Paid External Subscriber
  • GPV - Garage Swap with Postpaid Verizon Subscriber
extendedAttributes.key string subscriptionTypeDescN
extendedAttributes.value string A description of the the subscriptionTypeCode.
extendedAttributes.key string stageStateChangeReasonCodeN
extendedAttributes.value string State change reason codes. Valid values include the following:
  • OTE - On Demand Trial End
  • SUB - Ended Subscription
  • EXT - Expired Trial
  • APT - Activated Post Paid WiFi Service
  • APP - Activated Prepaid WiFi Service
extendedAttributes.key string stageStateChangeReasonDescN
extendedAttributes.value string A description of the stageStateChangeReasonCode.
groupNames string The device group that the device belongs to.
ipAddress string The IP address of the device.
lastActivationBy string The user who last activated the device.
lastActivationDate string The date and time that the device was last activated.
lastConnectionDate string The most recent connection date and time.

Example Success Response

{
   "hasMoreData":false,
   "devices":[
      {
         "accountName":"0000123456-00001",
         "billingCycleEndDate":"2020-05-09T20:00:00-04:00",
         "carrierInformations":[
            {
               "carrierName":"Verizon Wireless",
               "servicePlan":"m2m4G",
               "state":"active"
            }
         ],
         "connected":false,
         "createdAt":"2019-08-07T10:42:15-04:00",
         "deviceIds":[
            {
               "id":"10-digit MDN",
               "kind":"mdn"
            },
            {
               "id":"15-digit IMEI",
               "kind":"imei"
            },
            {
               "id":"15-digit IMEI",
               "kind":"imei"
            },
            {
               "id":"20-digit ICCID",
               "kind":"iccId"
            },
            {
               "id":"1+10-digit MSISDN",
               "kind":"msisdn"
            },
            {
               "id":"10-digit MDN",
               "kind":"mdn"
            }
         ],
         "extendedAttributes":[
            {
               "key":"PrimaryPlaceOfUseTitle"
            },
            {
               "key":"PrimaryPlaceOfUseFirstName",
               "value":"John"
            },
            {
               "key":"PrimaryPlaceOfUseMiddleName",
               "value":""
            },
            {
               "key":"PrimaryPlaceOfUseLastName",
               "value":"Doe"
            },
            {
               "key":"PrimaryPlaceOfUseSuffix"
            },
            {
               "key":"PrimaryPlaceOfUseAddressLine1"
            },
            {
               "key":"PrimaryPlaceOfUseAddressLine2"
            },
            {
               "key":"PrimaryPlaceOfUseCity"
            },
            {
               "key":"PrimaryPlaceOfUseState"
            },
            {
               "key":"PrimaryPlaceOfUseCountry"
            },
            {
               "key":"PrimaryPlaceOfUseZipCode"
            },
            {
               "key":"PrimaryPlaceOfUseZipCode4"
            },
            {
               "key":"PrimaryPlaceOfUseCBRPhone"
            },
            {
               "key":"PrimaryPlaceOfUseCBRPhoneType"
            },
            {
               "key":"PrimaryPlaceOfUseEmailAddress"
            },
            {
               "key":"AccountNumber",
               "value":"0000123456-00001"
            },
            {
               "key":"SmsrOid"
            },
            {
               "key":"ProfileStatus"
            },
            {
               "key":"PromoCodes",
               "value":""
            },
            {
               "key":"PromotionStartDate",
               "value":""
            },
            {
               "key":"PromotionScheduledEndDate",
               "value":""
            },
            {
               "key":"LeadId"
            },
            {
               "key":"CustomerName"
            },
            {
               "key":"CustomerAddressLine1"
            },
            {
               "key":"CustomerAddressLine2"
            },
            {
               "key":"CustomerAddressCity"
            },
            {
               "key":"CustomerAddressState"
            },
            {
               "key":"CustomerAddressZipCode"
            },
            {
               "key":"ServiceZipCode",
               "value":"07920"
            },
            {
               "key":"SkuNumber",
               "value":"4GTESTDEVICE"
            },
            {
               "key":"CostCenterCode",
               "value":""
            },
            {
               "key":"PreIMEI",
               "value":"15-digit IMEI"
            },
            {
               "key":"PreSKU",
               "value":"4GTESTDEVICE"
            },
            {
               "key":"SIMOTADate",
               "value":"2021-05-31T00:00:00Z"
            },
            {
               "key":"RoamingStatus",
               "value":"Roaming"
            },
            {
               "key":"LastRoamingStatusUpdate",
               "value":"2021-06-01T19:20:05Z"
            },
            {
               "key":"RoamingCountry",
               "value":"India"
            },
           {
               "key":"ServiceName1",
               "value":"Name of the service"
            },            
            {
               "key":"StateName1",
               "value":"Name of the service Inservice"
            },                        
            {            
               "key":"ServiceStateStartDate1",
               "value":"2021-05-24T19:20:05Z"
            },
            {
               "key":"SubscriptionTypeCode1",
               "value":"GPX"
            },
            {
               "key":"SubscriptionTypeDesc1",
               "value":"Swap with Pre-Paid Subscriber"
            },            
            {
               "key":"StageStateChangeReasonCode1",
               "value":""
            },                        
            {            
               "key":"StageStateChangeReasonDesc1",
               "value":""
            }
         ],
"groupNames":[
            "southwest"
         ],
         "ipAddress":"0.0.0.0",
         "lastActivationBy":"Joe Q Public",
         "lastActivationDate":"2019-08-07T10:42:34-04:00",
         "lastConnectionDate":"2020-03-12T04:23:37-04:00"
      }
   ]
}

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.

Try It Out!