Add Devices to an Account:

POST /devices/actions/add

Adds up to 200 new devices to an account, without activating lines of service for them. Use this resource if you want to manage some device settings before you are ready to activate service for the devices.

NOTE: This is not a required or recommended step. You do not need to add devices to an account before activating them. Verizon recommends using /devices/actions/activate to add devices and activate service for them in a single step.

See also:
Activate Devices

Uses and Requirements

The devices that you want to add must already exist in the Verizon Device Management Database (DMD). After you add devices, they are in the “Pre-Active” provisioning state in the ThingSpace Platform. They do not appear in your Verizon Wireless billing account or in the My Business Account or Verizon Enterprise Center portals.

To activate lines of service for devices after you have added them, see /devices/actions/activate.

Request

HTTP Request

 

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

 

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

Parameter Name Data Type Description
devicesToAdd
required
array of deviceIds objects The devices that you want to add.
kind,
id

required for devices
strings The type and value of the device identifier.
  • For 2G or 3G devices: ESN (decimal, 11 digits) or MEID (hexadecimal, 14 digits)
  • For 4G devices: IMEI (decimal, up to 16 digits) and ICCID (decimal, up to 20 digits), in that order
  • For eUICC devices: IMEI and EID (the request must also include smsrOid)
NOTE: If you are using a skuNumber to add 4G devices, you must provide only the ICCID identifier.
accountName
optional
*Recommended
string The billing account to which the devices are added. If you have access to multiple billing accounts, then you must specify an account. If you have access to only one account, the devices are added to that account even if you don’t include this parameter.
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.

state
required
string The initial service state for the devices. The only valid state is “Preactive.”
groupName
optional
string The name of a device group to add the devices to. They are added to the default device group if you don’t include this parameter.
customFields
optional
list of customField objects The names and values for any custom fields that you want set for the devices as they are added to the account.
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.
skuNumber
optional
string The Stock Keeping Unit (SKU) number of a 4G device type with an embedded SIM. Can be used with ICCID device identifiers in lieu of an IMEI when adding 4G devices. The SkuNumber is used with all devices in the request, so all devices must be of the same type.
NOTE: Only 4G devices with embedded SIMs can be added by SKU at this time.
smsrOid
required for devices with EUICC
string The Object ID of the SMSR system.

Example Request Body

Add two 4G devices:

 

{
      "accountName": "0868924207-00001",
      "customFields": [
        {
          "key": "CustomField2",
          "value": "SuperVend"
        }
      ],
       "devicesToAdd":[  
          {  
             "deviceIds":[  
                {  
                   "kind":"imei",
                   "id":"990013907835573"
                },
                {  
                   "kind":"iccid",
                   "id":"89141390780800784259"
                }
             ]
          },
          {  
             "deviceIds":[  
                {  
                   "kind":"imei",
                   "id":"990013907884259"
                },
                {  
                   "kind":"iccid",
                   "id":"89141390780800735573"
                }
             ]
          }
       ],
      "groupName": "West Region",
      "state": "preactive"
    }
    

 

Success Responses

Status 200

Contains the device identifiers and a success or failure response for each device in the request.

Parameter Name Data Type Description
deviceIds   Identifiers for the device.
kind
string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MEID (hexadecimal)
id
string The value of the device identifier.
response string The success message or error message for the current device.

Example Success Response

 

[
      {
        "deviceIds": [
          {
            "id": "89148000000800784259",
            "kind": "iccid"
          }
        ],
        "response": "Success"
      }
    ]
    

 

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!