Custom Fields

Custom fields are tenant-defined metadata attached to governance entities — a business unit, a cost centre, a review tier.

A definition is tenant-level and says what the field is: its name, value type, input control, and permitted options. A value is one entity's assignment of that definition. Definitions are listed here; values are read and written on the entity itself, under Use Cases, Models and Vendors.

Methods

list

List Custom Fields

Returns every custom field defined for the tenant. Pass entity_type to narrow the list to the definitions that apply to one entity type; definitions that apply to every entity type are always included.

Python

response = client.custom_fields.list()

# Only the fields that apply to use cases
response = client.custom_fields.list(entity_type="use_case")

TypeScript

const { data, error } = await client.customFields.list();

// Only the fields that apply to use cases
const { data: useCaseFields } = await client.customFields.list({
  entityType: 'use_case',
});

Parameters:

• entity_type (string, optional) - Query parameter. One of use_case, model, or vendor.

Returns: Paginated CustomFieldDefinition items

This index is not paginated upstream, so every definition is returned in a single page and pagination.has_more is always false.

---

create

Create Custom Field

Defines a new custom field for the tenant. It applies to every entity type unless entity_type_ids names the ones it should be limited to.

Python

from credoai import CustomFieldCreate

response = client.custom_fields.create(
    data=CustomFieldCreate(
        name="Business Unit",
        type="string",
        element_type="select",
        options=["Finance", "Legal", "Marketing"],
    ),
)

TypeScript

const { data, error } = await client.customFields.create({
  name: 'Business Unit',
  type: 'string',
  elementType: 'select',
  options: ['Finance', 'Legal', 'Marketing'],
});

Parameters:

• data (CustomFieldCreate, required) - Request payload

Returns: The created CustomFieldDefinition

---

update

Update Custom Field

Changes only the attributes supplied.

Python

from credoai import CustomFieldUpdate

response = client.custom_fields.update(
    custom_field_id="C6K8LCdr8CnrUtNPRTqT28",
    data=CustomFieldUpdate(options=["Finance", "Legal", "Marketing", "Ops"]),
)

TypeScript

const { data, error } = await client.customFields.update(
  'C6K8LCdr8CnrUtNPRTqT28',
  { options: ['Finance', 'Legal', 'Marketing', 'Ops'] },
);

Parameters:

• custom_field_id (string, required) - Path parameter
• data (CustomFieldUpdate, required) - Request payload

Returns: The updated CustomFieldDefinition

entity_type_ids is add-only: entity types can be added to a definition but not removed from it.

Deleting a definition is not exposed here — it also deletes every entity's value for that field, so it stays an administrative action in the Governance Center.

---

Finding a field's ID

Custom fields are identified by an opaque ID. Rather than looking one up and passing it around, you can address a field by name when setting a value — see Use Case Custom Fields. Listing definitions is still the way to discover what fields exist, what type each one is, and which options a select field permits.

Python

for field in client.custom_fields.list(entity_type="use_case").items:
    print(field.id, field.name, field.type, field.options)

TypeScript

const { data } = await client.customFields.list({ entityType: 'use_case' });
for (const field of data?.items ?? []) {
  console.log(field.id, field.name, field.type, field.options);
}

Error Handling

Status	Meaning
403	The API key's role cannot manage custom field definitions. Reading them is open to every role; creating and updating them is an administrative action.
422	name was missing on create, or type/element_type was not one of the permitted values.
404	No such custom field.