## Get Device Suspension Status ### Uses and Requirements You should be familiar with the Service Provisioning Rules before suspending and restoring service for devices. The returned information includes: - the current state of the device (active, suspended, etc.) - the date the device was suspended - the date that it will be returned automatically to Active status (based on the maximum number of suspend days allowed) - the number of suspension days associated with the suspend reason code that was used when the device was suspended - the number of days that the MDN has been suspended in the past 12 months - the remaining number of days in the current 12-month period that the MDN is allowed to be suspended The information is returned in a callback response; you must register for the DeviceSuspensionStatus callback service to receive the responses. ### Request HTTP Request [POST https://thingspace.verizon.com/api/m2m/v1/devices/suspension/status](/docs/standard-apis/connectivity-management/api-endpoints/device-management/get-device-service-suspension-status/getdeviceservicesuspensionstatus) 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 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 | |:----------------------------------------:|:---------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | **accountName** *(required)* | string | The numeric name of a billing account, and must include any leading zeros. | | **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. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MSISDN - decimal, 11 digits | | **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** *(optional)* | string | The name of a device group, to only include devices in that group. | | **servicePlan** *(optional)* | string | The name of a service plan, to only include devices with that service plan. | | **customFields** *(optional)* | 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)* | ### Example Request Body Request the current suspension status of two specific devices: ```json { "deviceIds": [ { "id": "15-digit IMEI", "kind": "imei" }, { "id": "15-digit IMEI", "kind": "imei" } ] } ``` 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): ```json { "filter": { "groupName": "suspended devices" }, "accountName": "1223334444-00001" } ``` ### 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. 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. | ### Example Success Response ```json { "requestId": "904dcdc6-eeee-ffff-gggg-403306f6d883" } ``` ### Example Suspension Status Callback Message ```json { "username": "", "password": "", "requestId": "904dcdc6-eeee-ffff-gggg-403306f6d883", "deviceResponse": { "deviceSuspensionStatusResponse": [ { "deviceIds": [ { "id": "15-digit IMEI", "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": "20-digit ICCID", "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 } ``` Example Request Completed Callback Message ```json { "username": "", "password": "", "requestId": "904dcdc6-eeee-ffff-gggg-403306f6d883", "deviceResponse": {}, "comment": "Request Completed Processing", "callbackCount": 1, "maxCallbackThreshold": 4 } ```