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.
PUT https://thingspace.verizon.com/api/m2m/v1/devices/actions/customFields
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. |
Use these parameters to select the devices to change:
| Parameter Name | Data Type | Description |
|---|---|---|
| Parameter Namedevices optional* |
Data Typearray of deviceIds objects | DescriptionThe devices that you want to change. |
| Parameter Name deviceIds
required for devices |
Data Typearray of devices, specified by device identifier. | Description |
| Parameter Name kind,
id required for devices |
Data Typestring | DescriptionThe type and value of the device identifier.
|
| Parameter NameaccountName optional *Recommended |
Data Typestring | DescriptionThe 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. |
| Parameter NamegroupName optional* |
Data Typestring | DescriptionThe name of a device group, if you want to only include devices in that group. |
| Parameter NameservicePlan optional* |
Data Typestring | DescriptionThe name of a service plan, if you want to only include devices that have that service plan. |
| Parameter NamecustomFields optional* |
Data Typelist of customField objects | DescriptionCustom field names and values, if you want to only include devices that have matching values. |
| Parameter Name key
required for customFields |
Data Typestring | DescriptionThe name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
| Parameter Name value
required for customFields |
Data Typestring | DescriptionThe 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 |
|---|---|---|
| Parameter NamecustomFieldsToUpdate | Data Typelist of customField objects | DescriptionThe names and new values of any custom fields that you want to change. |
| Parameter Name key
|
Data Typestring | DescriptionThe name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. |
| Parameter Name value
|
Data Typestring | Description The new value of the custom field. Limited to 50 characters, allowed characters include:
|
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"
}
]
}
Status 200
| 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 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. |
{ "requestId": "595f5c44-c31c-4552-8670-020a1545a84d" }
{
"username":"",
"password":"",
"requestId":"c8de7c1d-59b9-4cf3-b969-db76cb2ce509",
"deviceIds":[
{
"id":"8586928930",
"kind":"mdn"
}
],
"deviceResponse":{
},
"comment":"Success",
"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.