Update Device

Restriction: This API endpoint is not supported in the public cloud.
Restriction: This API endpoint is not supported in the Free Trial cloud.

Updates the information for the device specified by <deviceId>. Currently, the API supports updating the description, roles, and dynamic fields.

Users can only update information for devices that are accessible based on their roles.

URL

Copy 
https://<your_cloud>.app.perfectomobile.com/api/v1/device-management/devices/<DEVICE_ID>

Method

Put

For information on a previous version of this endpoint, see Update Device | Legacy.

Header parameters

Name

Description

Perfecto-Authorization

The Perfecto security token. For more information, see Generate a security token.

Request parameters

Name Type Description

description

string

The new device description.

roles

list of strings

Comma separated list of device roles.

customFields

list

To set this, you need to pass the name, value, and category. This parameter may appear multiple times. After the update request, each customFields parameter will be shown in the respective category.

The following category values are allowed:

  • DEVICE_TAGS

  • DYNAMIC_FIELDS

  • ADMIN_FIELDS

Copy
Usage syntax
{
    "description": "SOME_DESCRIPTION",
    "roles": ["role1", "role2"],
    "customFields": [
        {
            "name": "dynamicFieldKey1",
            "value": "value",
            "category": "DYNAMIC_FIELDS"
        },
        {
            "name": "dynamicFieldKey2",
            "value": "value",
            "category": "DYNAMIC_FIELDS"
        }
    ]
}
Copy
Example: dynamicField.timeout=10
{
    "customFields": [
        {
            "name": "timeout",
            "value": "10",
            "category": "DYNAMIC_FIELDS"
        }
    ]
}
Important: Both the roles and the dynamic fields replace the existing values of the device. They are not added to the existing.

To remove all roles, use the roles parameter with an empty value. There is no way to remove all dynamic fields.

Copy

Sample request body

{
    "description": "SOME_DESCRIPTION",
    "roles": ["role1", "role2"],
    "customFields": [
        {
            "name": "FIELD_NAME",
            "value": "FIELD_VALUE",
            "category": "DYNAMIC_FIELDS"
        },
        {
            "name": "FIELD_NAME",
            "value": "FIELD_vALUE",
            "category": "ADMIN_FIELDS"
        }
    ]
}

Success response

Code: 200

Copy
Success response format
{
    "status": "Success"
}

Error response

Copy
Error response format
[
    {
        "userMessage":"ERROR_MESSAGE",
        "developerMessage": "1-63dbebb1-4521fab52df9f41a578221c8"
    }
]

where:

  • userMessage is the error message to be shown.

  • developerMessage is a value that you can send to Perfecto Support to check errors if further investigation is required.

Sample error responses

Copy

A wrong securityToken is passed in the request (Unauthorized Request Code - 401)

[
    {
        "userMessage": "Unable to authenticate bearer token",
        "developerMessage": "Unable to authenticate bearer token"
    }
]
Copy

An invalid name field is provided in customFields (Bad Request Code - 400)

[
    {
        "userMessage": "Not all custom fields have a name. customField:CustomField{name='', value='value', category=ADMIN_FIELDS}",
        "developerMessage": "2b9ff1d1b7c74b1ea763494d3e685c38"
    }
]
Copy

An invalid category is provided in customFields (Bad Request Code - 400)

[
    {
        "userMessage": "Invalid category provided.",
        "developerMessage": "410f544252e14bd8b5ce88e84f86013c"
    }
]