Skip to main content
Version: 1.0

Custom Fields

Introduction

Custom fields allow users to assign custom attributes to people. For example, a custom field could be used to store an employee ID. These values can then be set and retrieved via the customAttributes property of the person object. Custom fields are scoped to a partition, so each partition can have a separate set of custom fields.

The custom field object

{
"id": "test_custom_field",
"type": "string",
"displayName": "Test Custom Field",
"visibility": "visible"
}
PropertyTypeDescription
idStringThe field ID.
typeStringThe field type. Possible values include array, boolean, enum (dropdown), number, object (field group), and string.
displayNameStringThe field display name.
requiredBooleanWhether the field is required. The default value is false.
visibilityStringThe visibility setting. Possible values include hidden, readonly, and visible. The default value is visible.
itemsObjectA custom field object that defines the properties of the items in an array field.
minLengthIntegerThe minimum number of items in an array field.
maxLengthIntegerThe maximum number of items in an array field.
valuesObject[]An array of objects representing the values in an enum (dropdown) field. Each object in the array has a required id parameter and an optional displayName parameter.
minIntegerThe minimum value in a number field.
maxIntegerThe maximum value in a number field.
decimalsIntegerThe number of decimal places allowed in a number field.
fieldsObject[]An array of custom field objects that define the child fields within an object field (field group).
regexStringA regular expression used for validation of a string field.

Basic Endpoints

Create a custom field

Request

POST https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/attributes/single HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
"id": "test_custom_field",
"type": "string",
"displayName": "Test Custom Field"
}
ParameterLocationTypeRequiredDescription
panel_idPathStringYesThe cloud node serial number.
partition_idPathIntegerYesThe partition ID.
panel_tokenHeaderStringYesA valid panel token.
idBodyStringYesThe field ID.
typeBodyStringYesThe field type. Possible values include array, boolean, enum (dropdown), number, object (field group), and string.
displayNameBodyStringNoThe field display name. If this value is not provided, the id will be used as the display name.
requiredBodyBooleanNoWhether the field should be required. The default value is false.
visibilityBodyStringNoThe visibility setting. Possible values include hidden, readonly, and visible. The default value is visible.
itemsBodyObjectSometimesA custom field object that defines the properties of the items in an array. This is required when type is set to array. Unlike its parent, this child object does not have an id property, but the type property is required. Possible values for the type property include boolean, enum (dropdown), number, and string.
minLengthBodyIntegerNoThe minimum number of items in an array field.
maxLengthBodyIntegerNoThe maximum number of items in an array field.
valuesBodyObject[]SometimesAn array of objects representing the values in a dropdown field. This is required when type is set to enum. Each object in the array has a required id parameter and an optional displayName parameter.
minBodyIntegerNoThe minimum value in a number field.
maxBodyIntegerNoThe maximum value in a number field.
decimalsBodyIntegerNoThe number of decimal places allowed in a number field. The minimum is 0 and the maximum is 10.
fieldsBodyObject[]SometimesAn array of custom field objects that define the child fields within a field group. This is required when type is set to object. The id and type properties are required for each child object. Possible values for the type property include boolean, enum (dropdown), number, and string.
regexBodyStringNoA regular expression used for validation of a string field. The maximum length is 255 characters.

Response

The response contains the ID of the newly created custom field object.

HTTP/1.1 200 OK
Content-Type: application/json

{
"id": "test_custom_field"
}

Retrieve a custom field

Request

GET https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/attributes/{{attribute_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
ParameterLocationTypeRequiredDescription
panel_idPathStringYesThe cloud node serial number.
partition_idPathIntegerYesThe partition ID.
attribute_idPathStringYesThe custom field ID.
panel_tokenHeaderStringYesA valid panel token.

Response

The response contains a custom field object.

HTTP/1.1 200 OK
Content-Type: application/json

{
"id": "test_custom_field",
"type": "string",
"displayName": "Test Custom Field",
"visibility": "visible"
}

Update a custom field

Request

PUT https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/attributes/{{attribute_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
"type": "string"
}
ParameterLocationTypeRequiredDescription
panel_idPathStringYesThe cloud node serial number.
partition_idPathIntegerYesThe partition ID.
attribute_idPathStringYesThe custom field ID.
panel_tokenHeaderStringYesA valid panel token.
typeBodyStringYesThe field type. Possible values include array, boolean, enum (dropdown), number, object (field group), and string.
displayNameBodyStringNoThe field display name. If this value is not provided, the id will be used as the display name.
requiredBodyBooleanNoWhether the field should be required. The default value is false.
visibilityBodyStringNoThe visibility setting. Possible values include hidden, readonly, and visible. The default value is visible.
itemsBodyObjectSometimesA custom field object that defines the properties of the items in an array. This is required when type is set to array. Unlike its parent, this child object does not have an id property, but the type property is required. Possible values for the type property include boolean, enum (dropdown), number, and string.
minLengthBodyIntegerNoThe minimum number of items in an array field.
maxLengthBodyIntegerNoThe maximum number of items in an array field.
valuesBodyObject[]SometimesAn array of objects representing the values in a dropdown field. This is required when type is set to enum. Each object in the array has a required id parameter and an optional displayName parameter.
minBodyIntegerNoThe minimum value in a number field.
maxBodyIntegerNoThe maximum value in a number field.
decimalsBodyIntegerNoThe number of decimal places allowed in a number field. The minimum is 0 and the maximum is 10.
fieldsBodyObject[]SometimesAn array of custom field objects that define the child fields within a field group. This is required when type is set to object. The id and type properties are required for each child object. Possible values for the type property include boolean, enum (dropdown), number, and string.
regexBodyStringNoA regular expression used for validation of a string field. The maximum length is 255 characters.

Response

HTTP/1.1 204 No Content

Delete a custom field

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/attributes/{{attribute_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
ParameterLocationTypeRequiredDescription
panel_idPathStringYesThe cloud node serial number.
partition_idPathIntegerYesThe partition ID.
attribute_idPathStringYesThe custom field ID.
panel_tokenHeaderStringYesA valid panel token.

Response

HTTP/1.1 204 No Content

List all custom fields

Request

GET https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/attributes HTTP/1.1
Authorization: Bearer {{panel_token}}
ParameterLocationTypeRequiredDescription
panel_idPathStringYesThe cloud node serial number.
partition_idPathIntegerYesThe partition ID.
panel_tokenHeaderStringYesA valid panel token.

Response

The response contains an array of custom field objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"id": "test_custom_field_1",
"type": "string",
"visibility": "visible",
"displayName": "Test Custom Field 1"
},
{
"id": "test_custom_field_2",
"type": "string",
"visibility": "visible",
"displayName": "Test Custom Field 2"
}
]

Update all custom fields

Request

The request contains an array of custom field objects. Note that this operation will overwrite all existing custom fields.

POST https://panel-{{panel_id}}.pdk.io/api/partitions/{{partition_id}}/attributes/all HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

[
{
"id": "test_custom_field_1",
"displayName": "Test Custom Field 1",
"type": "string"
},
{
"id": "test_custom_field_2",
"displayName": "Test Custom Field 2",
"type": "string"
}
]
ParameterLocationTypeRequiredDescription
panel_idPathStringYesThe cloud node serial number.
partition_idPathIntegerYesThe partition ID.
panel_tokenHeaderStringYesA valid panel token.

Response

HTTP/1.1 204 No Content