AddDevices

Adds up to 200 new devices to the account, without provisioning lines of service for them. Use this request if you want devices to appear in lists you retrieve using Wireless Network Services APIs or ThingSpace Manage or the M2M Management Center portal before you are ready to activate service for them.

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

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 will be in the "Pre-Active" provisioning state. They will 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 added with AddDevices, use the ChangeDeviceState - Activate request.

Request Parameters

Parameter Type Description
DeviceToAdd
required
DeviceIdentifierCollection A list of 1-200 devices to add, specified by device identifier.

For each device in DeviceToAdd, use this structure of nested parameters:

<DeviceIdentifierCollection>
  <DeviceIndentifiers>
    <DeviceIdentifier>
      <Kind></Kind>
      <Identifier></Identifier>
    </DeviceIdentifier>
  </DeviceIndentifiers>
</DeviceIdentifierCollection>
Kind
required for DeviceToAdd
strings The type 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.

Identifier
required for DeviceToAdd
string The value of the device identifier.
AccountName
optional
string

The billing account to which the devices will be 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 will be added to that account even if you don't include this parameter.

An account name is usually numeric, and must include any leading zeros.

DeviceGroupNames
optional
string The name of a device group to add the devices to when they are added to the account.
CustomFields
optional
CustomFieldObj The names and values for any custom fields that you want to set for the devices as they are added to the account.
Name
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.

Allowed characters in custom field values:

  • Alphanumeric characters
  • / (forward slash)
  • SPACE
  • @ (at sign)
  • . (period)
  • , (comma)
  • : (colon)
  • - (hyphen)
  • _ (underscore)
  • ( (open parenthesis)
  • ) (close parenthesis)
  • [ (open bracket)
  • ] (close bracket)
  • # (number sign or hash)
State
required
string The initial service state for the devices. The only valid state is "Preactive".
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 will be 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 eUICC devices
string The Object ID of the SMSR system.

Response Parameters

Parameter Type Description
ReturnMessage Message For each device in the request, contains device identifiers and a success or failure message.
Device DeviceIdentifierCollection Device identifiers for the current device.
DeviceIdentifiers DeviceIdentifier One or more identifiers for the device.
Kind string The type of the device identifier:
  • ESN (decimal)
  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MEID (hexadecimal)
  • MIN
Identifier string The value of the device identifier.
Message string The success message or error message for the current device. When a failure occurs, the returned message will be one of the Device Service Errors.

Example SOAP Request

Add Two 3G Devices

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:v2="http://nphase.com/unifiedwebservice/v2"
 xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
 xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"
 xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Header>
    <v2:token>03e0385d-9649-4d88-a977-6a0596cc38ab</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:AddDevices>
      <v2:Input>
        <nph:DeviceToAdd>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>esn</nph1:Kind>
                <nph1:Identifier>09613597668</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>esn</nph1:Kind>
                <nph1:Identifier>09613489171</nph1:Identifier>
              </nph1:DeviceIdentifier>
              <nph1:DeviceIdentifier>
                <nph1:Kind>meid</nph1:Kind>
                <nph1:Identifier>A1000001999998</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
        </nph:DeviceToAdd>
        <nph:State>Preactive</nph:State>
      </v2:Input>
    </v2:AddDevices>
  </soapenv:Body>
</soapenv:Envelope>

Add Two 4G Devices with SKU

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:v2="http://nphase.com/unifiedwebservice/v2"
 xmlns:nph="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService"
 xmlns:nph1="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common"
 xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
  <soapenv:Header>
    <v2:token>03e0385d-9649-4d88-a977-6a0596cc38ab</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:AddDevices>
      <v2:Input>
        <nph:DeviceToAdd>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>ICCID</nph1:Kind>
                <nph1:Identifier>89148000000800784258</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>ICCID</nph1:Kind>
                <nph1:Identifier>89148000000800784260</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
        </nph:DeviceToAdd>
        <nph:State>Preactive</nph:State>
        <nph:SkuNumber>7640111922001</nph:SkuNumber>
      </v2:Input>
    </v2:AddDevices>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
   <AddDevicesResponse xmlns="http://nphase.com/unifiedwebservice/v2">
    <Output xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService">
      <a:ReturnMessage>
       <a:Messages>
        <a:Device xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
          <b:DeviceIdentifiers>
           <b:DeviceIdentifier>
            <b:Kind>esn</b:Kind>
            <b:Identifier>09613597668</b:Identifier>
           </b:DeviceIdentifier>
          </b:DeviceIdentifiers>
        </a:Device>
        <a:Message>Success</a:Message>
       </a:Messages>
       <a:Messages>
        <a:Device xmlns:b="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.Common">
          <b:DeviceIdentifiers>
           <b:DeviceIdentifier>
            <b:Kind>esn</b:Kind>
            <b:Identifier>09613489171</b:Identifier>
           </b:DeviceIdentifier>
           <b:DeviceIdentifier>
            <b:Kind>meid</b:Kind>
            <b:Identifier>A1000001999998</b:Identifier>
           </b:DeviceIdentifier>
          </b:DeviceIdentifiers>
        </a:Device>
        <a:Message>Success</a:Message>
       </a:Messages>
      </a:ReturnMessage>
    </Output>
   </AddDevicesResponse>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram