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 40 total requests are processed per hour across all customers. The service accepts more than 40 requests per hour, but any requests after the maximum of 40 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 40 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 third 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.

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.

Example Request Body

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

Success Responses

Status 200

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

Callback Parameters

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

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
}