Retrieve Device Suspension Status

Get Device Suspension Status:
POST /devices/suspension/status

Returns 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.

Contents

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

Query Parameters

None.

Header Parameters

The request header must contain the current session token.

Parameter Name Data Type Description
VZ-MC-Token
required
string A valid session token returned by POST /session/login.

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
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 15 digits
  • MDN - decimal, 10 digits
  • MEID - hexadecimal, 14 characters
  • 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 specifyng individual devices. If you specify multiple parameters, they will be ANDed together so that only devices that match all of them will be 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
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.

Example Request Body

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"
}

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 will send 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 will be followed by a final callback message indicating that the request has been completed. All of the callback messages will have the same requestId.

Example Success Response

{
  "requestId": "904dcdc6-a590-45e4-ac76-403306f6d883"
}

Example Suspension Status Callback Message

{
  "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
}

Example Request Completed Callback Message

{
  "username": "",
  "password": "",
  "requestId": "904dcdc6-a590-45e4-ac76-403306f6d883",
  "deviceResponse": {},
  "comment": "Request Completed Processing",
  "callbackCount": 1,
  "maxCallbackThreshold": 4
}

Failure Responses

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!