Suspend Service for Devices:

POST /devices/actions/suspend

Suspends service for one or more devices.

About Device States
Service Provisioning Rules
Activate Service for Devices
Restore Service for Devices
Deactivate Service for Devices

Uses and Requirements

You should be familiar with the M2M Service Provisioning Rules before suspending and restoring service for devices.

A suspended device continues to be billed in accordance with the contract terms associated with that device.

A device cannot be suspended indefinitely, and the CarrierService callback message for this API includes information about when the device will automatically return to the Active state due to reaching the maximum number of days allowed by the account contract. You can register for the ResumeTrackingNotification callback to be notified 7 days before a suspended device will automatically be returned to Active status.

You can specify a list of individual devices, or work with all devices in an account or device group. You can filter the account or device group by service plan or custom field value to limit the devices affected. ThingSpace sends an asynchronous CarrierService callback message for each device in the request when service for the device has been suspended, or if there was a problem and service could not be suspended.

ThingSpace sends an asynchronous CarrierService callback message for each device in the request when service for the device has been suspended, or if there was a problem and the suspension failed.

NOTE: Most accounts allow five service provisioning actions (Activate, Suspend, Restore, Deactivate) per line per day. For example, you can suspend service for a device and restore it in a 24-hour period, but you cannot activate service for a device, suspend the service and restore the service in the same 24-hour period. If you require the ability to perform up to 25 Suspend or Restore transactions per line per day, contact your account representative or customer support.

REST Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/suspend

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 to suspend. 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
accountName
optional
**Recommended
string The name of a billing account.
This parameter is only required if the UWS account used for the current API session has access to multiple billing 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.

customFields
optional*
array of customField objects Custom field names and values, if you want to only include devices that have matching values.
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.
devices
optional*
array of deviceIds objects The devices for which you want to suspend service, specified by device identifier. You only need to provide one identifier per device. Do not use accountName, groupName, or customFields if you use this parameter.
kind,
id

required for devices
strings 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
withBilling
optional*
boolean Set to "true" to suspend the device with billing, set to "false" to suspend the device without billing
groupName
optional*
string The name of a device group, if you want to suspend all 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.

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

Suspend service for single or multiple devices

Note: The devices array can hold one or multiple devices. withBilling, groupName and servicePlan are optional and do not have to be included in the request.

{
  "accountName": "0000123456-00001",
  "customFields": [
    {
      "key": "CustomField2",
      "value": "SuperVend"
    }
  ],
  "devices": [
    {
      "deviceIds": [
        {
          "id": "20-digit ICCID",
          "kind": "iccid"
        }
      ]
    }
  ],
  "withBilling": true,
  "groupName": "name of the group",
  "servicePlan": "service plan name"
} 

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 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. All of the callback messages will have the same requestId.

Example Success Response

{
  "requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}

Callback Response Parameters

Parameter Type Description
CallbackRequest CallbackRequest Wrapper element for all callback elements.
Username string The username defined when a URL was registered for the callback service, or an empty element if no username was defined.
Password string The password defined when a registered for the callback service, or an empty element if no password was defined.
RequestId string A unique string that matches the RequestId returned in the synchronous response to the original API request.

A separate callback message is sent for each device that matched the request criteria, indicating whether the operation succeeded for that device. All of the callback messages will have the same RequestId.

Device DeviceIdentifier The device that was changed.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN (10-digit phone number)
  • MEID (14-character alphanumeric)
  • MSISDN (1+ 10-digit phone number)
Identifier string The value of the device identifier.
Data CallbackData The data elements for this callback.
CarrierService CarrierServiceCallbackRequest The data returned from a CarrierService API request.
ChangeDeviceState ChangeDeviceStateResponse Contains child elements for successful ChangeDeviceState requests. Null for other CarrierService requests.
     
Suspend SuspendDeviceResponse Contains information about when the device will automatically return to the Active state due to reaching the maximum number of suspend days allowed by the account contract.
ExpectedResumeDate string The date that the device will auto-resume based on the suspend reason code, the account contract, and the number of days that it has already been suspended in the last 12 months.
MaxSuspendDaysAllowed int The number of suspension days associated with the suspend reason code.
NumDaysSuspendedLast12Months int The number of days that the MDN has been suspended in the past 12 months.
NumDaysSuspendAllowedCurrent12Months int The remaining number of days in the current 12-month period that the MDN is allowed to be suspended.
     
Comment string An informational message about the suspension, such as "Device Suspended - Applicable Charges Will Continue"
     
Status string Success or Failed.
CallbackCount integer The number of times this callback message has been sent.
MaxCallbackThreshold integer The maximum number of times this callback message will be sent if it is not correctly acknowledged.

Example Success Callback Response

{
  "username":"",
  "password":"",
  "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
  "deviceIds":[
    {
      "id":"14-character MEID",
      "kind":"MEID"
    },
    {
      "id":"10-digit MDN",
      "kind":"MDN"
    }
  ],
  "deviceResponse":{
    "suspendResponse":{
      "expectedResumeDate":"05/25/2018",
      "maxSuspendDaysAllowed":180,
      "numDaysSuspendedLast12Months":93,
      "numDaysSuspendAllowedCurrent12Months":87
    }
  },
  "comment":"Device Suspended - Applicable Charges Will Continue",
  "status":"Success",
  "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!