POST /devices/actions/usagesegmentationlabelsAllows you to associate your own usage segmentation label with a device.
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.
POST https://thingspace.verizon.com/api/m2m/v1/devices/actions/usagesegmentationlabels
None.
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 |
|---|---|---|
| Parameter NameAuthorization required |
Data Typestring | DescriptionHTTP Authorization bearer token. |
| Parameter NameVZ-M2M-Token required |
Data Typestring | DescriptionA valid session token returned by POST /session/login. |
| Parameter NameContent-Type required |
Data Typestring | DescriptionMust be application/json. |
| Parameter Name | Data Type | Description |
|---|---|---|
| Parameter NameaccountName required |
Data Typestring | DescriptionThe name of a billing account. An account name is usually numeric, and must include any leading zeros. |
| Parameter Namelabels required |
Data TypeArray of deviceIds and label objects | DescriptionMaximum of 2,000 objects are allowed in the array. |
| Parameter NamedeviceId required |
Data TypedeviceId object | DescriptionAn identifier for a single device. |
| Parameter NamedeviceId.kind, deviceId.id required for deviceId |
Data Typestring | DescriptionThe type and value of the device identifier. Valid value is:
|
| Parameter Namelabel.name | Data TypeVarchar(20) | DescriptionThe label you want to associate with the device. |
| Parameter Namelabel.value | Data TypeVarchar (50) | DescriptionThe label value. |
{
"accountName":"9231221278-99990",
"labels":[
{
"deviceIds":[
{
"id":"3029423189477699229543109876975",
"kind":"EID"
}
],
"label":{
"name":"VIN",
"value":"XX1TFCFL5EA137745"
}
},
{
"deviceIds":[
{
"id":"29183120783667588118432098765864",
"kind":"EID"
}
],
"label":{
"name":"VIN",
"value":"XXUZL54B5YN105457"
}
}
]
}
Status 200
A successful request returns the request ID.
| Parameter Name | Data Type | Description |
|---|---|---|
| Parameter NamerequestId | Data Typestring | DescriptionA unique string that associates the request with the results that are sent via a callback message. |
| Parameter Name | Data Type | Description |
|---|---|---|
| Parameter Nameusername required |
Data Typestring | DescriptionThe username for authentication. |
| Parameter Namepassword required |
Data Typestring | DescriptionThe password for authentication. |
| Parameter NamerequestId required |
Data Typestring | DescriptionThe unique ID of the asynchronous request. |
| Parameter NamedeviceResponse | Data Typearray of usageSegmentationLabelsResponse objects | DescriptionSummary of status of the device and label assignment. |
| Parameter NameusagesegmentationlabelsResponse | Data Typearray of usageSegmentationLabels objects | DescriptionThe response of usage segmentation label assignment. |
| Parameter NameusageSegmentationLabels | Data Typearray of deviceId and label objects. | Description |
| Parameter NamedeviceIds | Data Type | DescriptionAll identifiers for the device. |
| Parameter NamedeviceIds.kind | Data Typestring | DescriptionThe type of the device identifier. Valid types of identifiers are:
|
| Parameter NamedeviceIds.id | Data Typestring | DescriptionThe value of the device identifier. |
| Parameter Namelabel.name | Data TypeVarchar(20) | DescriptionThe label you want to associate with the device. |
| Parameter Namelabel.value | Data TypeVarchar(50) | DescriptionThe label value. |
| Parameter Nameaction | Data Typestring | DescriptionThe type of action you are taking with the label. Valid values include:
|
| Parameter NamelineStatus | Data Typestring | DescriptionIndicates the status of the label action. Valid values include:
|
| Parameter NametotalLabelCount | Data Typestring | DescriptionThe total number of labels. |
| Parameter NamefailedLabelCount | Data Typestring | DescriptionThe total number of failed label assignments. |
| Parameter NamesuccessLabelCount | Data Typestring | DescriptionThe total number of successful label assignments. |
| Parameter Namestatus | Data Typestring | DescriptionThe status of the request response. Valid values include:
|
| Parameter NamecallbackCount | Data Typeinteger | DescriptionTotal number of callback requests. |
| Parameter NamemaxCallbackThreshold | Data Typeinteger | DescriptionMaximum number of callbacks allowed. |
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
}
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.
|