Set Usage Segmentation Labels:

POST /devices/actions/usagesegmentationlabels

Allows you to associate your own usage segmentation label with a device.

Contents

Uses and Requirements

Allow customers to associate a label to 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.

You must register for the CarrierService callback service to receive the callback response.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/usagesegmentationlabels

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

 

Parameter Name Data Type Description
Authorization
required		 string HTTP Authorization bearer token.
VZ-M2M-Token
required		 string A valid session token returned by POST /session/login.
Content-Type
required		 string Must be application/json.

Request Body Parameters

Parameter Name Data Type Description
accountName
required		 string The name of a billing account. An account name is usually numeric, and must include any leading zeros.
labels
required		 Array of deviceIds and label objects Maximum of 2,000 objects are allowed in the array.
deviceId
required		 deviceId object An identifier for a single device.
deviceId.kind,
deviceId.id
required for deviceId		 string The type and value of the device identifier. Valid value is:
  • EID - 32 digits
label.name Varchar(20) The label you want to associate with the device.
label.value Varchar (50) The label value.

Example Request Body

{
   "accountName":"9231221278-99990",
   "labels":[
      {
         "deviceIds":[
            {
               "id":"3029423189477699229543109876975",
               "kind":"EID"
            }
         ],
         "label":{
            "name":"VIN",
            "value":"XX1TFCFL5EA137745"
         }
      },
      {
         "deviceIds":[
            {
               "id":"29183120783667588118432098765864",
               "kind":"EID"
            }
         ],
         "label":{
            "name":"VIN",
            "value":"XXUZL54B5YN105457"
         }
      }
   ]
}

Success Responses

Status 200

A successful request returns the request ID.

Parameter Name Data Type Description
requestId string A unique string that associates the request with the results that are sent via a callback message.

Callback Parameters

Parameter Name Data Type Description
username
required		 string The username for authentication.
password
required		 string The password for authentication.
requestId
required		 string The unique ID of the asynchronous request.
deviceResponse array of usageSegmentationLabelsResponse objects Summary of status of the device and label assignment.
usagesegmentationlabelsResponse array of usageSegmentationLabels objects The response of usage segmentation label assignment.
usageSegmentationLabels array of deviceId and label objects.  
deviceIds   All identifiers for the device.
deviceIds.kind string The type of the device identifier. Valid types of identifiers are:
  • EID - 32 digits
deviceIds.id string The value of the device identifier.
label.name Varchar(20) The label you want to associate with the device.
label.value Varchar(50) The label value.
action string The type of action you are taking with the label. Valid values include:
  • set
lineStatus string Indicates the status of the label action. Valid values include:
  • Success
  • Failed(with description of failure)
totalLabelCount string The total number of labels.
failedLabelCount string The total number of failed label assignments.
successLabelCount string The total number of successful label assignments.
status string The status of the request response. Valid values include:
  • Success – The operation was completed and the asynchronous response was returned.
  • Failed – LineStatus would also indicate failed.
callbackCount integer Total number of callback requests.
maxCallbackThreshold integer Maximum number of callbacks allowed.

Example Callback Request

The CarrierService sends the callback.

{
   "username":"foo",
   "password":"bar",
   "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
   "deviceResponse":{
      "usageSegmentationLabelsResponse":{
         "usageSegmentationLabels":[
            {
               "deviceIds":[
                  {
                     "id":"3029423189477699229543109876975",
                     "kind":"EID"
                  }
               ],
               "label":{
                  "name":"VIN",
                  "value":"XX1TFCFL5EA137745"
               },
               "action":"Set",
               "lineStatus":"Success"
            },
            {
               "deviceIds":[
                  {
                     "id":"29183120783667588118432098765864",
                     "kind":"EID"
                  }
               ],
               "label":{
                  "name":"VIN",
                  "value":"XXUZL54B5YN105457"
               },
               "action":"Set",
               "lineStatus":"Failed",
               "description":"The device does not exist"
            }
         ],
         "totalLabelCount":"2",
         "failedLabelCount":"1",
         "successLabelCount":"1"
      }
   },
   "status":"Success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.

|