Cancel Location

POST /devices/actions/cancellocation

Detaches a device from the Verizon Network.

NOTE: This API is currently in a limited Beta trial. Due to strict network limitations it is not available for general use. It might be enabled for a broader audience in the future..

Uses and Requirements

You can use this API for plan changes, when devices must download appropriate policies or settings to adjust the streaming speed.

Note the limitations on calls to this API:

  • This API only accepts one device per call. You will receive a synchronous error if you include more than one device in a call.
  • Hourly limit: a maximum of 20 total requests are processed per hour across all customers. The service accepts more than 20 requests per hour, but any requests after the maximum of 20 are placed in a queue for processing in subsequent hours. (Processing will occur within at the most, 24 hours.)

For Example: The API invocation is limited to 20 per hour (for both customer A and customer B). Any additional calls are queued for the next hour. So if customer A sends 100 calls, the 100th call will be processed and an eventual callback will be sent back to the customer in the fifth hour from the time the request was made.

You must register for the CarrierService callback service to receive the callback response.

Request Components

HTTP Request

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

Query Parameters

None.

Header Parameters

The request header must contain both 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 cancel or detach from the network. You must include the account name and 4G device identifiers (IMEI, ICCID, MDN, IMSI, EID, MSISDN).

NOTE: For successful cancel location, the device should have a valid MDN, MIN, and IMSI in the system.

Parameter Name Data Type Description
accountName
required
string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
devices
required
array of deviceIds objects

The 4G device you want to detach from the network, specified by device identifier.


Note: This API currently only supports a single device. If multiple devices are provided, you will receive an error.

kind,
id

required for devices
string The type and value of the device identifier.
  • IMEI - decimal, up to 16 digits
  • ICCID - decimal, up to 20 digits
  • MDN - decimal, 10 digits
  • IMSI
  • MSISDN
  • EID

Example Request Body

{
   "accountName":"0868924207-00001",
   "devices":[
      {
         "deviceIds":[
            {
               "id":"990000862474410",
               "kind":"imei"
            },
            {
               "id":"89658808121000111461",
               "kind":"iccid"
            }
         ]
      }
   ]
}

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 sends a separate callback message for each device that matches 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": "24da9f9a-d110-4a54-86b4-93fb76aab83c"
}

Failure Responses

Synchronous Failure Responses

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

Asynchronous Failure Responses

Error Code Error Message

DEVICE_NOT_FOUND

Device Not Found for the given identifier(s)

CLR_REQUEST_FAILED

Unfortunately your action has not completed. Please contact our Wireless Enterprise Help Desk @ 800-525-0481. Please provide the data you sent to Verizon and any data Verizon sent back to you such as the RequestID. Thank you.

Callback Parameters

You must register for the CarrierService callback service to receive the callback response.

Parameter Name Data Type Description
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 URL was registered for the callback service, or an empty element if no password was defined.
requestId string A 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 matches 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.
deviceResponse array of response objects CarrierService response object.
deviceResponse.cancelLocationResponse array of response objects CarrierService response object.
deviceResponse.cancelLocationResponse.accountName string The name of a billing account.
deviceResponse.cancelLocationResponse.deviceIds array of objects The 4G device you want to detach from the network, specified by device identifier.
kind,
id

required for devices
status string Status of the detach request. Valid values include:
  • Success (the request was queued to be sent)
  • <>
  • Failure
callbackCount integer Total number of callback requests.
maxCallbackThreshold integer Maximum number of callbacks allowed.

Example Callback Response

{
  "username" : "",
  "password" : "",
  "requestId" : "24da9f9a-d110-4a54-86b4-93fb76aab83c",
  "deviceResponse" : {
    "cancelLocationResponse" : {
      "accountName" : "0000000601-00005",
      "deviceIds" : [ {
        "id" : "0790745298",
        "kind" : "mdn"
      } ]
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}