Deactivate Service for Devices:

POST /devices/actions/deactivate

Deactivates service for one or more devices.

NOTE: Deactivating service for a device may result in an early termination fee (ETF) being charged to the account, depending on the terms of the contract with Verizon. If your contract allows ETF waivers and you want to use one for a particular deactivation, set the EtfWaiver value to True.

See also:
About Device States
Service Provisioning Rules
Activate Service for Devices
Suspend Service for Devices
Restore Service for Devices

Uses and Requirements

You should be familiar with the M2M Service Provisioning Rules before deactivating devices.

You can specify a list of individual devices, or work with all devices in an account or device group. You can limit the devices affected by applying service plan or custom field filters.

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

Request Components

HTTP Request

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

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
Parameter NameAuthorization
required		 Data Typestring DescriptionHTTP Authorization bearer token.
Parameter NameVZ-M2M-Token
required		 Data Typestring DescriptionA valid session token returned by POST /session/login.
Parameter NameContent-Type
required		 Data Typestring DescriptionMust be application/json.

Request Body

The request body identifies the devices to deactivate. 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
Parameter Namedevices
optional*		 Data Typearray of deviceIds objects DescriptionThe devices for which you want to deactivate service, specified by device identifier. You only need to provide one identifier per device. Do not use  groupName, or customFields if you use this parameter.
Parameter Name
kind,
id
required for devices
 Data Typestring DescriptionThe 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
Parameter NameaccountName
required
 Data Typestring DescriptionThe 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.
Parameter NamegroupName
optional*		 Data Typestring DescriptionThe name of a device group, if you want to deactivate all devices in that group.
Parameter NameservicePlan
optional*		 Data Typestring DescriptionThe name of a service plan, if you want to only include devices that have that service plan.
Parameter NamecustomFields
optional*		 Data Typelist of customField objects DescriptionCustom field names and values, if you want to only include devices that have matching values.
Parameter Name
key
required for customFields
 Data Typestring DescriptionThe name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Parameter Name
value
required for customFields
 Data Typestring DescriptionThe 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.
Parameter NamereasonCode
required		 Data Typestring DescriptionCode identifying the reason for the deactivation. Currently the only valid reason code is “FF”, which corresponds to General Admin/Maintenance.
Parameter NameetfWaiver
optional		 Data Typeboolean DescriptionFees may be assessed for deactivating Verizon Wireless devices, depending on the account contract. The etfWaiver parameter waives the Early Termination Fee (ETF), if applicable.
  • When etfWaiver is set to true, the fee is waived, assuming that waivers are allowed in the contract and they have not all been used.
  • When etfWaiver is set to false, the fee is not to be waived via this mechanism. If you use a business process where you deactivate devices and apply ETF waivers through some other mechanism, you may continue to follow that process,and simply set etfWaiver to false.
If your account does not have ETF waivers at all, set etfWaiver to False. The Deactivate request fails if you set etfWaiter to true and there are no waivers available based on the contract.
Parameter NamedeleteAfterDeactivation
optional		 Data Typeboolean DescriptionSpecifies whether you want to delete the device from the database upon deactivation.

* 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

Deactivate a single device

{
      "devices": [
        {
          "deviceIds": [
            {
              "id": "20-digit ICCID",
              "kind": "iccid"
            }
          ]
        }
      ],
      "reasonCode": "FF",
      "etfWaiver": true,
      "deleteAfterDeactivation": true
    }

Deactivate service for two 4G devices

The accountName is only needed if the user has access to more than one account.

{
      "accountName": "0000123456-00001",
      "devices": [
        {
          "deviceIds": [
            {
              "id": "20-digit ICCID",
              "kind": "iccid"
            }
          ]
        },
        {
          "deviceIds": [
            {
              "id": "20-digit ICCID",
              "kind": "iccid"
            }
          ]
        }
      ],
      "reasonCode": "FF",
      "etfWaiver": true,
      "deleteAfterDeactivation": true
    }

Deactivate all devices in a specified device group that have a specified service plan

{
      "accountName": "0000123456-0001",
      "groupName": "southwest",
      "servicePlan": "service plan name",
       "reasonCode": "FF",
       "etfWaiver": false,
       "deleteAfterDeactivation": true
    }

Success Responses

Status 200

Parameter Name Data Type Description
Parameter NamerequestId Data Typestring DescriptionA 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":"15-digit IMEI",
          "kind":"imei"
        },
        {  
          "id":"20-digit ICCID",
          "kind":"iccid"
        }
      ],
      "deviceResponse":{  
        "deactivateResponse":{  
          "deactivated":true
        }
      },
      "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!