Custom Fields API

Custom fields allow you to extend Kordon resources with additional attributes specific to your organization’s needs. You can add custom fields to various resource types like Requirements, Assets, Risks, and more.

Field Types

Available field types (kind):

• string - Text input field
• number - Numeric input field
• boolean - True/false checkbox
• date - Date picker
• select - Dropdown with predefined options
• multiselect - Multiple selection dropdown

Currently Supported

Only string type is currently supported. Other field types are planned for future releases.

Field Configuration

The configuration object contains type-specific settings:

• For select and multiselect: List of available options
• For number: Min/max values, decimal places
• For string: Max length, validation rules

Permissions

The permissions object indicates what actions the current user can perform:

• update - Can modify the custom field
• destroy - Can delete the custom field
• connect - Can use the field on resources
• changelog - Can view the field’s change history

GET /custom_fields/

List all custom fields in your organization.

Fields

Field	Type	Description
id	UUID	Unique identifier for the custom field.
name	string	Internal name of the field (lowercase with underscores).
label	string	Display name shown to users.
description	string	Optional description of the field’s purpose.
kind	string	Field type (string, number, boolean, date, select, multiselect). Currently only string is supported.
attribute_of	string	Resource type this field belongs to (e.g., “Requirement”, “Asset”).
is_required	boolean	Whether the field must be filled in. (Not yet implemented)
is_shown_in_detail_view	boolean	Whether the field is displayed in the resource detail view.
public	boolean	Whether the field is visible to all users. (Not yet implemented)
configuration	object	Type-specific settings and options.
permissions	object	User permissions: update, destroy, connect, changelog.
created_at	timestamp	ISO 8601 timestamp when the field was created.
updated_at	timestamp	ISO 8601 timestamp of last update.

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/custom_fields/" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": [
        {
            "id": "83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f",
            "attribute_of": "Requirement",
            "configuration": {},
            "created_at": "2026-02-20T11:19:53+00:00",
            "description": "",
            "is_required": false,
            "is_shown_in_detail_view": false,
            "kind": "string",
            "label": "my custom field",
            "name": "my_custom_field",
            "permissions": {
                "update": true,
                "destroy": true,
                "connect": true,
                "changelog": true
            },
            "public": true,
            "updated_at": "2026-02-20T11:19:53+00:00"
        }
    ],
    "meta": {
        "total_count": 1,
        "page": 1,
        "permissions": {
            "create": true
        }
    }
}

GET /custom_fields/:id

Retrieve a specific custom field by ID.

curl --location GET \
--url "https://YOUR_KORDON_DOMAIN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 200

{
    "data": {
        "id": "83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f",
        "attribute_of": "Requirement",
        "configuration": {},
        "created_at": "2026-02-20T11:19:53+00:00",
        "description": "",
        "is_required": false,
        "is_shown_in_detail_view": false,
        "kind": "string",
        "label": "my custom field",
        "name": "my_custom_field",
        "permissions": {
            "update": true,
            "destroy": true,
            "connect": true,
            "changelog": true
        },
        "public": true,
        "updated_at": "2026-02-20T11:19:53+00:00"
    }
}

POST /custom_fields/

Create a new custom field.

Field	Type	Required	Description
name	string	Yes	Internal field name (lowercase, underscores only).
label	string	Yes	Display name shown to users.
kind	string	Yes	Field type: string, number, boolean, date, select, multiselect. Currently only string is supported.
attribute_of	string	Yes	Resource type: Requirement, Asset, Risk, Control, etc.
description	string	No	Optional description of the field’s purpose.
is_required	boolean	No	Whether the field must be filled. Default: false. (Not yet implemented)
is_shown_in_detail_view	boolean	No	Display in detail view. Default: false.
public	boolean	No	Visible to all users. Default: true. (Not yet implemented)
configuration	object	No	Type-specific settings (e.g., options for select fields).

curl --location POST \
--url "https://YOUR_KORDON_DOMAIN/api/v1/custom_fields/" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
    "name": "compliance_status",
    "label": "Compliance Status",
    "kind": "select",
    "attribute_of": "Requirement",
    "description": "Track the compliance status of requirements",
    "is_required": true,
    "is_shown_in_detail_view": true,
    "public": true,
    "configuration": {
        "options": ["Not Started", "In Progress", "Compliant", "Non-Compliant"]
    }
}'

Example Response

Status: 201

{
    "data": {
        "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
        "attribute_of": "Requirement",
        "configuration": {
            "options": ["Not Started", "In Progress", "Compliant", "Non-Compliant"]
        },
        "created_at": "2026-02-20T12:30:45+00:00",
        "description": "Track the compliance status of requirements",
        "is_required": true,
        "is_shown_in_detail_view": true,
        "kind": "select",
        "label": "Compliance Status",
        "name": "compliance_status",
        "permissions": {
            "update": true,
            "destroy": true,
            "connect": true,
            "changelog": true
        },
        "public": true,
        "updated_at": "2026-02-20T12:30:45+00:00"
    }
}

PATCH /custom_fields/:id

Update an existing custom field.

Note

Changing the kind of a field that already has data may result in data loss or conversion issues.

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
    "label": "Updated Custom Field",
    "is_required": true,
    "is_shown_in_detail_view": true
}'

Example Response

Status: 200

{
    "data": {
        "id": "83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f",
        "attribute_of": "Requirement",
        "configuration": {},
        "created_at": "2026-02-20T11:19:53+00:00",
        "description": "",
        "is_required": true,
        "is_shown_in_detail_view": true,
        "kind": "string",
        "label": "Updated Custom Field",
        "name": "my_custom_field",
        "permissions": {
            "update": true,
            "destroy": true,
            "connect": true,
            "changelog": true
        },
        "public": true,
        "updated_at": "2026-02-20T13:45:22+00:00"
    }
}

DELETE /custom_fields/:id

Delete a custom field.

curl --location DELETE \
--url "https://YOUR_KORDON_DOMAIN/api/v1/custom_fields/83d028c1-9ce1-4f29-ad2b-994c2d0ebd4f" \
--header "Authorization: Bearer YOUR-TOKEN"

Example Response

Status: 204 No Content

---

Using Custom Fields on Resources

Once you’ve created a custom field, you can set its value on the corresponding resource type using a PATCH request. Use the custom field’s name as the key.

Setting a Custom Field Value

To set or update a custom field value on a resource (e.g., Requirement, Asset, Risk), include the field in a PATCH request to that resource’s endpoint.

Example: Setting a custom field on a Requirement

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/requirements/REQUIREMENT_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "requirement": {
    "my_custom_field": "Sunday test"
  }
}'

Example: Setting multiple fields including custom fields

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/requirements/REQUIREMENT_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "requirement": {
    "title": "Updated Requirement Title",
    "my_custom_field": "Custom value",
    "compliance_status": "In Progress"
  }
}'

Field Names

Use the name property of the custom field (not the label). For example, if you created a field with name: "my_custom_field", use that exact name in your PATCH requests.

Clearing a Custom Field Value

To clear a custom field value, set it to null or an empty string:

curl --location PATCH \
--url "https://YOUR_KORDON_DOMAIN/api/v1/requirements/REQUIREMENT_ID" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "requirement": {
    "my_custom_field": null
  }
}'