SetUsageSegmentationLabels

Allows you to assign or removal your own usage segmentation label for a device.

Uses and Requirements

Allow customers to assign or remove a label for a device, ultimately to obtain billing and usage information for their own usage segments operated on devices operated by another party or customer. The customer assigning a label to a device is restricted to retrieving information for their usage segments, and cannot retrieve or access any other device information owned by another party.

For example, this API can be used for the automotive sector in cases where a streaming radio device is present.

Request Parameters

Parameter Type Description
AccountName
required		 string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
LabelsToSet
required		 Array of UsageSegmentationLabel Maximum of 2,000 objects are allowed in the array
UsageSegmentationLabel
Device
required		 DeviceIdentifier The device for which you want to set labels. 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:

  • EID (decimal)
DeviceIdentifierCollection
required for Device		 string The value of the current device identifier.
Label string The label you want to associate with the device
Name string The label you want to associate with the device.
Value string The label value.
LabelsToRemove
optional		 Identifier Labels you want to no longer associate with a device.
Label string The label you want to no longer associate with the device
  • EID (decimal)
Name string The label name you want to no longer associate with the device.
Value string The label value you want to remove from the device.

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 sends 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 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.
CarrierService CarrierServiceCallbackRequest The data returned from a CarrierService API request.
ChangeDeviceState ChangeDeviceStateResponse Null for SetUsageSegmentationLabels requests.
ChangeDeviceFeatureCodes ChangeDevicefeatureCodesResponse Null for SetUsageSegmentationLabels requests.
ChangeDeviceServicePlan ChangeDeviceServicePlanResponse Null for SetUsageSegmentationLabels requests.
ChangeDeviceCostCenter ChangeDeviceCostCenter Response Null for SetUsageSegmentationLabels 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.
Change4GDeviceIdentifier Change4GDeviceIdentifierResponse Null for SetUsageSegmentationLabels requests.
MoveDevice MoveDeviceResponse Null for SetUsageSegmentationLabels requests.
ChangeDeviceContactInfo ChangeDeviceContactInfoResponse Null for SetUsageSegmentationLabels requests.
ChangeDeviceSkuSubscription ChangeDeviceSkuSubscriptionResponse Null for SetUsageSegmentationLabels requests.
SetUsageSegmentationLabels array Array for UsageSegmentationLabels
Device
required		 DeviceIdentifier The device for which you want to set labels. 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:

  • EID (decimal)
Label string The label you associated with the device
Name string The name of the label associated with the device.
Value string The label value.
Action string The type of action.
Status string Status of the device response.
Description string ???
totalLabelCount integer Total number of labels on which action was taken.
failedLabelCount integer Total number of labels that were not successfully assigned or removed.
successLabelCount integer Total number of successful lables that were assigned or removed.
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.
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 

<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>
        <token xmlns="http://nphase.com/unifiedwebservice/v2">f75bd90f-5d70-46fc-8bf9-0374680acfe5</token>
    </soapenv:Header>
    <soapenv:Body>
        <v2:SetUsageSegmentationLabels>
            <v2:Input>
            <nph:AccountName>0342330389-00001</nph:AccountName>
            <nph:LabelsToSet>
                <nph:UsageSegmentationLabel>
                    <nph:Device>
                        <nph1:DeviceIdentifiers>
                        <nph1:DeviceIdentifier>
                            <nph1:Kind>EID</nph1:Kind>
                            <nph1:Identifier>89148000005845275452</nph1:Identifier>
                        </nph1:DeviceIdentifier>
                        </nph1:DeviceIdentifiers>
                        <nph1:IpAddress>127.0.0.1</nph1:IpAddress>
                    </nph:Device>
                    <nph:Label>
                        <nph1:Name>VIN</nph1:Name>
                        <nph1:Value>1HD1KEM1XDB602203</nph1:Value>
                    </nph:Label>
                </nph:UsageSegmentationLabel>
            </nph:LabelsToSet>
            <nph:LabelsToRemove>
                <nph1:Label>
                    <nph1:Name>VIN</nph1:Name>
                    <nph1:Value>1HD1KEM1XDB602202</nph1:Value>
                </nph1:Label>
            </nph:LabelsToRemove>
            </v2:Input>
        </v2:SetUsageSegmentationLabels>
    </soapenv:Body>
</soapenv:Envelope>

Example SOAP Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Body>
        <SetUsageSegmentationLabelsResponse xmlns="http://nphase.com/unifiedwebservice/v2">
            <Output xmlns:a="http://schemas.datacontract.org/2004/07/NPhase.UnifiedWebService.APIs.v2.Contract.DeviceService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:RequestId>f75bd90f-5d70-46fc-1111-0374680acfe5</a:RequestId>
            </Output>
        </SetUsageSegmentationLabelsResponse>
    </s:Body>
</s:Envelope>

Example SOAP Callback for Successful Label Assignment

 <CallbackRequest>
 <Username xmlns="http://nphase.com/unifiedwebservice/v2" />
 <Password xmlns="http://nphase.com/unifiedwebservice/v2" />
 <RequestId xmlns="http://nphase.com/unifiedwebservice/v2">cba8aeb1-e7a4-4d27-97e8-93933b201b61</RequestId>
 <Data xmlns="http://nphase.com/unifiedwebservice/v2">
    <Data xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <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 xsi:nil="true" />
          <MoveDevice xsi:nil="true" />
          <ChangeDeviceContactInfo xsi:nil="true" />
          <ChangeDeviceSkuSubscription xsi:nil="true" />
          <SetUsageSegmentationLabels>
             <UsageSegmentationLabels>
                <DeviceIdentifierCollection>
                   <Kind>eid</Kind>
                   <Identifier>05062019000000000000000000000001</Identifier>
                </DeviceIdentifierCollection>
                <Label>
                   <Name>vin</Name>
                   <Value>meetapk12345678</Value>
                </Label>
                <Action>Set</Action>
                <Status>Success</Status>
                <Description />
             </UsageSegmentationLabels>
             <TotalLabelCount>1</TotalLabelCount>
             <FailedLabelCount>0</FailedLabelCount>
             <SuccessLabelCount>1</SuccessLabelCount>
          </SetUsageSegmentationLabels>
       </CarrierService>
       <ExternalProvisioningChange xsi:nil="true" />
       <PromoChange xsi:nil="true" />
       <SMSDelivery xsi:nil="true" />
       <PRLInformation xsi:nil="true" />
       <DeviceService xsi:nil="true" />
       <GoToState xsi:nil="true" />
       <DeviceProfileService xsi:nil="true" />
       <AlertService xsi:nil="true" />
       <InternalService xsi:nil="true" />
       <DiagnosticsService xsi:nil="true" />
       <Fault xsi:nil="true" />
       <Comment xsi:nil="true" />
       <Summary xsi:nil="true" />
       <Status>SUCCESS</Status>
       <CallbackCount>1</CallbackCount>
       <MaxCallbackThreshold>4</MaxCallbackThreshold>
       <ExtendedEnhancedConnectivityService xsi:nil="true" />
       <NiddService xsi:nil="true" />
    </Data>
 </Data>
</CallbackRequest>

Example Remove Success

<CallbackRequest>
    <Username xmlns="http://nphase.com/unifiedwebservice/v2" />
    <Password xmlns="http://nphase.com/unifiedwebservice/v2" />
    <RequestId xmlns="http://nphase.com/unifiedwebservice/v2">62c7184f-2e4e-4936-9d9f-a98115b16738</RequestId>
    <Data xmlns="http://nphase.com/unifiedwebservice/v2">
    <Data xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <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 xsi:nil="true" />
            <MoveDevice xsi:nil="true" />
            <ChangeDeviceContactInfo xsi:nil="true" />
            <ChangeDeviceSkuSubscription xsi:nil="true" />
            <SetUsageSegmentationLabels>
                <UsageSegmentationLabels>
                <DeviceIdentifierCollection />
                <Label>
                    <Name>vin</Name>
                    <Value>meetapk12345678</Value>
                </Label>
                <Action>Remove</Action>
                <Status>Success</Status>
                <Description />
                </UsageSegmentationLabels>
                <TotalLabelCount>1</TotalLabelCount>
                <FailedLabelCount>0</FailedLabelCount>
                <SuccessLabelCount>1</SuccessLabelCount>
            </SetUsageSegmentationLabels>
        </CarrierService>
        <ExternalProvisioningChange xsi:nil="true" />
        <PromoChange xsi:nil="true" />
        <SMSDelivery xsi:nil="true" />
        <PRLInformation xsi:nil="true" />
        <DeviceService xsi:nil="true" />
        <GoToState xsi:nil="true" />
        <DeviceProfileService xsi:nil="true" />
        <AlertService xsi:nil="true" />
        <InternalService xsi:nil="true" />
        <DiagnosticsService xsi:nil="true" />
        <Fault xsi:nil="true" />
        <Comment xsi:nil="true" />
        <Summary xsi:nil="true" />
        <Status>SUCCESS</Status>
        <CallbackCount>1</CallbackCount>
        <MaxCallbackThreshold>4</MaxCallbackThreshold>
        <ExtendedEnhancedConnectivityService xsi:nil="true" />
        <NiddService xsi:nil="true" />
    </Data>
    </Data>
</CallbackRequest>

Example Failure for SetUsageSegmentationLabels

<CallbackRequest>
    <Username xmlns="http://nphase.com/unifiedwebservice/v2" />
    <Password xmlns="http://nphase.com/unifiedwebservice/v2" />
    <RequestId xmlns="http://nphase.com/unifiedwebservice/v2">ff29c8ab-8e6a-4778-a3da-bb6ca1ff3fde</RequestId>
    <Data xmlns="http://nphase.com/unifiedwebservice/v2">
    <Data xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <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 xsi:nil="true" />
            <MoveDevice xsi:nil="true" />
            <ChangeDeviceContactInfo xsi:nil="true" />
            <ChangeDeviceSkuSubscription xsi:nil="true" />
            <SetUsageSegmentationLabels>
                <UsageSegmentationLabels>
                <DeviceIdentifierCollection>
                    <Kind>eid</Kind>
                    <Identifier>01572019000000000000000000000001</Identifier>
                </DeviceIdentifierCollection>
                <Label>
                    <Name>vin</Name>
                    <Value>meetapk12345678</Value>
                </Label>
                <Action>Set</Action>
                <Status>Failed</Status>
                <Description>The device identifier does not exists.</Description>
                </UsageSegmentationLabels>
                <TotalLabelCount>1</TotalLabelCount>
                <FailedLabelCount>1</FailedLabelCount>
                <SuccessLabelCount>0</SuccessLabelCount>
            </SetUsageSegmentationLabels>
        </CarrierService>
        <ExternalProvisioningChange xsi:nil="true" />
        <PromoChange xsi:nil="true" />
        <SMSDelivery xsi:nil="true" />
        <PRLInformation xsi:nil="true" />
        <DeviceService xsi:nil="true" />
        <GoToState xsi:nil="true" />
        <DeviceProfileService xsi:nil="true" />
        <AlertService xsi:nil="true" />
        <InternalService xsi:nil="true" />
        <DiagnosticsService xsi:nil="true" />
        <Fault xsi:nil="true" />
        <Comment xsi:nil="true" />
        <Summary xsi:nil="true" />
        <Status>FAILED</Status>
        <CallbackCount>1</CallbackCount>
        <MaxCallbackThreshold>4</MaxCallbackThreshold>
        <ExtendedEnhancedConnectivityService xsi:nil="true" />
        <NiddService xsi:nil="true" />
    </Data>
    </Data>
</CallbackRequest>