---
updatedAt: 2026-04-30T11:49:55.000Z
agentTools:
  projectIndex: https://developer.ixon.cloud/llms.txt
---

# Manage custom properties

This article will explain how to manage custom properties and provide details about the related endpoints and some specific fields.

> 📘 Require module
>
> You will need the **Custom Fields** module to visualize and use custom fields. Check your modules at <Anchor label="**Admin > Licenses**" target="_blank" href="https://portal.ixon.cloud/admin/licenses">**Admin > Licenses**</Anchor>. To obtain this module, contact your IXON account manager or IXON distrubutor.

# Introduction to Custom properties and related endpoints

You can use **custom fields** (also called **custom properties**) to add information to your machine, such as a password, or an instruction manual, or more. This article will explain how to manage them via IXON's API endpoints. Check this <Anchor label="support article" target="_blank" href="https://support.ixon.cloud/s/article/Add-extra-machine-details-with-custom-fields">support article</Anchor> to know more about them before you start.

Assuming that you already have an **<Anchor label="Application ID" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-authentication-headers#how-to-get-an-application-id">Application ID</Anchor>**, **<Anchor label="Company ID" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-prerequisites#how-to-get-a-companys-publicid">Company ID</Anchor>** and **<Anchor label="Bearer Token" target="_blank" href="https://developer.ixon.cloud/docs/ixon-api-authentication-headers#how-to-get-a-bearer-token">Bearer Token</Anchor>**, you will now be able to call the following endpoints.

## CustomPropertyList

| Verb                                                                                                                 | Goal                                   | Required fields and IDs                                  |
| :------------------------------------------------------------------------------------------------------------------- | :------------------------------------- | :------------------------------------------------------- |
| <Anchor label="GET" target="_blank" href="https://developer.ixon.cloud/reference/get_custom-properties">GET</Anchor> | Retrieves a list of custom properties. | You can use `?fields=*` to retrieve all relevant fields. |

**Please note**: the **CustomProperty** endpoint is the non-list version of **CustomPropertyList**, and can be used to perform [GET](https://developer.ixon.cloud/reference/get_custom-properties-publicid) action for a single custom property by providing its `publicId`.

> 📘 Note about `scopeType`
>
> This field corresponds to the first part of the Identifier of a custom property, and it's set to `com` by default when a user creates one, like shown in this picture:
>
> <Image align="center" border={true} src="https://files.readme.io/a12a8fb56d009517df156d05ff1b594dac9ec1854733f4faa579454f7b43cb80-image.png" className="border" />
>
> If you see `glb` as value in the `scopeType`, ignore it. These are global values set by IXON and are used internally for other features.

> ❗️ Filtering by Custom Properties
>
> ***Filtering devices given a specific custom property via the IXON API is currently not possible**.* The request won't return an error, but it will instead return the full list of devices.  For this reason, if filtering logic is needed, it is recommended to **implement** it in your code.

## MyCompanyCustomPropertyList

| Verb                                                                                                                                       | Goal                                                                                                  | Required fields and IDs                                                                                                                                                                                                           |
| :----------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <Anchor label="POST" target="_blank" href="https://developer.ixon.cloud/reference/post_companies-me-custom-properties">POST</Anchor>       | Creates one or more new custom properties. Returns the `publicId` of each of the new custom property. | The `resourceType` of the new custom property (either `Agent` or `Asset`), the `name`,  the `slug` (which is always the same value as the `name` but with an initial capital letter and no spacing) and the type of `validation`. |
| <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_companies-me-custom-properties">PATCH</Anchor>    | Modifies one or more fields of one or more custom properties.                                         | The `publicId` of the custom property you want to modify.                                                                                                                                                                         |
| <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_companies-me-custom-properties">DELETE</Anchor> | Deletes one or more custom properties.                                                                | The `publicId` of the custom property you want to delete.                                                                                                                                                                         |

**Please note**: the **MyCompanyCustomProperty** endpoint is the non-list version of **MyCompanyCustomPropertyList**, and can be used to perform <Anchor label="PATCH" target="_blank" href="https://developer.ixon.cloud/reference/patch_companies-me-custom-properties-publicid">PATCH</Anchor> and <Anchor label="DELETE" target="_blank" href="https://developer.ixon.cloud/reference/delete_companies-me-custom-properties-publicid">DELETE</Anchor> actions for a single custom property by providing its `publicId`. It is not possible to perform a POST request with this endpoint.

> 👍 MyCompanyCustomPropertyList in detail
>
> This endpoint's POST request is used to create a custom field from scratch in **Admin > Device settings > Custom fields** or **Admin > Device settings > Assets**, therefore being used for both custom properties of either Agents or Assets. The following fields can be used in the request body of this request:
>
> <Table align={["left","left","left","left"]}>
>   <thead>
>     <tr>
>       <th style={{ textAlign: "left" }}>
>         Field
>       </th>
>
>       <th style={{ textAlign: "left" }}>
>         Data type
>       </th>
>
>       <th style={{ textAlign: "left" }}>
>         Description
>       </th>
>
>       <th style={{ textAlign: "left" }}>
>         Mandatory
>       </th>
>     </tr>
>   </thead>
>
>   <tbody>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `resourceType`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `string`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         It consists of the type of resource the custom property belongs to (
>
>         `Agent`
>
>         or
>
>         `Asset`
>
>         ).
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Yes
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `resourceVariant`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `string | null`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         The Asset type. If the resource is an Agent, this field can be
>
>         `null`
>
>         .
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Yes
>
>         **Note: it is not flagged as mandatory, but in case of custom fields belonging to Assets, it needs to be filled or the custom field won't be  visible in the interface.**
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `slug`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `string`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         It consists of the same value as the
>
>         `name`
>
>         but with an initial capital letter and no spacing. Not visible to the user in the interface.
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Yes
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `name`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `string`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         The name of the custom field.
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Yes
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `description`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `string | null`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         The description of the custom field.
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         No
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `required`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `boolean`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Its default value is
>
>         `false`
>
>         . Cannot be set through the interface, and does not need to be used in the POST request.
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         No
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `validation`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `object`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Refer to the information below for more details.
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Yes
>       </td>
>     </tr>
>
>     <tr>
>       <td style={{ textAlign: "left" }}>
>         `flags`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         `array`
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         Contains information about visibility of a custom field. If the option "Hide in portal view" is selected, then it will contain
>
>         `hiddenInPortal`
>
>         , otherwise it will be empty.
>       </td>
>
>       <td style={{ textAlign: "left" }}>
>         No
>       </td>
>     </tr>
>   </tbody>
> </Table>
>
> The `validatation` object is mandatory and checks whether the **value** of the selected *Field type* matches with the data type. The field types can be visualized when adding a new custom field:
>
> <Image align="center" border={true} width="500px" src="https://files.readme.io/5a78ae3a536a67cdfd92a483e042e127354f6017122d2695c3490ec4de561812-image.png" className="border" />
>
> You can refer to this table to apply the correct validation through the API endpoint request body:
>
> | Field type    | Data type | Validation fields                                                                                                       |
> | :------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------- |
> | Text/JSON     | `string`  | `{     "validation": {       "type": "str"     }   }`                                                                   |
> | Single option | `enum`    | `{     "validation": {       "type": "enum",       "options": [         "Option1",         "Option2"       ]     }   }` |
> | Numerical     | `int`     | `{     "validation": {       "type": "int"     }   }`                                                                   |
> | Boolean       | `bool`    | `{     "validation": {       "type": "bool"     }   }`                                                                  |

***

# How-tos and use cases

In this section you will find step-by-step examples of real use cases concerning the manipulation of custom fields.

## How to retrieve all available custom fields

**Goal**: retrieving a list of custom fields available in a company.

**What you will need**:

* Your `applicationId`;
* Your `companyId`;
* Your `bearerToken`.

To obtain a list of custom fields, all you only have to follow one single step consisting of sending a **<Anchor label="GET Request" target="_blank" href="https://developer.ixon.cloud/reference/get_custom-properties">GET Request</Anchor>** to the **CustomPropertyList** endpoint:

```curl GET Request
curl --location 'https://portal.ixon.cloud/api/custom-properties' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'
```
```json Response
{
  "type": "CustomProperty",
  "data": [
    {
      "publicId": "$customPropertyPublicId",
      "scopeType": "glb",
      "resourceType": "Branding",
      "resourceVariant": null,
      "slug": "BrowserTitle",
      "name": "Browser Title",
      "description": "Used the title on your browser",
      "required": false,
      "validation": {
        "type": "str",
        "minLength": null,
        "maxLength": null,
        "regex": null
      },
      "flags": []
    },
    {
      "publicId": "$customPropertyPublicId",
      "scopeType": "com",
      "resourceType": "Asset",
      "resourceVariant": "$assetTypePublicId",
      "slug": "InstructionsManual",
      "name": "Instruction Manual",
      "description": null,
      "required": false,
      "validation": {
        "type": "str",
        "minLength": null,
        "maxLength": null,
        "regex": null
      },
      "flags": []
    },
    {
      "publicId": "$customPropertyPublicId",
      "scopeType": "com",
      "resourceType": "Asset",
      "resourceVariant": "$assetTypePublicId",
      "slug": "LocalPassword",
      "name": "Local Password",
      "description": null,
      "required": false,
      "validation": {
        "type": "str",
        "minLength": null,
        "maxLength": null,
        "regex": null
      },
      "flags": [
        "hiddenInPortal"
      ]
    }
  ],
  "moreAfter": null,
  "status": "success"
}
```

There are a few things to point out in this JSON response:

* In the first custom field, you can see that the `scopeType` value is `glb` (global). You might see more fields with such a scope type, they are default and we **recommend to not manipulate them**;
* The `minLength` and `maxLength` (`minValue` and `maxValue` for `int`) values are fields used to automatically check the data type of a custom field. For this reason, it is not required to set them in a request body of a POST request. Additionally, the field `regex` is not used;
* The string `hiddenInPortal` is used to flag the "Hide in portal view" option. If not present, then it means that the custom field is visible in the portal:

  <Image align="center" border={true} src="https://files.readme.io/e5568dfb6695692d3b3c283a8794ae5b81edfd022dcec7f9a49be45d4b2f2184-image.png" className="border" />

## How to retrieve a custom field belonging to either Agents or Assets

**Goal**: retrieving a custom field used in an agent or asset.

**What you will need**:

* Your `applicationId`;
* Your `companyId`;
* Your `bearerToken`.

### Agent

In case you want to retrieve custom fields belonging to agents, you can use the <Anchor label="**GET Request**" target="_blank" href="https://developer.ixon.cloud/reference/get_agents">**GET Request**</Anchor> of the **AgentList** endpoint. All you have to do is retrieving all fields of the `custom` object in the URL query:

```curl GET Request
curl --location 'https://portal.ixon.cloud/api/agents?fields=deviceId,custom.*' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'
```
```json Response
{
  "type": "Agent",
  "data": [
    {
      "publicId": "$agentPublicId",
      "name": "IX3 Router - Scrap Mixer",
      "deviceId": "$deviceMACAddress",
      "custom": {
        "glbStarUsers": null,
        "comLocalPassword": "password",
        "comInstructionsManual": "$linkToInstructionManual"
      }
    },
    {
      "publicId": "$agentPublicId",
      "name": "SecureEdge Pro - Scrap Grabber",
      "deviceId": "$deviceMACAddress",
      "custom": {
        "glbStarUsers": null,
        "comLocalPassword": "password",
        "comInstructionsManual": "$linkToInstructionManual"
      }
    }
  ],
  "moreAfter": null,
  "status": "success"
}
```

### Asset

In case your machines are assets, you will have to use the <Anchor label="**GET Request**" target="_blank" href="https://developer.ixon.cloud/reference/get_assets-1">**GET Request**</Anchor> of the **AssetList** endpoint. Again, you will be retrieving all fields of the `custom` object in the URL query:

```curl GET Request
curl --location 'https://portal.ixon.cloud/api/assets?fields=name,description,resourceVariant.*,parent.publicId,custom.*' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'
```
```json Response
{
    "type": "Asset",
    "data": [
        {
            "publicId": "$assetPublicId",,
            "name": "Aluminium Heat Measurer",
            "description": "Measures heat.",
            "resourceVariant": {
                "publicId": "$assetTypePublicId",
                "name": "Scrap metal measurer",
                "order": 2000
            },
            "parent": {
                "publicId": "$parentAssetPublicId",
                "reference": {
                    "name": "Asset"
                }
            },
            "custom": {
                "comComInstructionsManual": "$linkToInstructionsManual"
            }
        },
        {
            "publicId": "KxWcZIBlMkTM",
            "name": "Aluminium Metrics",
            "description": "Measurements for aluminium.",
            "resourceVariant": {
                "publicId": "$assetTypePublicId",
                "name": "Scrap metal measurer",
                "order": 2000
            },
            "parent": null,
            "custom": {
                "comComInstructionsManual": "$linkToInstructionsManual"
            }
        }
    ],
    "moreAfter": null,
    "status": "success"
}
```

## How to create a new custom field

**Goal**: creating a new custom field for an agent and assigning a value to it.

**What you will need**:

* Your `applicationId`;
* Your `companyId`;
* Your `bearerToken`;
* The `publicId` of one or more *Agents*.

### Step 1 - Create the custom field

To create a new custom property, you will need to send a <Anchor label="**POST Request**" target="_blank" href="https://developer.ixon.cloud/reference/patch_companies-me-custom-properties">**POST Request**</Anchor> to the **MyCompanyCustomPropertyList** endpoint. This is the only endpoint that handles the creation of custom properties from scratch:

```curl POST Request
curl --location 'https://portal.ixon.cloud:443/api/companies/me/custom-properties' \
     --header 'Api-Application: $applicationId' \
     --header 'Api-Company: $companyId' \
     --header 'Api-Version: 2' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $bearerToken'
     --data '
[
  {
    "validation": {
      "type": "str"
    },
    "resourceType": "Agent",
    "slug": "AlarmInstructions",
    "name": "Alarm Instructions"
  }
]
'
```
```json Response
{
  "type": "CreateResponse",
  "data": [
    {
      "publicId": "$newCustomFieldPublicId"
    }
  ],
  "moreAfter": null,
  "status": "success"
}
```

For more details about the fields in this request body, please refer to this <Anchor label="previous section" target="_blank" href="https://developer.ixon.cloud/docs/manage-custom-properties#/mycompanycustompropertylist">previous section</Anchor>.

### Step 2 - Assign a value to the new custom field

The **Identifier** (visible in <Anchor label="IXON's Portal view" target="_blank" href="https://portal.ixon.cloud/admin/custom-fields">IXON's Portal view</Anchor>) of a custom field is available to all *Agents* or *Assets*, but it won't necessarily have a `value` as you can see here:

<Image align="center" alt="Upon creation, no value is assigned." caption="Upon creation, no value is assigned." src="https://files.readme.io/60eb1fae68f487ec04f947feeb202cbcb5098a0b750593b22555cf996678a77b-image.png" />

How can we emulate pressing the **"Edit"** button with the API?

In our specific case we want to assign a value to two different agents at the same time. To do this, we will use the **AgentList** endpoint's <Anchor label="**PATCH Request**" target="_blank" href="https://developer.ixon.cloud/reference/patch_agents">**PATCH Request**</Anchor>:

```curl PATCH Request
curl --location --request PATCH 'https://portal.ixon.cloud/api/agents' \
		 --header 'Api-Application: $applicationId' \
  	 --header 'Api-Company: $companyId' \
  	 --header 'Api-Version: 2' \
  	 --header 'accept: application/json' \
  	 --header 'authorization: Bearer $bearerToken' \
  	 --data '
[
  {
    "custom": {
      "comAlarmInstructions": "Press the red button twice to stop the alarm sound."
    },
    "publicId": "$agentPublicId"
  },
  {
    "custom": {
      "comAlarmInstructions": "Twist the handle to stop the alarm sound."
    },
    "publicId": "$agentPublicId"
  }
]
'
```
```json Response
{
    "type": "Null",
    "data": null,
    "status": "success"
}
```

As you can see, we have modified the value of `comAlarmInstructions` in two different agents at the same time. The same can be done for assets with **AssetList's <Anchor label="PATCH Request" target="_blank" href="https://developer.ixon.cloud/reference/patch_assets-1">PATCH Request</Anchor>** with the same request body structure as the one above, provided that you have the needed assets' `publicId`.

> 🚧 Important note on `newKey`
>
> If you choose to test this with the help of IXON's Endpoint documentation, you might see something like this after expanding the `custom` object in the body params:
>
> ![](https://files.readme.io/39b372d5e2ba91f0a6548c729ae77a40c18223a4a653330f4746b6cd79501ac3-image.png)
>
> This can potentially cause confusion, as the `newKey` string is **NOT** "new" and does **NOT** consist of a new custom field's identifier, but instead it consists of the **existing** identifier that you want to assign a value to or change the value of, such as `comInstructionsManual`, and `New Value` will consist of the value that you want to assign to it. You cannot possibly ask the endpoint to change the value of a `key` that does not exist.
>
> No verbs of this endpoint, including PATCH, can create a new custom field. **MyCompanyCustomPropertyList** is the only endpoint that can create a new custom field  as mentioned in Step 1, and the value of the`Identifier` (in this case `newKey`) is generated upon creation of the custom field. This is how `custom` should look like in a valid PATCH request:
>
> <Image align="center" border={true} src="https://files.readme.io/080b0c6c27e2e8e3118bea63e3c3700debd250a067c47f93f48afcf2230db2e7-image.png" className="border" />