web sdk custom fields

Working with custom fields

Custom fields allow you to extend Security Center entities with additional properties specific to your business needs. This guide covers creating custom fields, reading/writing values, filtering by custom fields, and important limitations.

What are custom fields?

Custom fields are user-defined properties that can be added to Security Center entities. They allow you to store additional information beyond the standard entity properties.

Common use cases

• Employee badge numbers
• Department codes
• Building access levels
• Training dates
• Equipment identifiers
• Custom business logic data

Supported data types

Custom fields support these data types:

Data type	Description	Example value	Notes
Text	String value	"Engineering"	Defaults to empty string if omitted.
Numeric	Integer value	12345	Signed 32-bit integer.
Boolean	True/false value	true	None.
DateTime	Date and time	"2025-01-15T10:30:00+08:00"	ISO 8601 format, supports timezone.
Date	Date only	"2025-01-15T00:00:00Z"	Time is always midnight UTC.
Decimal	Decimal number	99.99	Up to 15 significant digits.
Image	Binary image data	Base64-encoded	Write not supported through the Web SDK.
Entity	Reference to another entity	GUID	Links to Security Center entity.

Required privileges

These routes require an account that can connect through the Web SDK.

Creating or deleting custom field definitions requires General settings > Modify custom field definitions.

Reading or updating custom field values also requires access to the target entity and access to the custom field in Security Center. For cardholders, cardholder groups, credentials, and visitors, updating values also requires the corresponding Modify custom fields privilege for that entity type.

Creating custom fields

Use the custom-field creation route to add one field definition to a specific entity type:

POST /customField/{entityType}/{customFieldName}/{dataType}/{defaultValue}

Parameters

• entityType - Entity type (for example, Cardholder, Credential, Door).
• customFieldName - Name of the custom field (spaces are accepted but limit q= access; see Limitations).
• dataType - Data type (Text, Numeric, Boolean, DateTime, Date, Decimal, Image, Entity).
• defaultValue - Default value applied at creation. Required for Numeric, Boolean, DateTime, Date, and Decimal. Optional for Text, Image, and Entity; omit with a trailing slash, for example POST /customField/Cardholder/MyField/Image/.

Examples

POST /customField/Cardholder/DepartmentCode/Text/IT
POST /customField/Cardholder/BadgeNumber/Numeric/0
POST /customField/Cardholder/IsContractor/Boolean/false
POST /customField/Cardholder/LastTrainingDate/DateTime/DateTime.Now

For DateTime fields, the special values DateTime.Now (current local time) and DateTime.UtcNow (current UTC time) are accepted as the default.

Responses

A successful request returns:

{
  "Rsp": {
    "Status": "Ok"
  }
}

A duplicate field name returns:

{
  "Rsp": {
    "Status": "Fail",
    "Result": {
      "Message": "The property Name is invalid. The property Name should be unique by EntityType, Owner and CustomEntityTypeId in case of CustomEntity EntityType."
    }
  }
}

Reading custom field values

There are two ways to read custom field values: a dedicated endpoint and the entity query syntax.

Read with the dedicated endpoint

Use the dedicated endpoint when you need to read a single custom field:

GET /customField/{entityId}/{customFieldName}

For example:

GET /customField/{entity-guid}/DepartmentCode

The response wraps the typed value in a Value field:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Value": "Sales"
    }
  }
}

The data type of the field is preserved in the response:

• Text fields return strings: "Value": "Engineering".
• Numeric fields return numbers: "Value": 12345.
• Boolean fields return booleans: "Value": true.
• DateTime fields return ISO 8601 strings: "Value": "2025-01-15T10:30:00+08:00".

Read through the entity endpoint

Custom fields can be queried like standard entity properties using the /entity endpoint. Use this approach when reading multiple fields in a single request:

GET /entity?q=entity={guid},CustomFieldName

Read a single custom field:

GET /entity?q=entity={entity-guid},DepartmentCode

Read multiple custom fields:

GET /entity?q=entity={entity-guid},DepartmentCode,BadgeNumber,IsContractor

Read custom fields and standard properties together:

GET /entity?q=entity={entity-guid},Name,FirstName,LastName,DepartmentCode,BadgeNumber

Important

If a custom field name matches a standard entity property name on the same entity type, the custom field is returned first in /entity?q=.... For example, if an entity has a custom field named Name, GET /entity?q=entity={guid},Name returns the custom field value, not the built-in Name property. Use the /customField/... endpoint when you need unambiguous custom-field access.

The response merges custom field values with any requested standard properties:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Name": "New_Cardholder_6225b1afcdf44f2798ccd531fd2d0320",
      "FirstName": "Test",
      "LastName": "User",
      "DepartmentCode": "Sales",
      "BadgeNumber": 12345
    }
  }
}

Writing custom field values

There are two ways to set custom field values: a dedicated endpoint and the entity update syntax.

Update with the dedicated endpoint

Use the dedicated endpoint when you need to update a single custom field:

PUT /customField/{entityId}/{customFieldName}/{value}

Examples:

PUT /customField/{entity-guid}/DepartmentCode/Engineering
PUT /customField/{entity-guid}/BadgeNumber/12345
PUT /customField/{entity-guid}/IsContractor/true
PUT /customField/{entity-guid}/LastTrainingDate/2025-01-15T10:30:00

Each data type accepts a string representation in the path:

• Text: Any string value.
• Numeric: Integer string (for example, "12345").
• Boolean: "true" or "false" (case-insensitive).
• DateTime: ISO 8601 string, or "DateTime.Now", or "DateTime.UtcNow".
• Date: Date string (for example, "2025-02-03"). The value is stored as midnight UTC.
• Decimal: Decimal string (for example, "99.99").
• Entity: Entity GUID, with or without braces. LogicalId(...) is not accepted on the /customField/... route.

A successful update returns:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Update through the entity endpoint

Custom fields can be updated like standard entity properties using the /entity endpoint. Use this approach when updating multiple fields in a single request:

POST /entity?q=entity={guid},CustomFieldName=value

Update a single custom field:

POST /entity?q=entity={entity-guid},DepartmentCode=Sales

Update multiple custom fields:

POST /entity?q=entity={entity-guid},DepartmentCode=Engineering,BadgeNumber=54321,IsContractor=false

Update custom fields and standard properties together:

POST /entity?q=entity={entity-guid},FirstName=Jane,DepartmentCode=Marketing,BadgeNumber=99999

A successful update returns:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Deleting custom fields

Delete the field definition only after confirming it is no longer needed on any entity of that type. Deletion removes the custom field from all entities of the specified type.

DELETE /customField/{entityType}/{customFieldName}

For example:

DELETE /customField/Cardholder/OldFieldName

A successful deletion returns:

{
  "Rsp": {
    "Status": "Ok"
  }
}

Important

Deleting a custom field removes it from all entities. This operation cannot be undone.

Filtering by custom fields

Custom fields can be used as filters in EntityConfiguration reports. Filtering by a DateTime custom field is not supported: a CustomField(...) expression that targets a DateTime-typed field fails with SdkErrorCode: InvalidOperation and a message that names the rejected field.

Syntax

GET /report/{EntityType}Configuration?q=CustomFields@CustomField(customFieldGuid,value)

The expression takes two arguments:

• customFieldGuid - GUID of the custom field (not the field name).
• value - Value to filter by.

Important

You must use the custom field's GUID, not its name. Custom field GUIDs can be obtained by querying an entity with the custom field set (see example below).

Examples

Use these examples to adapt the pattern in this section to your scenario.

Filter cardholders by a single custom field:

GET /report/CardholderConfiguration?q=CustomFields@CustomField({custom-field-guid},IT)

Filter by multiple custom fields (logical AND). Returns only entities where DepartmentCode is "IT" and IsContractor is true:

GET /report/CardholderConfiguration?q=CustomFields@CustomField({custom-field-guid},IT)@CustomField({custom-field-guid-2},true)

Combine with an entity type filter:

GET /report/EntityConfiguration?q=EntityTypes@Cardholder,CustomFields@CustomField({custom-field-guid},Sales)

A typical response returns the GUIDs of matching entities:

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {"Guid": "984c7ac2-6c76-44c0-be2d-1de009b2a259"},
      {"Guid": "631d3540-e293-469f-8a64-22b282cd7fd0"}
    ]
  }
}

Obtaining custom field GUIDs

To get a custom field's GUID, read the CustomFields property of any entity that has the custom field defined:

GET /entity?q=entity={entity-guid},CustomFields

The response contains an array of custom field entries. Each entry has a nested CustomField object with the field definition, including the GUID:

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "CustomFields": [
        {
          "CustomField": {
            "DefaultValue": "",
            "CustomEntityTypeId": "00000000-0000-0000-0000-000000000000",
            "EntityType": "Cardholder",
            "GroupName": "",
            "GroupPriority": 1,
            "Guid": "{custom-field-guid}",
            "Mandatory": false,
            "IsEncrypted": false,
            "Name": "DepartmentCode",
            "Owner": "00000000-0000-0000-0000-000000000000",
            "ShowInReports": true,
            "Unique": false,
            "ValueType": "Text",
            "CustomDataType": null
          },
          "Name": "DepartmentCode",
          "ValueType": "Text",
          "Value": "Sales"
        }
      ]
    }
  }
}

Use the Guid value from the CustomField object in report filter queries.

Custom field properties

When retrieving entity data, each custom field includes these properties:

Core properties

• Name (string) - Custom field name
• Guid (GUID) - Unique identifier for the custom field
• EntityType (enum) - Entity type this field applies to
• ValueType (enum) - Data type (Text, Numeric, Boolean, etc.)
• Value (varies) - Current value for this entity
• DefaultValue (varies) - Default value when not set

Configuration properties

• Mandatory (boolean) - Whether field is required
• Unique (boolean) - Whether values must be unique
• IsEncrypted (boolean) - Whether values are encrypted
• ShowInReports (boolean) - Whether field appears in reports
• GroupName (string) - UI grouping name
• GroupPriority (int) - Display order in UI
• Owner (GUID) - Owner entity GUID
• CustomEntityTypeId (GUID) - For custom entity types

Limitations and important notes

Image fields are read-only through the Web SDK

• Use GET /entity?q=entity={guid},FieldName to read the value; it is returned as Base64.
• The dedicated GET /customField/{entityId}/{customFieldName} route rejects Image reads.
• No documented Web SDK path accepts writes to Image values. Populate them through another mechanism.

Field names with spaces or special characters

Custom fields with spaces in names can be created through the /customField endpoints (URL-encode the name in the path, for example Audit%20Field), but they cannot be accessed through the q= query syntax. Even if you URL-encode the spaces (for example, /entity?q=entity={guid},Audit%20Field), the request fails.

Use camelCase or underscore naming for maximum compatibility. Examples: DepartmentCode, Badge_Number, EmployeeID.

Custom field names are case-sensitive

The name must match the exact casing used when the field was created. This applies to both the /customField/ endpoints and the q= query syntax.

Default values are applied at creation time

When you create a custom field with a default value, existing entities receive that value. New entities created after the custom field exists also receive the default value.

Use report endpoints for custom-field filtering

The /entity endpoint reads or updates entities that you already identified. It does not perform cross-entity filtering. To filter entities by a custom field value, use a configuration report such as /report/EntityConfiguration or /report/CardholderConfiguration.

Custom field GUIDs are required for filtering

Report filters require the custom field GUID, not the name. Custom field names cannot be used in CustomField() filter syntax.

Value type enforcement

Setting an invalid value for a data type returns an error. For example, setting "abc" for a Numeric field returns "Could not convert abc based on Numeric.".

Custom entity types do not support custom field creation

Creating custom fields for CustomEntity is not supported.

See also

• The /entity endpoint: The /entity endpoint and shared q= query syntax.
• Referencing entities: Entity discovery, search, and parameter formats.