Custom attributes

Add typed fields to customers, companies, conversations, messages and custom objects using name suffixes and attribute metadata.

Custom attributes are your own fields on Kustomer objects. They live under a custom key, and the suffix of each name sets its type:

JSON
{
  "custom": {
    "loyaltyTierStr": "gold",
    "lifetimeValueNum": 1840.5,
    "lastOrderAt": "2026-10-02T15:04:05Z",
    "marketingOptInBool": true,
    "accountUrl": "https://admin.acme.example/customers/10293",
    "notesTxt": "Prefers email. Allergic to latex."
  }
}

Suffixes

SuffixTypeExample nameExample value
StrShort string, up to 1,024 charactersloyaltyTierStr"gold"
TxtText, shown as a multi-line fieldnotesTxt"Prefers email."
NumNumberlifetimeValueNum1840.5
AtDate and time (ISO 8601)lastOrderAt"2026-10-02T15:04:05Z"
BoolBooleanmarketingOptInBooltrue
UrlURLaccountUrl"https://..."
IdReference to another objectprimaryOrderId"5822a4a5aa5f92110005d69a"

Every type also accepts null to clear the value. Use camelCase and keep names stable: the system name is what the API, workflows and search use, even if an admin later changes the display name.

InteractiveFrom label to attribute name
Type suffix
Try
1Split into words
Ordernumber
2camelCase
orderNumber
3Add the suffix
orderNumberStrShort string, up to 1,024 characters
Key you send

orderNumberStr is camelCase and ends in Str, so its value is a short string. Every type also accepts null to clear it.

In the API
PATCH /v1/customers/{id}
{
"custom": {
"orderNumberStr": "4417"
}
}
200 OK
In Kustomer
JD
Jane Doe
jane.doe@example.com
Order Number4417
Search and workflow conditions use customer_custom_orderNumberStr
Names are built in your browser from the rules on this page. The agent card is a simplified mock: without metadata, the label is the default display name, title-cased and without the suffix.

Which objects support them

Customers, companies, conversations, messages, notes, users, KObjects and tracked events. Each object type has its own set of attributes, configured separately.

Attribute metadata

Metadata tells Kustomer how to present and validate each attribute: its display name, type, allowed values, and whether it's sensitive. Admins can edit it in Settings › Platform › Klasses, or you can manage it through the API.

get/v1/metadata/{resource} put/v1/metadata/{resource}

resource is one of customer, company, conversation, message, note, user, kobject, kobject.<klassSlug>, event or event.<suffix>.

cURL
curl -X PUT "https://acme.api.kustomerapp.com/v1/metadata/customer" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "loyaltyTierStr": {
        "displayName": "Loyalty tier",
        "enumeration": ["bronze", "silver", "gold"]
      },
      "lifetimeValueNum": { "displayName": "Lifetime value" },
      "primaryOrderId": {
        "displayName": "Primary order",
        "target": "kobject.ecomm-order"
      }
    }
  }'

Metadata properties

properties.<name>
displayNamestring
Label shown in Kustomer. Defaults to the title-cased name without its suffix: totalOrdersNum becomes "Total Orders".
typestring
Set automatically from the suffix, for example number for Num.
enumerationstring[]
Allowed values. Kustomer shows a dropdown instead of a free-text field.
targetstring
For Id attributes: the type of object referenced, such as kobject.ecomm-order.
multiboolean
For Id attributes: allow a list of references.
sensitiveobject
{ "enabled": true, "maskType": "..." } marks the attribute as sensitive so it's masked for users without unmasking permission.

A single request can set up to 100 properties.

Using custom attributes elsewhere

  • Search. Custom attributes are searchable with names like customer_custom_loyaltyTierStr or kobject_custom_ecomm-order_orderStatusStr. See Search.
  • Workflows and business rules. Use them in conditions (for example customer_custom_loyaltyTierStr equals gold) and set them in actions. See Conditions and variables.
  • Apps. Declare them in an app definition so they're configured on install. See Klasses.