ChangeDeviceState - Activate

Activates service for one or more 4G devices. If the devices do not already exist in the account, this API method adds them before activation.

Uses and Requirements

You should be familiar with the M2M Service Provisioning Rules before activating devices. The devices that you want to work with must have been registered with Verizon by the manufacturer.

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.

The ThingSpace Platform 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.

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

Best Practices

The Best Practice for activation is to verify that the devices are ready to be activated before calling the ChangeDeviceState method:

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 GetDeviceInformation to check the status of the device and GetDeviceProvisioningHistory 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.

Request Parameters

Parameter Type Description
DeviceList
optional*
DeviceIdentifierCollection

A list of the devices for which you want to activate service, specified by device identifier. Do not pass DeviceGroupName or DeviceCustomFieldFilter if you use this parameter.

You can use GetDeviceList to get a list of all devices in the account.

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

<DeviceIdentifierCollection>
  <DeviceIndentifiers>
    <DeviceIdentifier>
      <Kind></Kind>
      <Identifier></Identifier>
    </DeviceIdentifier>
  </DeviceIndentifiers>
  <IpAddress></IpAddress>
</DeviceIdentifierCollection>
Kind
required for DeviceList
string The type of the device identifier. Valid types of identifiers are:

  • ICCID (up to 20 digits)
  • IMEI (up to 16 digits)
  • MDN
  • MSISDN

For 4G devices, you must specify both the IMEI and the ICCID within separate DeviceIdentifier elements, in that order.

Identifier
required for DeviceList
string The value of the device identifier.
IpAddress
optional for DeviceList
string

The IP address to assign to the device (in the following format: 1-255.0-255.0-255.0-255).

DeviceGroupName
optional*
string The name of a device group if you want to activate all devices in that group.
AccountName
optional*
string

The name of a billing account, which can serve one of two purposes:

  • This parameter is required to activate new devices that have not already been added to the account. You must also include the DeviceList parameter to identify the devices.
  • If you are passing DeviceGroupName to activate all devices in a device group that have already been added to an account, and you have access to multiple accounts, this parameter is required since the same device group name can exist in multiple accounts.

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

DeviceCustomFieldFilter
optional*
CustomFieldFilterObject The names and values of custom fields, if you want to only include devices that have matching custom fields.
Name
required for DeviceCustomFieldFilter
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value
required for DeviceCustomFieldFilter
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)
Activate
required
ActivateDeviceRequest Activates the specified devices.
CarrierName
optional
string The carrier that will perform the activation. This element is only used for preprovisioning and when you have more than one carrier. If you have only one carrier you do not need to specify this element; your carrier will be used by default.
CarrierIpPoolName
optional*
string The pool 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.
ServicePlan
required
string

The service plan code that you want to assign to all specified devices. Set this parameter to one of the Code values returned by GetServicePlanList in the Account Service.

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.

FeatureCodesToAdd
optional
string Not currently in use.
FeatureCodesToRemove
optional
string Not currently in use.
EffectiveDate
optional
string Not currently in use.
MdnZipCode
required
string

The 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. You can use GetLeadInformation to get a list of all leads, which includes the address information.

MdnNpaNxx
optional
string Not used during activation.
CustomFields
optional
CustomField The names and values of any custom fields that you want to set during activation.
Name
required
string The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Value
required
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
optional
string The activation state: "Active", "Active.Ready", or "Active.Test". The default is "Active". The states "Active.Ready" and "Active.Test" are only valid on the Vodafone network.
DeviceGroupNames
optional
string The name of a device group that the devices should be added to.
LeadId
optional
string

The ID of a "Qualified" or "Closed - Won" VPP customer lead, which is used with other values to determine MDN assignment, taxation, and compensation. Use GetLeadInformation 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 AddressZipCode value defined for the lead. You can use GetLeadInformation to get a list of all leads, which includes the address information.

PublicIPRestriction
optional
string

For 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 devices will have full access to the Internet.
  • Restricted = The devices will have access to any content provided by Verizon Wireless but will be restricted from access to the Internet.

If left blank, the devices will get the default value set for the account. Public network devices with dynamic IP addresses are always unrestricted.

PrimaryPlaceOfUse
optional
PrimaryPlaceOfUse

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

CustomerName
required for PrimaryPlaceOfUse
PrimaryPlaceOfUseCustomerName The customer name to be used for line usage taxation.
Title
optional
string An optional title for the customer, such as "Mr." or "Dr."
FirstName
required for CustomerName
string The customer's first name. Valid values are any string of up to 20 alphanumeric characters, space, dash, exclamation point, and pound sign.
MiddleName
optional
string The customer's middle name.
LastName
required for CustomerName
string The customer's last name. Valid values are any string of up to 25 alphanumeric characters, space, dash, exclamation point, and pound sign.
Suffix
optional
string An optional suffix for the customer name, such as "Jr." or "III."
Address
required for PrimaryPlaceOfUse
PrimaryPlaceOfUseAddress The customer address for the line's primary place of use, for line usage taxation.
AddressLine1
required for Address
string The 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.
AddressLine2
optional
string Optional additional street address information.
City
required for Address
string The city for the line's primary place of use.
State
required for Address
string The state for the line's primary place of use.
ZipCode
required for Address
string The Zip code for the line's primary place of use.
Country
required for Address
string Either "US" or "USA" for the country of the line's primary place of use.
ZipCode4
optional
string>
CBRPhone
optional
string> A phone number where the customer can be reached (CBR).
CBRPhoneType
optional
string>

A single letter to indicate the customer phone type:

  • M = Mobile
  • H = Home
  • F = Fax
  • W = Work/Business
  • P = Pager
EmailAddress
optional
string> An email address for the customer.
SkuNumber
optional
string (20 characters max)

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 activating 4G devices. The SkuNumber will be used with all devices in the request, so all devices must be of the same type.

NOTE:If you use SKU-based activations, you must perform SIM OTA prior to any maintenance provisioning transactions (suspend, reconnect, rate plan change, feature change, etc.).

NOTE:Only 4G devices with embedded SIMs can be activated by SKU at this time.

CostCenterCode
optional
string A 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.

* You can either specify individual devices with the DeviceList parameter, or you can run the request on all devices that have a specified account name, device group name, or custom field value. You can specify an AccountName or a DeviceGroupName, plus the DeviceCustomFieldFilter to identify only those devices that are in that account or group AND have the specified custom field value.

Response Parameters

Parameter Type Description
RequestId string

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
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 An identifier of the device that was activated. This element may appear multiple times, for different types of device identifier.
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)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
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.
Activate ActivateDeviceResponse Contains information about the activated device for successful ChangeDeviceState - Activate requests. Null for other ChangeDeviceState callback messages.
DeviceIdentifierCollection DeviceIdentifier The device identifiers for the device. All known identifiers that are assigned to the device are included in the callback.
Kind string The 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
Identifier string The value of the device identifier.
IpAddress string The IP address of the activated device.
State string The state of the activated device.
ServicePlan string The service plan code that is assigned to the device.
FeatureCodes FeatureCode The feature codes for the device. Feature codes are only available with the Verizon Wholesale network.
DeviceCredential DeviceCredential
Username string
Password string
StateName string
ServiceName string
Deactivate DeactivateDeviceResponse Null in ChangeDeviceState - Activate callback messages.
Restore RestoreDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
Suspend SuspendDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
Reconnect ReconnectDeviceResponse Null in ChangeDeviceState - Deactivate callback messages.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for ChangeDeviceState requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Null for ChangeDeviceState requests.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for ChangeDeviceState requests.
ChangeDeviceCustomFields ChangeDeviceCustomFieldsResponse Null for ChangeDeviceState requests.
ChangeDeviceIdentifier ChangeDeviceIdentifierResponse Null for ChangeDeviceState requests.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Null for ChangeDeviceState requests.
MoveDevice MoveDeviceResponse Null for ChangeDeviceState requests.
ChangeDeviceContactInfo ChangeDeviceContactInfo Response Null for ChangeDeviceState requests.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
SMSDelivery SMSDelivery Null for this callback service.
PRLInformation PRLInformation Null for this callback service.
GoToState GoToState Null for this callback service.
Fault SoapFault Information about any errors that may have occurred.
faultcode QName
faultstring string
faultfactor anyURI
detail
Comment string Null in ChangeDeviceState callback messages.
Summary SummaryReport Null for this callback service.
Status string Success or Failed.
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 SOAP Request

<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.CarrierService"
  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>current_session_token</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:ChangeDeviceState>
      <v2:Input>
        <nph:DeviceList>
          <nph1:DeviceIdentifierCollection>
            <nph1:DeviceIdentifiers>
              <nph1:DeviceIdentifier>
                <nph1:Kind>IMEI</nph1:Kind>
                <nph1:Identifier>990013907835573</nph1:Identifier>
              </nph1:DeviceIdentifier>
              <nph1:DeviceIdentifier>
                <nph1:Kind>ICCID</nph1:Kind>
                <nph1:Identifier>89141390780800784259</nph1:Identifier>
              </nph1:DeviceIdentifier>
            </nph1:DeviceIdentifiers>
          </nph1:DeviceIdentifierCollection>
        </nph:DeviceList>
        <nph:Activate>
          <nph:ServicePlan>T Plan 2</nph:ServicePlan>
          <nph:MdnZipCode>98765</nph:MdnZipCode>
        </nph:Activate>
      </v2:Input>
    </v2:ChangeDeviceState>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<ChangeDeviceStateResponse xmlns="http://nphase.com/unifiedwebservice/v2">
  <Output xmlns:a="http://schemas.datacontract.org/2004/07NPhase.UnifiedWebService.APIs.v2.Contract.CarrierService"
    xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <a:RequestId>2c90bd28-ece4-42ef-9f02-7e3bd4fbff33</a:RequestId>
  </Output>
</ChangeDeviceStateResponse>

Example SOAP Callback

NOTE: If you activate a device on a Customer Private Network that has dynamic IP address assignment, the callback response will not include an IP address because the IP address is only available when the device is connected. Use GetDeviceInformation to retrieve the IP address for connected devices.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username/>
      <Password/>
      <RequestId>2c90bd28-ece4-42ef-9f02-7e3bd4fbff33</RequestId>
      <Device>
        <Kind>imei</Kind>
        <Identifier>A1000000444461</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService>
            <ChangeDeviceState>
              <Activate>
                <DeviceIdentifierCollection>
                  <Kind>mdn</Kind>
                  <Identifier>5096306081</Identifier>
                </DeviceIdentifierCollection>
                <DeviceIdentifierCollection>
                  <Kind>imsi</Kind>
                  <Identifier>311480082140479</Identifier>
                </DeviceIdentifierCollection>
                <DeviceIdentifierCollection>
                  <Kind>imei</Kind>
                  <Identifier>990003420535573</Identifier>
                </DeviceIdentifierCollection>
                <DeviceIdentifierCollection>
                  <Kind>msisdn</Kind>
                  <Identifier>15094235018</Identifier>
                </DeviceIdentifierCollection>
                <DeviceIdentifierCollection>
                  <Kind>iccid</Kind>
                  <Identifier>89148000000800784259</Identifier>
                </DeviceIdentifierCollection>
                <DeviceIdentifierCollection>
                  <Kind>min</Kind>
                  <Identifier>5098857931</Identifier>
                </DeviceIdentifierCollection>
                <State>Active</State>
                <ServicePlan>84638</ServicePlan>
                <DeviceCredential>
                  <Username>5096306081@vzw3g.com</Username>
                  <Password>5096306081</Password>
                </DeviceCredential>
                <StateName xsi:nil="true"/>
                <ServiceName xsi:nil="true"/>
              </Activate>
              <Deactivate xsi:nil="true"/>
              <Restore xsi:nil="true"/>
              <Suspend xsi:nil="true"/>
              <Reconnect xsi:nil="true"/>
            </ChangeDeviceState>
            <ChangeDeviceFeatureCodes xsi:nil="true"/>
            <ChangeDeviceServicePlan xsi:nil="true"/>
            <ChangeDeviceCostCenter xsi:nil="true"/>
            <ChangeDeviceCustomFields/>
            <ChangeDeviceIdentifier xsi:nil="true"/>
            <Change4GDeviceIdentifier xsi:nil="true"/>
            <MoveDevice xsi:nil="true"/>
            <ChangeDeviceConctactInfo xsi:nil="true"/>
          </CarrierService>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <GoToState xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment xsi:nil="true"/>
          <Summary xsi:nil="true"/>
          <Status>Success</Status> 
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram