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
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 ICCID - decimal, up to 20 digits IMEI - decimal, up to 15 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

You can only specify one device by deviceId. To get information on multiple devices, you must either send multiple requests or match the devices by filter, groupName, servicePlan, currentState, etc.

{
   "deviceId": {
      "id": "89148000000800139708",
      "kind": "iccid"
   }
}

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": "0786890242-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 In addition, 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.
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 15 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. Nil for all other devices.
extendedAttributes.key	string	PromotionStartDate
extendedAttributes.value	string	The date that the promotion started, such as 4/3/2015 12:00:00 AM
extendedAttributes.key	string	PromotionScheduledEndDate
extendedAttributes.value	string	The date that the promotion is scheduled to end, such as 10/31/2016 12:00:00 AM
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	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.
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":"0786890242-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":"5086303377",
               "kind":"mdn"
            },
            {
               "id":"311880082140479",
               "kind":"imsi"
            },
            {
               "id":"990083420535573",
               "kind":"imei"
            },
            {
               "id":"89148000800800784259",
               "kind":"iccId"
            },
            {
               "id":"15096383371",
               "kind":"msisdn"
            },
            {
               "id":"5086308842",
               "kind":"min"
            }
         ],
         "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":"0342080330-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":"3568210767040101"
            },
            {
               "key":"PreSKU",
               "value":"4GTESTDEVICE"
            },
            {
               "key":"SIMOTADate",
               "value":"3/11/2020 5:01:22 AM"
            },
            {
               "key":"RoamingStatus",
               "value":"Roaming"
            },
            {
               "key":"LastRoamingStatusUpdate",
               "value":"2/22/2020 8:29:42 AM"
            },
            {
               "key":"RoamingCountry",
               "value":"India"
            }
         ],
         "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!