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:

To move the line of service and MDN to a new device, specify the ESN or MEID of the new device.
To get a new MDN, provide a ZIP code or NPA-NXX to have the MDN derived from the available pool in that area.
To request a non-geographic MDN (one that is not associated with a specific location), set the AssignNonGeoMDN parameter to "true" and provide an MdnZipCode for billing purposes. (The account must be enabled for non-geographic MDNs, and the device must support it.)

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 existing device must be in the Active state with an MDN assigned.
The new hardware cannot be in the Active or Suspend state.
The new hardware (ESN or MEID) cannot already be in the ThingSpace Platform database. To reuse a Deactive device, please call Customer Service to remove the device from your account. For more information, see M2M Service Provisioning Rules.

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