Activate Service for Devices:

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.

 

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

Parameter Name Data Type Description
Parameter Namedevices
required		 Data Typearray of deviceIds objects DescriptionUp to 10,000 devices for which you want to activate service, specified by device identifier.
NOTE
Do not include this parameter if you want to use the deviceGroup parameter to activate all devices in a device group.
Parameter Name
kind,
id
required for devices
 Data Typestrings DescriptionThe type and value of the device identifier.
  • For 4G devices: IMEI (decimal, up to 16 digits) and ICCID (decimal, up to 20 digits), in that order
NOTE: If you are using a skuNumber to add 4G devices, you must provide only the ICCID identifier.
Parameter Name
ipAddress
optional
 Data Typestring DescriptionThe IP address to assign to the device in the following format: 1-255.0-255.0-255.0-255.
Parameter NameaccountName
optional
*Recommended		 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 NameservicePlan
required		 Data Typestring DescriptionThe service plan name to be assigned to all specified devices. Set this parameter to one of the code values returned by GET /plans/{accountname}. For Consumer eSIM for Enterprise, the value will be HybridESim.
Verizon Wireless provides service plan codes at the time of on-boarding and subsequently whenever there are any changes to the service plan.
NOTE: Any devices in the request that are not supported by the service plan will not activate.
Parameter NamemdnZipCode
required		 Data Typestring DescriptionThe Zip code of the location where the line of service will primarily be used, or a Zip code that you have been told to use with these devices. For accounts that are configured for geographic numbering, this is the ZIP code from which the MDN will be derived.
NOTE: If you include leadId in an activation request, you should set the mdnZipCode value to match the AddressZipCode value defined for the lead.
Parameter NamegroupName
optional		 Data Typestring DescriptionThis parameter can serve either of two purposes:
  • If you specify devices by ID in the devices parameters, this is the name of a device group that the devices should be added to. (They will be in the default device group if you don’t specify one.)
  • If you don’t specify individual devices with the devices parameter, you can provide the name of a device group to activate all devices in that group.
Parameter NameskuNumber
optional		 Data Typestring (20 characters max) DescriptionThe Stock Keeping Unit (SKU) of a 4G device type can be used with ICCID device identifiers in lieu of an IMEI when activating 4G devices. The SkuNumber will be used with all devices in the request, so all devices must be of the same type.
NOTE: When using SKU based activations, SIM OTA must be performed prior to performing maintenance transactions (Service Plan change, feature change, ICCID change.)
Parameter NamecarrierName
optional		 Data Typestring DescriptionThe carrier that will perform the activation. This parameter is only required if you have more than one carrier. If you have only one carrier you do not need to specify the carrierName; your carrier will be used by default.
Parameter NamecarrierIpPoolName
*optional		 Data Typestring DescriptionThe private IP pool (Carrier Group Name) from which your device IP addresses will be derived. If you do not include this element, the default pool will be used.
*This field is required if using the
ipAddress parameter.
Parameter NamecustomFields
optional		 Data Typelist of customField objects Description

A user-defined descriptive field, limited to 50 characters. 
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 Description

The value of the custom field. Allowed characters include:

  • Alphanumeric characters
  • / (forward slash)
  • SPACE
  • @ (at sign)
  • . (period)
  • , (comma)
  • : (colon)
  • - (hyphen)
  • _ (underscore)
  • ( (open parenthesis)
  • ) (close parenthesis)
  • [ (open bracket)
  • ] (close bracket)
  • # (number sign or hash)
Parameter NameleadId
optional		 Data Typestring DescriptionThe ID of a “Qualified” or “Closed - Won” VPP customer lead, which is used with other values to determine MDN assignment, taxation, and compensation. Use GET /leads to get a list of valid Lead IDs.
LeadId is not allowed for non-VPP activations.
NOTE: If you include leadId in an activation request, you should set the mdnZipCode value to match the zip value in the address returned for the lead.
Parameter NamecostCenterCode
optional		 Data Typestring DescriptionA string to identify the cost center that the device is associated with. This value will be applied to all devices in the activation request. Valid values are any string of up to 36 alphanumeric characters, space, dash, exclamation point, and pound sign.
Parameter NamepublicIpRestriction
optional		 Data Typestring DescriptionFor devices with static IP addresses on the public network, this specifies whether the devices have general access to the Internet. Valid values are “restricted” or “unrestricted”.
  • Unrestricted = The device will have full access to the Internet.
  • Restricted = The device will have access to any content provided by Verizon Wireless but will be restricted from access to the Internet.
If left blank, the device will get the default value set for the account. Public network devices with dynamic IP addresses are always unrestricted.
Parameter NameprimaryPlaceOfUse
optional		 Data Typeobject DescriptionThe customer name and the address of the device’s primary place of use. Leave these fields empty to use the account profile address as the primary place of use. These values will be applied to all devices in the activation request.
If the account is enabled for non-geographic MDNs and the device supports it, the primaryPlaceOfUse address will also be used to derive the MDN for the device.
The Primary Place of Use location may affect taxation or have other legal implications. You may want to speak with legal and/or financial advisers before entering values for these fields.
NOTE: primaryPlaceOfUse cannot be used with leadId. VPP partners should enter a leadId value for a customer lead, and the AddressZipCode in the lead record will be used for taxation. VPP partners can use primaryPlaceOfUse fields without a leadId to associate customer-specific data with devices.
Parameter Name
customerName
required for primaryPlaceOfUse
 Data Typeobject DescriptionThe customer name to be used for line usage taxation.
Parameter Name
title
optional for customerName
 Data Typestring DescriptionAn optional title for the customer, such as “Mr.” or “Dr.”
Parameter Name
firstName
required for customerName
 Data Typestring DescriptionThe customer’s first name. Valid values are any string of up to 20 alphanumeric characters, space, dash, exclamation point, and pound sign.
Parameter Name
middleName
optional for customerName
 Data Typestring DescriptionThe customer’s middle name.
Parameter Name
lastName
required for customerName
 Data Typestring DescriptionThe customer’s last name. Valid values are any string of up to 25 alphanumeric characters, space, dash, exclamation point, and pound sign.
Parameter Name
suffix
optional
 Data Typestring DescriptionAn optional suffix for the customer name, such as “Jr.” or “III.”
Parameter Name
address
required for primaryPlaceOfUse
 Data Typeobject DescriptionThe customer address for the line’s primary place of use, for line usage taxation.
Parameter Name
addresLine1
required for address
 Data Typestring DescriptionThe street address for the line’s primary place of use. This must be a physical address for taxation; it cannot be a P.O. box.
Parameter Name
addressLine2
optional for address
 Data Typestring DescriptionOptional additional street address information.
Parameter Name
city
required for address
 Data Typestring DescriptionThe city for the line’s primary place of use.
Parameter Name
state
required for address
 Data Typestring DescriptionThe two-letter abbreviation of the state for the line’s primary place of use. To see examples of the two-letter codes (i.e. TX for Texas), please see the Wikipedia page on ISO-3166-2:US
Parameter Name
zip
required for address
 Data Typestring DescriptionThe Zip code for the line’s primary place of use.
Parameter Name
zip4
optional
 Data Typestring DescriptionThe ZIP+4 for the line’s primary place of use.
Parameter Name
country
required for address
 Data Typestring DescriptionEither “US” or “USA” for the country of the line’s primary place of use.
Parameter Name
phone
optional
 Data Typestring DescriptionA phone number where the customer can be reached.
Parameter Name
phoneType
optional
 Data Typestring DescriptionA single letter to indicate the customer phone type:
  • M = Mobile
  • H = Home
  • F = Fax
  • W = Work/Business
  • P = Pager
Parameter Name
emailAddress
optional
 Data Typestring DescriptionAn email address for the customer.

Response Parameters

Parameter Type Description
ParameterRequestId Typestring Description

A unique string that associates the request with the results that are sent via a callback service.

The ThingSpace Platform will send 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 will have the same RequestId.

Callback Response Parameters

Parameter Type Description
ParameterCallbackRequest TypeCallbackRequest DescriptionWrapper element for all callback elements.
ParameterUsername Typestring DescriptionThe username defined when a URL was registered for the callback service, or an empty element if no username was defined.
ParameterPassword Typestring DescriptionThe password defined when a registered for the callback service, or an empty element if no password was defined.
ParameterRequestId Typestring DescriptionA 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.
ParameterDevice TypeDeviceIdentifier DescriptionAn identifier of the device that was activated. This element may appear multiple times, for different types of device identifier.
ParameterKind Typestring DescriptionThe type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
ParameterIdentifier Typestring DescriptionThe value of the device identifier.
ParameterData TypeCallbackData DescriptionThe data elements for this callback.
ParameterCarrierService TypeCarrierServiceCallbackRequest DescriptionThe data returned from a CarrierService API request.
ParameterChangeDeviceState TypeChangeDeviceStateResponse DescriptionContains child elements for successful ChangeDeviceState requests. Null for other CarrierService requests.
ParameterActivate TypeActivateDeviceResponse DescriptionContains information about the activated device for successful ChangeDeviceState - Activate requests. Null for other ChangeDeviceState callback messages.
ParameterDeviceIdentifierCollection TypeDeviceIdentifier DescriptionThe device identifiers for the device. All known identifiers that are assigned to the device are included in the callback.
ParameterKind Typestring DescriptionThe type of the device identifier. Valid types are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
ParameterIdentifier Typestring DescriptionThe value of the device identifier.
ParameterIpAddress Typestring DescriptionThe IP address of the activated device.
ParameterState Typestring DescriptionThe two-letter state abbreviation (i.e. TX for Texas) for the activated device.
ParameterServicePlan Typestring DescriptionThe service plan name that is assigned to the device. For Consumer eSIM for Enterprise, the value will be HybridESim.
ParameterFeatureCodes TypeFeatureCode DescriptionThe feature codes for the device. Feature codes are only available with the Verizon Wholesale network.
ParameterDeviceCredential TypeDeviceCredential Description 
ParameterUsername Typestring Description 
ParameterPassword Typestring Description 
ParameterStateName Typestring Description 
ParameterServiceName Typestring Description 
ParameterStatus Typestring DescriptionSuccess or Failed.
ParameterCallbackCount Typeinteger DescriptionThe number of times this callback message has been sent.
ParameterMaxCallbackThreshold Typeinteger DescriptionThe maximum number of times this callback message will be sent if it is not correctly acknowledged.

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

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 will send 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 will have the same requestId.

Example Success Response

{
  "requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}
Parameter Name Data Type Description
Parameter NamerequestId Data Typestring Description

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 match 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

 
Parameter NamedeviceIds Data TypeArray DescriptionArray of kind, id objects
Parameter Namekind,
id		 Data Typestrings DescriptionThe type and value of the device identifier.

For 4G devices, IMEI (decimal, up to 16 digits) and ICCID (decimal, up to 20 diigts), in that order
Parameter NamedeviceResponse Data Typearray of activateResponse objects DescriptionResponse object for CarrierService callbacks
Parameter NameactivateResponse Data Typearray of activateResponse objects DescriptionResponse object for CarrierService callbacks
Parameter Name  Data Type  Description 
Parameter NameactivateResponse.deviceIds Data Typestring DescriptionThe type and value of the device identifier.
Parameter NameipAddress Data Typestring DescriptionThe IP address assigned to the device.
Parameter Namestate Data Typestring DescriptionThe device state. Valid values include: Activate, Suspend, Deactive, Pre-active
Parameter NameservicePlan Data Typestring DescriptionThe service plan name assigned to all specified devices. For Consumer eSIM for Enterprise, the value will be HybridESim.
Parameter NamefeatureCodes Data Type  DescriptionNot used for this service.
Parameter NamedeviceCredential Data Typearray DescriptionArray of username and password objects.
Parameter NamedeviceCredential.username Data Typestring DescriptionDevice user name.
Parameter NamedeviceCredential.password Data Typestring DescriptionDevice password
Parameter Namestatus Data Typestring DescriptionThe current status of the callback response. Valid values include:
Pending - The request is still being processed.
Success - The request has completed processing with no errors.
Failed - There were errors that prevented the request from being completed.
Parameter NamecallbackCount Data Typeinteger DescriptionTotal number of callback requests
Parameter NamemaxCallbackThreshold Data Typeinteger DescriptionMaximum number of callbacks allowed.

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

Parameter Name Data Type Description
Parameter NamerequestId Data Typestring Description

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.

 
Parameter NameniddResponse Data TypeniddResponse object DescriptionResponse object for NiddService callbacks.
Parameter NameniddResponse.niddConfigResponse.accountName Data Typestring DescriptionThe 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.
Parameter NameniddResponse.niddConfigResponse.reason Data Typestring Description

Only appears when status is “ConfigCreationFailed." Valid values include:

  • Internal error

  • NIDD configuration already exists

  • NIDD configuration not available.
Parameter NameniddResponse.niddConfigResponse.deviceIds Data Typearray of device identifier objects DescriptionAll the non-null device identifiers for the device:
  • kind: the type of the identifier (IMEI, IMSI, MDN, MIN, MSISDN, ICCID, EID)
  • id: a device identifier value    
Parameter Namestatus Data Typestring Description

Nidd config response status. Valid values include:

  • ConfigCreated
  • ConfigCreationFailed
Parameter NamecallbackCount Data Typeinteger DescriptionTotal number of callback requests.
Parameter NamemaxCallbackThreshold Data Typeinteger DescriptionMaximum number of callbacks allowed.

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"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

Try It Out!