Custom Attributes (ca_values)
The create and patch endpoints for both objectives and key results accept a ca_values object for setting custom attribute values. This section describes its shape and validation rules; the individual endpoints below reference it rather than repeating the details.
ca_values is a JSON object that maps a custom attribute's configuration ID (a string key) to a value. The expected value depends on the attribute's configured type. Custom attributes are defined per workspace, and each is enabled for objectives, key results, or both.
Value formats by type
|
Type
|
Expected value
|
Example
|
|
text
|
A non-empty string, 1–1000 characters (measured after trimming surrounding whitespace).
|
"Strategic initiative"
|
|
numeric
|
A number — integer or decimal. Numeric strings are also accepted.
|
42 or "42.5"
|
|
date
|
A string in YYYY-MM-DD format.
|
"2026-09-30"
|
|
singleselect
|
The selected option's ID, as a string.
|
"766"
|
|
multiselect
|
An array of option ID strings.
|
["766", "770"]
|
For singleselect and multiselect, the value is the option's ID, not its display label. Look up option IDs from the custom attribute's configuration.
Mandatory attributes, and create vs. patch behavior
-
On create, every custom attribute marked mandatory for the object type must be supplied with a valid, non-empty value. Omitting a mandatory attribute — or sending it as null or empty — returns 400 with error code MISSING_MANDATORY_CA.
-
On patch, updates are partial: send only the attributes you want to change. You do not need to resend the full mandatory set. However, a mandatory attribute cannot be cleared — sending a mandatory attribute as null or empty returns 400 MISSING_MANDATORY_CA. Optional attributes may be cleared by sending null.
Custom attribute error codes
|
error_code
|
Meaning
|
|
MISSING_MANDATORY_CA
|
A mandatory custom attribute is missing or empty on create, or an attempt was made to clear a mandatory attribute on patch.
|
|
INVALID_CONFIG_ID
|
No custom attribute configuration exists for the supplied key/ID.
|
|
CA_NOT_APPLICABLE_FOR_OBJECT_TYPE
|
The custom attribute exists but is not enabled for this object type (objective vs. key result).
|
|
INVALID_VALUE_FOR_TEXT_FIELD
|
Value is not a string, or its length is outside 1–1000 non-whitespace characters.
|
|
INVALID_VALUE_FOR_NUMERIC_FIELD
|
Value cannot be parsed as a number.
|
|
INVALID_VALUE_FOR_DATE_FIELD
|
Value is not a valid YYYY-MM-DD date.
|
|
INVALID_VALUE_FOR_SINGLESELECT_FIELD
|
Value is not a non-empty string, or is not one of the attribute's eligible option IDs.
|
|
INVALID_VALUE_FOR_MULTISELECT_FIELD
|
Value is not a non-empty array, or contains one or more ineligible option IDs.
|
Example validation error
Validation failures return the standard error envelope. The error field is a JSON-encoded array; for custom attribute failures its message is itself an array of {message, error_code} entries — one per failing attribute — wrapped under the operation's outer error code:
{
"error": "[{\"message\": [{\"message\": \"Mandatory custom attribute 'Owner' (ID 5) is required for objective\", \"error_code\": \"MISSING_MANDATORY_CA\"}], \"error_code\": \"CANNOT_CREATE_OBJECTIVE\"}]",
"path": "$",
"code": "unexpected"
}
