ChangeDeviceIdentifier

Changes the identifier of a 3G device associated with a line of service. Use this API to transfer the line of service and the MDN to new hardware, or to change the MDN.

Uses and Requirements

To change these identifiers:

You cannot change the hardware (ESN) and the MDN in the same API call.

NOTE: All of these conditions must be true for this call to succeed:

The M2M Platform sends a CarrierService callback message when the device identifier has been changed, or if there was a problem and the change could not be completed.

Request Parameters

Parameter Type Description
Device
required
DeviceIdentifier The device that you want to change. You can use GetDeviceList to get a list of all devices in the account.
Kind
required for Device
string The type of the device identifier. Valid types of identifiers are:

  • ESN (decimal)
  • MDN
  • MEID (hexadecimal)
  • MSISDN
Identifier
required for Device
string The value of the current device identifier.
ChangeDeviceIdentifierTo
optional
DeviceIdentifier The new ESN or MEID identifier for the device.
Kind
required for ChangeDeviceIdentifierTo
string The type of the new device identifier. Valid types of identifiers are:

  • ESN (decimal)
  • MEID (hexadecimal)
Identifier
required for ChangeDeviceIdentifierTo
string The value of the new device identifier.
AssignNonGeoMDN
optional
boolean Set to true to assign a non-Geo MDN.
  • If this flag is true, MdnZipCode is required and MdnNpaNxx is optional.
  • If this flag is false, MdnZipCode is optional and MdnNpaNxx is required.

NOTE: The account must be configured to support non-Geo MDNs, and the device must be non-Geo capable.

MdnZipCode
optional
string The ZIP code from which the MDN will be derived. Specify the zip code of the location where the line of service will primarily be used. If you do not specify a zip code, this API will assign the zip code associated with the service plan for the device.
MdnNpaNxx
optional
string The NPA NXX from which the MDN will be derived. Specify the 6-digit NPA NXX of the location where the line of service will primarily be used. This API checks to see if a number starting with the NPA NXX is available. If not, this API uses the MdnZipCode element, if specified, to assign a number in the area of the line of service. This parameter is required when you change an MDN for a B2B carrier, such as Verizon Wireless.
ServicePlan
optional
string

The code for a different service plan, if you want to change the service plan while changing the device identifier. 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.

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 M2M 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 The device that was changed.
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • 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 Null for ChangeDeviceIdentifier requests.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for ChangeDeviceIdentifier requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Null for ChangeDeviceIdentifier requests.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for ChangeDeviceIdentifier requests.
ChangeDeviceCustomFields ChangeDeviceCustomFieldsResponse Empty in callback messages for ChangeDeviceIdentifier requests. Null for other CarrierService callback messages.
ChangeDeviceIdentifier ChangeDeviceIdentifierResponse Contains the new device identifier for successful ChangeDeviceIdentifier requests. Null for other CarrierService callback messages.
DeviceIdentifierChanged DeviceIdentifier The new device identifier
Kind string The type of the device identifier. Valid types of identifiers are:
  • ESN (decimal)
  • MDN
  • MEID (hexadecimal)
  • MIN
  • MSISDN
Identifier string The value of the device identifier.
ServicePlan string The name of the new service plan for the device, if the service plan was changed.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Null for ChangeDeviceIdentifier requests.
MoveDevice MoveDeviceResponse Null for ChangeDeviceIdentifier 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.
DeviceSuspendStatus DeviceSuspendStatus 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 for ChangeDeviceIdentifier requests.
Summary SummaryReport Null for this callback service.
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

Scenario 1: Specifying a new Identifier

<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">
  <soapenv:Header>
    <v2:token>e1b27a04-d67a-4b16-be49-6227172fcb54</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:ChangeDeviceIdentifier>
      <v2:Input>
        <nph:Device>
          <nph1:Kind>meid</nph1:Kind>
          <nph1:Identifier>A1000001999998</nph1:Identifier>
        </nph:Device>
        <nph:ChangeDeviceIdentifierTo>
          <nph1:Kind>meid</nph1:Kind>
          <nph1:Identifier>A1000001999990</nph1:Identifier>
        </nph:ChangeDeviceIdentifierTo>
      </v2:Input>
    </v2:ChangeDeviceIdentifier>
  </soapenv:Body>
</soapenv:Envelope>

Scenario 2: Request New Identifier by MDN Zip Code

<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">
  <soapenv:Header>
    <v2:token>e1b27a04-d67a-4b16-be49-6227172fcb54</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:ChangeDeviceIdentifier>
      <v2:Input>
        <nph:Device>
          <nph1:Kind>esn</nph1:Kind>
          <nph1:Identifier>6067D9AD</nph1:Identifier>
        </nph:Device>
        <nph:MdnZipCode>60601</nph:MdnZipCode>
      </v2:Input>
    </v2:ChangeDeviceIdentifier>
  </soapenv:Body>
</soapenv:Envelope>

Scenario 3: Request New Identifier by MDN NPA-NXX

<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">
  <soapenv:Header>
    <v2:token>e1b27a04-d67a-4b16-be49-6227172fcb54</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:ChangeDeviceIdentifier>
      <v2:Input>
        <nph:Device>
          <nph1:Kind>esn</nph1:Kind>
          <nph1:Identifier>6067D9AD</nph1:Identifier>
        </nph:Device>
        <nph:MdnNpaNxx>123456</nph:MdnNpaNxx>
      </v2:Input>
    </v2:ChangeDeviceIdentifier>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <ChangeDeviceIdentifierResponse 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.CarrierService">
        <a:RequestId>d747ec03-312e-4a20-bcee-c0686d48afb4</a:RequestId>
      </Output>
    </ChangeDeviceIdentifierResponse>
  </s:Body>
</s:Envelope>

Example SOAP Callback

<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>a28892ea-6503-4aa7-bfa2-4cd45d42f61b</RequestId>
      <Device>
        <Kind>ESN</Kind>
        <Identifier>22211315718</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService>
            <ChangeDeviceState xsi:nil="true"/>
            <ChangeDeviceFeatureCodes xsi:nil="true"/>
            <ChangeDeviceServicePlan xsi:nil="true"/>
            <ChangeDeviceCostCenter xsi:nil="true"/>
            <ChangeDeviceCustomFields xsi:nil="true"/>
            <ChangeDeviceIdentifier>
              <DeviceIdentifierChanged>
                <Kind>mdn</Kind>
                <Identifier>2358519153</Identifier>
              </DeviceIdentifierChanged>
            </ChangeDeviceIdentifier>
            <Change4GDeviceIdentifier xsi:nil="true"/>
            <MoveDevice xsi:nil="true"/>
          </CarrierService>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment xsi:nil="true"/>
          <Summary xsi:nil="true"/>
          <CallbackCount>1</CallbackCount>
          <MaxCallbackThreshold>4</MaxCallbackThreshold/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

Request Schema Diagram

Response Schema Diagram