API Reference
Set Usage Segmentation Labels
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
}