POST /devices/actions/activate

Activates service for one or more devices so that they can send and receive data. If the devices do not already exist in the account and the activation request fails for some reason, this request may add them to the ThingSpace list as deactivated.

See also:
About Device States
Service Provisioning Rules
Retrieve Service Plans
Retrieve Account Leads
Add Devices
Suspend 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 activating devices. The devices that you want to add must already exist in Verizon Mobile Device Management (MDM).

You can specify a list of individual 4G devices, or work with all 4G devices in an account or device group. If the devices have previously been added to the account and have custom field values, you can use a custom field filter to only activate devices with specific values.

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

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

NOTE: Devices will be assigned non-geographic MDNs if the account and device both support this feature.

NOTE: There is a limit on the number of Activate requests that can be submitted every minute. To avoid encountering this limit (100 requests per minute) when you need to activate a large number of devices, put multiple devices in each request. You can submit up to 10,000 devices per request.

Best Practices

The Best Practice for activation is to verify that the devices are ready to be activated before sending a POST /devices/actions/activate request:

• Send a POST /devices/actions/list request to check the state of the devices before service activation.
  • New devices that have not been added to the account should return “DeviceNotFound” (which is good).
  • Devices that have already been added to the account must be in the Preactive or deactive state before service can be activated.
• Send a POST /devices/actions/activate request to activate service for the device.
• Register a URL to receive CarrierService callback messages and run a callback listening service at that URL. ThingSpace will send a callback message when each device has been fully activated, or if there was a problem and the device was not activated.

Activations usually complete within a few minutes.* If you receive a general error in a callback, you should open a support ticket. Other errors indicate a problem with the request parameters, so please verify the device identifiers and other values and then resend the request.

In addition to receiving CarrierService callback messages, You can use POST /devices/actions/list to check the status of the device and POST /devices/history/actions/list to see details of completed activation requests.

* Activations may take up to 12 hours to complete if there are major network or technology updates occurring at the same time.

For more tips and information on best practices for activation, please visit Best Practices for Activation.

Request Components

HTTP Request

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

Resource Path and 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.

Request Body

The request body identifies the devices that you want to activate, and other information about the activation. You can either list individual devices, or work with all devices in a device group and/or all devices that have specific custom field values.

Response Parameters

Callback Response Parameters

Request Examples

Request to activate two 4G devices and set IP Address:

{
  "devices":[
    {
      "deviceIds":[
        {
          "kind":"imei",
          "id":"990013907835573"
        },
        {
          "kind":"iccid",
          "id":"89141390780800784259"
        }
      ]
      "ipAddress" : "100.127.22.33"
    },
    {
      "deviceIds":[
        {
          "kind":"imei",
          "id":"990013907884259"
        },
        {
          "kind":"iccid",
          "id":"89141390780800735573"
        }
      ]
      "ipAddress" : "100.127.22.34"
    }
  ],
  "accountName":"0868924207-00001",
  "servicePlan":"the service plan name",
  "mdnZipCode":"98801",
  "customFields":[
    {
      "key":"CustomField2",
      "value":"SuperVend"
    }
  ],
  "groupName":"4G West",
  "primaryPlaceOfUse":{
    "customerName":{
      "title":"President",
      "firstName":"Zaffod",
      "lastName":"Beeblebrox"
    },
    "address":{
      "addressLine1":"1600 Pennsylvania Ave NW",
      "city":"Washington",
      "state":"DC",
      "zip":"20500",
      "country":"USA"
    }
  }
}

Request to activate 4G devices using SKU and ICCID:

{
   "devices":[
      {
         "deviceIds":[
            {
               "kind":"iccid",
               "id":"89141390780800784259"
            }
         ]
      },
      {
         "deviceIds":[
            {
               "kind":"iccid",
               "id":"89141390780800735573"
            }
         ]
      }
   ],
   "accountName":"0868924207-00001",
   "servicePlan":"the service plan name",
   "mdnZipCode":"98801",
   "skuNumber":"7640111922001"
}

Success Responses

Status 200

Example Success Response

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

Example Success CarrierService Callback Response

{
  "username":"",
  "password":"",
  "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
  "deviceIds":[
    {
      "id":"352452060026934",
      "kind":"IMEI"
    }
  ],
  "deviceResponse":{
    "activateResponse":{
      "deviceIds":[
        {
          "id":"5096306081",
          "kind":"mdn"
        },
        {
          "id":"311480104434320",
          "kind":"imsi"
        },
        {
          "id":"89148000001024124378",
          "kind":"iccId"
        },
        {
          "id":"13122379508",
          "kind":"msisdn"
        },
        {
          "id":"2345958183",
          "kind":"min"
        }
      ],
      "ipAddress":"10.224.48.88",
      "state":"Active",
      "servicePlan":"the service plan name",
      "featureCodes":[],
      "deviceCredential":{
        "username":"5096306081@vzw3g.com",
        "password":"5096306081"
      }
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

niddConfig Callback Parameters

Example niddConfig Success Callback Response

{
  "username" : "user",
  "password" : "pwd",
  "requestId" : "3c5eef41-011c-4c20-8780-f4031180141b",
  "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",
  "password" : "pwd",
  "requestId" : "4c5eef41-011c-2c20-8780-f4031180141b",
  "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"
}