Restore Service for Devices:

POST /devices/actions/restore

Restores service to one or more suspended devices.

Restore Service for Devices:
POST /devices/actions/restore

Uses and Requirements

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

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.

The M2M Platform sends an asynchronous CarrierService callback message for each device in the request when service for the device has been restored, or if there was a problem and service could not be restored.

The M2M Platform sends another asynchronous NiddService callback message for each NB-IoT device in the request when NIDD Config for the device has been enabled again.

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.

Request

HTTP Request

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

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 Parameters

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
groupName optional*	string	The name of a device group, if you want to restore 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.

Example Request Body

Note: The devices array can hold one or multiple devices. 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"
        }
      ]
    }
  ],
  "groupName": "name of the group",
  "servicePlan": "service plan name"
}

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.

Restore	RestoreDeviceResponse	Empty in callback messages for ChangeDeviceState - Restore requests.


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":"user name",
  "password":"password",
  "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
  "deviceIds":[  
    {  
      "id":"990003420535573",
      "kind":"imei"
    },
    {  
      "id":"89148000000800784259",
      "kind":"iccid"
    }
  ],
  "deviceResponse":{  
    "restoreResponse":{  
       "restored":true
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

niddService Callback Parameters

Parameter Name	Data Type	Descrpition
requestId	string	A unique string that associates the request with the NIDD information 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.
niddResponse.niddConfigResponse	array	Response object for NiddService callbacks
niddConfigResponse.accountName	string	The name of a billing account, which is usually in the format of 10 digits, a hyphen, and then five more digits. Must include any leading zeros.
niddConfigResponse.deviceId	array of device Identifiers	The type and value of the device identifier. Kind: the type of identifier (IMEI, MSISDN, or External ID) id: a device identifier value
niddConfigResponse.reason	string	Reason the status is “ConfigCreationFailed” or “ConfigTerminated”. Valid values include: Internal error NIDD configuration already exists NIDD configuration not available. Only appears if status is “ConfigCreationFailed”.
status	string	Nidd config response status. Valid values include: ConfigCreated ConfigCreationFailed
callbackCount	integer	Total number of callback requests.
maxCallbackThreshold	integer	Maximum number of callbacks allowed.

Example niddConfig Success Callback Response

{
  "username" : "user name",
  "password" : "password",
  "requestId" : "595f5c44-c31c-4552-8670-020a1545a84d",
  "niddResponse" : {
    "niddConfigResponse" : {
      "accountName" : "9992330389-00001",
      "deviceIds" : [ {
        "id" : "99962019000000000000000000000002",
        "kind" : "EID"
      }, {
        "id" : "9996201900000000000345",
        "kind" : "IMEI"
      } ]
    }
  },
  "status" : "ConfigCreated",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

Example niddConfig Failure Callback Response


  "username" : "user name",
  "password" : "password",
  "requestId" : "595f5c44-c31c-4552-8670-020a1545a84d",
  "niddResponse" : {
    "niddConfigResponse" : {
      "accountName" : "9992330389-00001",
      "reason" : "Not CatM or NBIoT Device",
      "deviceIds" : [ {
        "id" : "99962019000000000000000000000002",
        "kind" : "EID"
      }, {
        "id" : "9996201900000000000345",
        "kind" : "IMEI"
      } ]
    }
  },
  "status" : "ConfigFailed",
  "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!