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.
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.
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.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.POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/list
None.
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 . |
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 will return all devices that the session user account has access to. A request with just an accountName will return all devices in that account. A request with an accountName and any combination of other parameters will include 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.
|
accountName optional |
string | The billing account for which a list of devices will be returned. If you don’t specify an accountName, the list will include all devices to which you have access. An account name is usually numeric, and must include any leading zeros. |
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:
|
filter.deviceIdentifierFilters.kind required for deviceIdentifierFilters |
string | The type of the device identifier to match. Valid types of identifiers are:
|
contains required for filter |
string | The string to match against device identifiers. The string can be as short as one character, but more characters will 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.
|
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. |
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
}
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 will be an empty array.
Parameter Name | Data Type | Description |
---|---|---|
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 will be one of these values:
|
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:
|
deviceIds.id | string | The value of the device identifier. |
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. |
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:
|
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 | 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 | 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 | accountNumber |
extendedAttributes.value | string | The billing account number that the device is associated with. It is usually the same as the AccountName. |
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. |
{
"devices": [
{
"accountName": "0245078689-00001",
"billingCycleEndDate": "2016-02-09T19:00:00-05:00",
"carrierInformations": [
{
"carrierName": "Verizon Wireless",
"servicePlan": "Tablet5GB",
"state": "active"
}
],
"connected": false,
"createdAt": "2015-12-17T13:53:21-05:00",
"customFields": [
{
"key": "CustomField1",
"value": ""
},
{
"key": "CustomField2",
"value": ""
},
{
"key": "CustomField3",
"value": ""
},
{
"key": "CustomField4",
"value": "Galactic Heavy Industries"
},
{
"key": "CustomField5",
"value": ""
}
],
"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": "PromoCodes",
"value": ""
},
{
"key": "PromotionStartDate",
"value": ""
},
{
"key": "PromotionScheduledEndDate",
"value": ""
},
{
"key": "LeadId",
"value": ""
},
{
"key": "CustomerName",
"value": ""
},
{
"key": "CustomerAddressLine1",
"value": ""
},
{
"key": "CustomerAddressLine2",
"value": ""
},
{
"key": "CustomerAddressCity",
"value": ""
},
{
"key": "CustomerAddressState",
"value": ""
},
{
"key": "CustomerAddressZipCode",
"value": ""
},
{
"key": "ServiceZipCode",
"value": ""
},
{
"key": "SkuNumber"
},
{
"key": "CostCenterCode",
"value": ""
},
{
"key": "PreIMEI"
},
{
"key": "PreSKU"
},
{
"key": "smsrOid",
"value": ""
},
{
"key": "ProfileStatus",
"value": ""
},
{
"key": "AccountNumber",
"value": "0245078689-00001"
}
],
"groupNames": [
"NCW Devices"
],
"ipAddress": "100.127.22.52",
"lastActivationBy": "Zaffod Beeblebrox",
"lastActivationDate": "2015-12-17T13:56:13-05:00",
"lastConnectionDate": "2015-12-17T14:12:36-05:00"
}
],
"hasMoreData":false
}
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!