POST /devices/suspension/statusReturns service suspension information about one or more devices.
NOTE: This API method requires special account configuration, and it must be enabled for your organization before you can use it. You can contact Customer Support or your Verizon Sales Representative to learn about enabling this API method for your organization.
You should be familiar with the Service Provisioning Rules before suspending and restoring service for devices.
The returned information includes:
The information is returned in a callback response; you must register for the DeviceSuspensionStatus callback service to receive the responses.
POST https://thingspace.verizon.com/api/m2m/v1/devices/suspension/status
None.
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. |
The request body identifies the devices that you want to work with. You can either specify individual devices in the devices parameter, or you can use the filter parameters to work with devices that match the filter parameter values.
| Parameter Name | Data Type | Description |
|---|---|---|
| deviceIds optional |
array of deviceId objects | The devices that you want to include in the request, specified by device identifier. You only need to provide one identifier per device. NOTES Do not include this parameter if you want to use the filter parameter to select devices by metadata values. |
kind,
id required for deviceIds |
string | The type and value of the device identifier.
|
| filter optional |
list of filter parameters | Parameter names and values that you want to use to select the devices to work with, instead of specifying individual devices. If you specify multiple parameters, they are ANDed together so that only devices that match all of them are changed. |
groupName
|
string | The name of a device group, to only include devices in that group. |
servicePlan
|
string | The name of a service plan, to only include devices with that service plan. |
customFields
|
list of customfield objects | Custom field names and values, if you want to only include devices that have matching values. |
key
required for customFields filter |
string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
value
required for customFields filter |
string | The value of the custom field. |
| accountName optional *Recommended |
string | The name of a billing account. This value is required if you specify groupName as a filter.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. |
Request the current suspension status of two specific devices:
{
"deviceIds": [
{
"id": "A10085E5003861",
"kind": "meid"
},
{
"id": "A10085E5003186",
"kind": "meid"
}
]
}
Request the suspension status of all devices in an account that match a specified device group (for example, if you put all suspended devices in a specific device group):
{
"filter":
{
"groupName": "suspended devices"
},
"accountName": "1223334444-00001"
}
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. ThingSpace 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. Those are followed by a final callback message indicating that the request has been completed. All of the callback messages have the same requestId. |
{
"requestId": "904dcdc6-a590-45e4-ac76-403306f6d883"
}
{
"username": "",
"password": "",
"requestId": "904dcdc6-a590-45e4-ac76-403306f6d883",
"deviceResponse": {
"deviceSuspensionStatusResponse": [
{
"deviceIds": [
{
"id": "502209576627731",
"kind": "imei"
}
],
"state": "suspend",
"suspendDate": "2017-12-21 00:00:00",
"expectedResumeDate": "2018-03-20",
"daysRemainingAutoResume": "90",
"maxSuspendDaysAllowed": "180",
"numDaysSuspendedLast12Months": "0",
"numDaysSuspendAllowedCurrent12Months": "91",
"timesSuspendedLast12Months": "1"
},
{
"deviceIds": [
{
"id": "50220957662773100000",
"kind": "iccid"
}
],
"state": "suspend",
"suspendDate": "2017-12-21 00:00:00",
"expectedResumeDate": "2018-03-20",
"daysRemainingAutoResume": "90",
"maxSuspendDaysAllowed": "180",
"numDaysSuspendedLast12Months": "0",
"numDaysSuspendAllowedCurrent12Months": "91",
"timesSuspendedLast12Months": "1"
}
]
},
"callbackCount": 1,
"maxCallbackThreshold": 4
}
{
"username": "",
"password": "",
"requestId": "904dcdc6-a590-45e4-ac76-403306f6d883",
"deviceResponse": {},
"comment": "Request Completed Processing",
"callbackCount": 1,
"maxCallbackThreshold": 4
}
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.