Standard APIsGlobal IoT OrchestrationAPI EndpointsRetrieve the Global Device List
API Reference
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.
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 callbacks, please visit 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 primary 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"
}