Use Cases Custom Fields

Read and write custom field values on a use case.

Reading values without a second call

A use case read carries the values it has set, on its custom_fields attribute, so the common case costs no extra request:

Python
TypeScript

use_case = client.use_cases.get("use_case-123")

for field in use_case.custom_fields or []:
    print(field.name, field.value)

const { data } = await client.useCases.get('use_case-123');

for (const field of data?.customFields ?? []) {
  console.log(field.name, field.value);
}

It is on the list endpoint too, so a page of use cases arrives with its values attached. Three things to know about it:

Only fields that have been set appear. The get method below returns every field that applies to the use case, set or not. Use it when you need to know what a caller could set.
definition is null. The platform has no way to include a value's definition on a use-case read, so use get below (or the definitions registry) when you need a field's type or permitted options.
null is not []. An empty list means no values are set; null means the response does not carry them, which today is only the create response. Read the use case back to see values set at creation.

Models and vendors have no equivalent — the platform does not expose the relationship on those entity types, so their values come only from the routes below.

Methods

`get`

List Use Case Custom Fields

Every custom field that applies to the use case is returned, whether or not a value has been set — an unset field comes back with a null value. Each entry also carries its definition, so you can see a field's type and permitted options without a second call.

Python
TypeScript

fields = client.use_cases("use_case-123").custom_fields.get()

for field in fields:
    print(field.name, field.value)

const { data, error } = await client.useCases.customFields.list('use_case-123');

Returns: A list of CustomFieldValue items

`update`

Set Use Case Custom Field

Sets one custom field value. Identify the field by either custom_field_id or name — exactly one, not both.

Python
TypeScript

from credoai import CustomFieldValueUpdate

# By name
client.use_cases("use_case-123").custom_fields.update(
    CustomFieldValueUpdate(name="Business Unit", value="Finance"),
)

# By ID
client.use_cases("use_case-123").custom_fields.update(
    CustomFieldValueUpdate(custom_field_id="C6K8LCdr8CnrUtNPRTqT28", value="Finance"),
)

# Multi-value fields take a list; null clears a field
client.use_cases("use_case-123").custom_fields.update(
    CustomFieldValueUpdate(name="Reviewers", value=["user-1", "user-2"]),
)
client.use_cases("use_case-123").custom_fields.update(
    CustomFieldValueUpdate(name="Business Unit", value=None),
)

// By name
await client.useCases.customFields.update('use_case-123', {
  name: 'Business Unit',
  value: 'Finance',
});

// By ID
await client.useCases.customFields.update('use_case-123', {
  customFieldId: 'C6K8LCdr8CnrUtNPRTqT28',
  value: 'Finance',
});

// Multi-value fields take an array; null clears a field
await client.useCases.customFields.update('use_case-123', {
  name: 'Reviewers',
  value: ['user-1', 'user-2'],
});

Parameters:

data (CustomFieldValueUpdate, required) - Request payload

Returns: A list of the updated CustomFieldValue items — always a list, whether you set one field or several.

Custom fields can also be set inline when creating or updating a use case, through the custom_fields array on the request — the same addressing rules apply.

Setting several fields at once

Pass values, a map of field name to value, and they are set in one request.

Python
TypeScript

client.use_cases("use_case-123").custom_fields.update(
    CustomFieldValueUpdate(values={
        "Business Unit": "Finance",
        "Review Tier": 3,
    }),
)

await client.useCases.customFields.update('use_case-123', {
  values: { 'Business Unit': 'Finance', 'Review Tier': 3 },
});

Names are resolved before anything is written, so an unknown or ambiguous name fails the whole request with nothing applied.

Addressing by name

Custom field names are not guaranteed unique: a definition that applies to every entity type and one targeted at a specific type can share a name. A name is resolved against the definitions that apply to this use case, and is rejected if it matches none of them or more than one. When a name is ambiguous, the error lists the candidate IDs so you can pass custom_field_id instead.

Error Handling

Status	Meaning
`422`	Neither or both of `custom_field_id` and `name` were given; the name matched no field on this use case; the name was ambiguous; or the value did not match the field's type or permitted options.
`404`	No such use case.
`403`	The API key's role cannot edit this use case.

Reading values without a second call​

Methods​

get​

update​

Setting several fields at once​

Addressing by name​

Error Handling​