Standard APIsConnectivity ManagementAPI EndpointsDevice ManagementList Current Devices PRL Version
API Reference
Retrieve Device PRL Information
Uses and Requirements
The information is returned in a callback response; calls to this API return an error if the account doesn’t have a registered URL for the DevicePRLInformation callback service.
NOTE: This API is not supported for 4G devices.
Request Components
HTTP Request
POST https://thingspace.verizon.com/api/m2m/v1/devices/prl/actions/list
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
The request body identifies the devices for which you want the PRL version. You can either list individual devices, or work with all devices in an account or device group, and optionally filter by service plan or custom field values.
| Parameter Name | Data Type | Description |
|---|---|---|
| deviceIds optional* | array of deviceId objects | The devices for which you want the PRL version, specified by device identifier. You only need to provide one identifier per device. Do not use any of the other parameters if you specify device IDs. |
| kind, id required for deviceIds | string | The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MEID - hexadecimal, 14 characters MSISDN - decimal, 11 digits |
| accountName optional *Recommended | string | The name of a billing account. This parameter is only required if you are passing groupName and the UWS account used for the current API session has access to multiple billing accounts, because the same device group name can exist in multiple accounts. An account name is usually numeric, and must include any leading zeros. *By coding for the account number today, you prevent future code from breaking if you ever add a new sub-account. |
| groupName optional* | string | The name of a device group, if you want to only include devices in that group. |
| servicePlan optional* | string | The name of a service plan, if you want to only include devices that have that service plan. |
| customFields optional* | string | The names and values of custom fields, if you want to only include devices that have matching custom fields. |
| key required for customFields | string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
| 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. |
- You can either specify up to 10,000 individual devices with the devices parameter, or you can use any combination of groupName, servicePlan, and customFields to run the request on all devices that match all criteria.
Example Request Body
Request the PRL version of two specific devices:
{
"deviceIds": [
{
"id": "A10085E5003861",
"kind": "meid"
},
{
"id": "A10085E5003186",
"kind": "meid"
}
]
}
Request the PRL version of all devices in an account that match a specified device group and service plan:
{
"groupName": "West Region",
"accountName": "101234-0001",
"servicePlan": "3G 2MB"
}Success Responses
Status 200
| Parameter Name | Data Type | Description |
|---|---|---|
| requestId | string | A unique string that associates the request with the results that are sent via a callback service. The ThingSpace Platform sends a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All of the callback messages have the same requestId. |
Example Success Response
{
"requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}Example Success Callback Response
{
"username":"",
"password":"",
"requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
"deviceIds":[
{
"id":"A100001F702731",
"kind":"MEID"
},
{
"id":"9083074681",
"kind":"MDN"
}
],
"deviceResponse":{
"prlInformationResponse": {
"prlVersion": "523310"
},
},
"status":"Success",
"callbackCount":1,
"maxCallbackThreshold":4
}