Change4GDeviceIdentifier

Changes the identifier of a 4G device to match hardware changes made for a line of service. Use this API to transfer the line of service and the MSISDN to new hardware, or to change the MSISDN.

Uses and Requirements

Which Option to Use

For this Hardware Change Use this Change4GOption Notes
Change the SIM in a 4G device ChangeICCID The new SIM must be inactive and not already associated with a billing account.
Replace the 4G device and use the current SIM ChangeIMEI May require optional ServicePlan parameter to change to a plan that is compatible with the new device.
Replace a 4G device and SIM ChangeIMEIandICCID The new SIM must be inactive and not already associated with a billing account. May require optional ServicePlan parameter to change to a plan that is compatible with the new device.
Change the phone number of a 4G device ChangeMSISDN You cannot change the hardware (IMEI or ICCID) and the MSISDN in the same API call.
Replace a 3G device with a 4G device 3Gto4G May require optional ServicePlan parameter to change to a 4G-compatible service plan.
Replace a 4G device with a 3G device 4Gto3G May require optional ServicePlan parameter to change to a 3G-compatible service plan.

Getting Device History after Changing Identifiers

Required Device States

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

Callback Messages

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
Change4GOption
required
string

The type of change that you want to make. Valid values are:

  • ChangeICCID (put a new SIM in an existing device)
  • ChangeIMEI (put the existing SIM in a new device)
  • ChangeIMEIandCCID (replace both the device and the SIM)
  • ChangeMSISDN (request a new phone number for the device)
  • 3Gto4G (replace a 3G device with a 4G device)
  • 4Gto3G (replace a 4G device with a 3G device)

NOTE: The values are not case sensitive.

Device
required
DeviceIdentifier The device that you want to change, specified by a device identifier. You do not have to use the same kind of device identifier here as the kind that you are changing. For example, if you want to change a device's ICCID, you can specify the device here by its MSISDN or IMEI, or by its current ICCID.

NOTE: You can use GetDeviceList to get a list of devices that shows the device identifiers.

Kind
required
string

The type of the device identifier. Valid types of identifiers are:

  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • MSISDN
  • ESN (decimal)
  • MEID (hexadecimal)
Identifier
required
string The value of the current device identifier.
ChangeDeviceIdentifierTo
optional
DeviceIdentifierCollection The new identifier for the device. The type must match what is required by the selected Change4GOption. For 3Gto4G, you must provide both an ICCID and IMEI in separate DeviceIdentifier elements.
Kind
required
string

The type of the new device identifier. Valid types of identifiers are:

  • IMEI
  • ICCID
  • MEID
  • ESN
Identifier
required
string The value of the new device identifier, such as the ICCID number.
AssignNonGeoMDN
optional
boolean

For use with the ChangeMSISDN option. Set to true to assign a non-Geo MDN and MSISDN, or false to assign an MDN and MSISDN from a specific NPA-NXX.

  • If this flag is true, MdnZipCode is required (for billing) and MdnNpaNxx is optional.
  • If this flag is false, MdnZipCode is optional and MdnNpaNxx is required.

You cannot change a non-Geo device to have a geographic MDN/MSISDN.

NOTE: To use non-geographic MDNs, 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 and MSISDN will be derived when AssignNonGeoMDN is true. Specify the zip code of the location where the line of service will primarily be used.
MdnNpaNxx
optional
string The NPA NXX (area code and prefix) from which the MDN and MSISDN will be derived when AssignNonGeoMDN is false. 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 parameter, if specified, to assign a number in the area of the line of service. This parameter is required when you change an MDN/MSISDN 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.

NOTE: Replacing a 3G device with a 4G device, or replacing a 4G device with a 3G device, will most likely require changing 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 URL was registered for the callback service, or an empty element if no username 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)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 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 Null for Change4GDeviceIdentifier requests.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for Change4GDeviceIdentifier requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Null for ChangeDeviceIdentifier requests.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for Change4GDeviceIdentifier requests.
ChangeDeviceCustomFields ChangeDeviceCustomFieldsResponse Null for Change4GDeviceIdentifier requests.
ChangeDeviceIdentifier ChangeDeviceIdentifierResponse Null for Change4GDeviceIdentifier requests.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Contains the new device identifier for successful Change4GDeviceIdentifier 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)
  • ICCID (up to 20 digits)
  • IMEI (up to 15 digits)
  • 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.
MoveDevice MoveDeviceResponse Null for Change4GDeviceIdentifier requests.
ChangeDeviceContactInfo ChangeDeviceContactInfoResponse Null for Change4GDeviceIdentifier requests.
ExternalProvisioningChange ExternalProvisioningChange Null for this callback service.
PromoChange PromoChange Null for this callback service.
Usage Usage 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.
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 for Change4GDeviceIdentifier requests.
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">
  <soapenv:Header>
    <v2:token>e1b27a04-d67a-4b16-be49-6227172fcb54</v2:token>
  </soapenv:Header>
  <soapenv:Body>
    <v2:Change4GDeviceIdentifier>
      <v2:Input>
        <nph:Device>
          <nph1:Kind>iccid</nph1:Kind>
          <nph1:Identifier>61898914800000113481</nph1:Identifier>
        </nph:Device>
        <nph:Change4GOption>ChangeICCID</nph:Change4GOption>
        <nph:ChangeDeviceIdentifierTo>
          <nph1:Kind>iccid</nph1:Kind>
          <nph1:Identifier>89148000000842590078</nph1:Identifier>
        </nph:ChangeDeviceIdentifierTo>
        <nph:ServicePlan>M2M_4G</nph:ServicePlan>
      </v2:Input>
    </v2:Change4GDeviceIdentifier>
  </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <Change4GDeviceIdentifierResponse 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>
    </Change4GDeviceIdentifierResponse>
  </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 xsi:nil="true"/>
            <Change4GDeviceIdentifier>
              <DeviceIdentifierChanged>
                <Kind>iccid</Kind>
                <Identifier>89148000000842590078</Identifier>
              </DeviceIdentifierChanged>
              <ServicePlan>M2M_4G</ServicePlan>
            </Change4GDeviceIdentifier>
            <MoveDevice xsi:nil="true"/>
            <ChangeDeviceContactInfo xsi:nil="true"/>
          </CarrierService>
          <ExternalProvisioningChange xsi:nil="true"/>
          <PromoChange xsi:nil="true"/>
          <Usage xsi:nil="true"/>
          <SMSDelivery xsi:nil="true"/>
          <PRLInformation xsi:nil="true"/>
          <DeviceSuspendStatus 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