ChangeDeviceCostCenter

Changes or removes the Cost Center Code value or customer name and address (Primary Place of Use) for one or more devices.

Uses and Requirements

The ThingSpace Platform sends a CarrierService callback message for each device in the request when the device has been changed, or if there was a problem and the change could not be completed.

NOTE: To change both the cost center code and the primary place of use in a single request, the CostCenterCode parameter must come before the PrimaryPlaceOfUse parameters.

Request Parameters

Parameter	Type	Description
DeviceList optional*	DeviceIdentifierCollection	A list of the devices for which you want to change or remove the cost center code, specified by device identifier. You only need to provide one identifier per device. Do not pass DeviceGroupName, AccountName, DeviceCustomFieldFilter, or DeviceServicePlanFilter 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> </DeviceIdentifierCollection>
Kind required for DeviceList	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) MSISDN
Identifier required for DeviceList	string	The value of the device identifier.
DeviceGroupName optional*	string	The name of a device group, if you want to only include devices in that group. NOTE: You can use GetDeviceGroupList to get a list of all device groups in the account.
AccountName optional*	string	The name of a billing account. This parameter is only required if the UWS account used for the current API session has access to multiple billing accounts. An account name is usually numeric, and must include any leading zeros.
DeviceServicePlanFilter optional*	string	The name of a service plan, if you want to only include devices that have that service plan. You can use GetServicePlanList to get a list of all service plans in the account.
DeviceCustomFieldFilter optional*	CustomField	The names and values of custom fields, if you only want to change 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)
CostCenterCode optional	string	The new cost center code. Valid values are any string of up to 36 alphanumeric characters, space, dash, exclamation point, and pound sign.
RemoveCostCenterCode optional	Boolean	Set to true to remove the cost center code value. This flag takes precedence over a new CostCenterCode value. If this flag is true and CostCenterCode has a value, the cost center code will be removed. Do not include this parameter or set it to false to change the CostCenterCode value.
PrimaryPlaceOfUse optional	PrimaryPlaceOfUse	The customer name and contact information, and the address of the device's primary place of use. These values will be applied to all devices in the change request. 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 or changing values for these fields.
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.

* 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, service plan name, or custom field value. You can specify an AccountName or a DeviceGroupName plus one or both filters to identify only those devices that match all criteria.

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) 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	Null for ChangeDeviceCostCenter requests.
ChangeDeviceFeatureCodes	ChangeDevicefeatureCodesResponse	Null for ChangeDeviceCostCenter requests.
ChangeDeviceServicePlan	ChangeDeviceServicePlanResponse	Null for ChangeDeviceCostCenter requests.
ChangeDeviceCostCenter	ChangeDeviceCostCenter Response	The cost center code and primary place of use of the device after the request completed.
CostCenterCode	string	The cost center code of the device.
PrimaryPlaceOfUse	PrimaryPlaceOfUse object	The name, address, and contact information of the device owner.
CustomerName	CustomerName object	The name of the device owner.
Title FirstName MiddleName LastName Suffix	strings	The registered customer name for the device.
Address	Address object	The address and contact information of the device owner.
AddressLine1 AddressLine2 City State ZipCode Country ZipCode4 CBRPhone CBRPhoneType EmailAddress	strings	The registered primary place of use address for the device, plus the customer phone number and email address.
ChangeDeviceCustomFields	ChangeDeviceCustomFieldsResponse	Null for ChangeDeviceCostCenter requests.
ChangeDeviceIdentifier	ChangeDeviceIdentifierResponse	Null for ChangeDeviceCostCenter requests.
Change4GDeviceIdentifier	Change4GDeviceIdentifierResponse	Null for ChangeDeviceCostCenter requests.
MoveDevice	MoveDeviceResponse	Null for ChangeDeviceCostCenter 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
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

Change Cost Center Code for two 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>4b48257b-dea0-4f93-a1d2-4e7faa15f59d</v2:token>
</soapenv:Header>
<soapenv:Body>
  <v2:ChangeDeviceCostCenter>
    <v2:Input>
      <nph:DeviceList>
        <nph1:DeviceIdentifierCollection>
          <nph1:DeviceIdentifiers>
            <nph1:DeviceIdentifier>
              <nph1:Kind>mdn</nph1:Kind>
              <nph1:Identifier>8587757416</nph1:Identifier>
            </nph1:DeviceIdentifier>
          </nph1:DeviceIdentifiers>
        </nph1:DeviceIdentifierCollection>
        <nph1:DeviceIdentifierCollection>
          <nph1:DeviceIdentifiers>
            <nph1:DeviceIdentifier>
              <nph1:Kind>mdn</nph1:Kind>
              <nph1:Identifier>8587757416</nph1:Identifier>
            </nph1:DeviceIdentifier>
          </nph1:DeviceIdentifiers>
        </nph1:DeviceIdentifierCollection>
      </nph:DeviceList>
      <nph:CostCenterCode>CC12345</nph:CostCenterCode>
    </v2:Input>
  </v2:ChangeDeviceCostCenter>
</soapenv:Body>

Remove Cost Center 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"
  xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soapenv:Header>
  <v2:token>4b48257b-dea0-4f93-a1d2-4e7faa15f59d</v2:token>
</soapenv:Header>
<soapenv:Body>
  <v2:ChangeDeviceCostCenter>
    <v2:Input>
      <nph:DeviceList>
        <nph1:DeviceIdentifierCollection>
          <nph1:DeviceIdentifiers>
            <nph1:DeviceIdentifier>
              <nph1:Kind>mdn</nph1:Kind>
              <nph1:Identifier>8587757416</nph1:Identifier>
            </nph1:DeviceIdentifier>
          </nph1:DeviceIdentifiers>
        </nph1:DeviceIdentifierCollection>
      </nph:DeviceList>
      <nph:RemoveCostCenterCode>true</nph:RemoveCostCenterCode>
    </v2:Input>
  </v2:ChangeDeviceCostCenter>
</soapenv:Body>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <ChangeDeviceCostCenterResponse 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>fb4a29ac-a3a6-4db2-8188-4cca1a77b2f3</a:RequestId>
      </Output>
    </ChangeDeviceCostCenterResponse>
  </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>c8de7c1d-59b9-4cf3-b969-db76cb2ce509</RequestId>
      <Device>
        <Kind>mdn</Kind>
        <Identifier>8586928930</Identifier>
      </Device>
      <Data>
        <Data>
          <CarrierService>
            <ChangeDeviceState xsi:nil="true"/>
            <ChangeDeviceFeatureCodes xsi:nil="true"/>
            <ChangeDeviceServicePlan xsi:nil="true"/>
            <ChangeDeviceCostCenter>
              <CostCenterCode>12345</CostCenterCode>
              <PrimaryPlaceOfUse>
                <CustomerName>
                  <Title>President</Title>
                  <FirstName>Zaffod</FirstName>
                  <MiddleName>P</MiddleName>
                  <LastName>Beeblebrox</LastName>
                  <Suffix>I</Suffix>
                </CustomerName>
                <Address>
                  <AddressLine1>9868 Scranton Rd</AddressLine1>
                  <AddressLine2>Suite A</AddressLine2>
                  <City>San Diego</City>
                  <State>CA</State>
                  <ZipCode>92121</ZipCode>
                  <Country>US</Country>
                  <ZipCode4>0001</ZipCode4>
                  <CBRPhone>1234567890</CBRPhone>
                  <CBRPhoneType>P</CBRPhoneType>
                  <EmailAddress>zaffod@theinternet.com</EmailAddress>
                </Address>
              </PrimaryPlaceOfUse>
            </ChangeDeviceCostCenter>
            <ChangeDeviceCustomFields xsi:nil="true"/>
            <ChangeDeviceIdentifier xsi:nil="true"/>
            <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"/>
          <DeviceSuspendStatus xsi:nil="true"/>
          <Fault xsi:nil="true"/>
          <Comment>Success</Comment>
          <Summary xsi:nil="true"/>
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>