Standard APIsConnectivity ManagementAPI EndpointsDevice ManagementUpdate Devices Custom Fields
API Reference
Change Device Custom Fields
Uses and Requirements
Assign or change custom field values for one or more devices. You can use custom fields to make it easier to manage and report on devices. The ThingSpace Platform sends a CarrierService callback message for each device in the request when the custom fields have been changed, or if there was a problem and the change could not be completed.
Request
HTTP Request
PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/customFields
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
Use these parameters to select the devices to change:
| Parameter Name | Data Type | Description |
|---|---|---|
| devices optional* | array of deviceIds objects | The devices that you want to change. |
| deviceIds required for devices | array of devices, specified by device identifier. | |
| kind, id required for devices | string | The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 16 digits MDN - decimal, 10 digits MEID - hexadecimal, 14 characters MSISDN - decimal, 11 digits |
| accountName optional *Recommended | 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. *By coding for the account number today, you prevent future code from breaking if you ever add a new sub-account. |
| groupName optional* | string | The name of a device group, if you want to only include devices in that group. |
| servicePlan optional* | string | The name of a service plan, if you want to only include devices that have that service plan. |
| customFields optional* | list of customField objects | Custom field names and values, if you want to only include devices that have matching values. |
| key required for customFields | string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
| value required for customFields | string | The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported. |
- You can either specify up to 10,000 individual devices with the devices parameter, or you can use any combination of groupName, servicePlan, and customFields to run the request on all devices that match all criteria.
Use these parameters to specify the new custom field values:
| Parameter Name | Data Type | Description |
|---|---|---|
| customFieldsToUpdate | list of customField objects | The names and new values of any custom fields that you want to change. |
| key | string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
| value | string | The new value of the custom field. Limited to 50 characters, allowed characters include: Alphanumeric characters / (forward slash) SPACE @ (at sign) . (period) , (comma) : (colon) - (hyphen) _ (underscore) ( (open parenthesis) ) (close parenthesis) [ (open bracket) ] (close bracket) # (number sign or hash) |
Example Request Body
Set two custom field values for a single device
{
"devices": [
{
"deviceIds": [
{
"id": "89148000000800139708",
"kind": "iccid"
}
]
}
],
"customFieldsToUpdate": [
{
"key": "CustomField1",
"value": "West Region"
},
{
"key": "CustomField2",
"value": "Distribution"
}
]
}Change an existing custom field value for all devices in an account that have a specified current value
{
"accountName": "010045678-0001",
"customFields": [
{
"key": "CustomField2",
"value": "West Region"
}
],
"customFieldsToUpdate": [
{
"key": "CustomField2",
"value": "Southwest Region"
}
]
}Success Responses
Status 200
Contains the device identifiers and a success or failure response for each device in the request.
| Parameter Name | Data Type | Description |
|---|---|---|
| deviceIds | Identifiers for the device. | |
| 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) MEID (hexadecimal) |
| id | string | The value of the device identifier. |
| response | string | The success message or error message for the current device. |
Example Success Response
{ "requestId": "595f5c44-c31c-4552-8670-020a1545a84d" }Example Success Callback Response
{
"username":"",
"password":"",
"requestId":"c8de7c1d-59b9-4cf3-b969-db76cb2ce509",
"deviceIds":[
{
"id":"8586928930",
"kind":"mdn"
}
],
"deviceResponse":{
},
"comment":"Success",
"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"
}