Update custom attribute metadata

put/v1/metadata/{resource}
Requires any one of these rolesAbout roles
org.permission.metadata.update
Legacyorg.admin.metadata.write

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Sets the metadata properties for custom attributes on any of the available resources (for example, Company, Conversation, Customer, Message, and KObject (custom Object)).

Metadata property options are dependent on the data type as specified by the suffix of the property name. The displayName default value is set to the title cased version of the camelCase property name and the type is determined automatically. For example, a property named totalOrdersNum will have a default displayName value of Total Orders (if no alternative displayName value is set) and the type is set to number based on the Num suffix in the property name totalOrdersNum.

To learn more about options for metadata properties, visit Klasses.

Note

When you configure metadata property types for custom attributes, you must configure metadata for custom properties ending with Id before you can use the attributes. When you update these properties, Kustomer validates these values to ensure that the related object exists and matches the specified target type.

When configuring attributes as sensitive, note that some attributes will inherit any permissions and metadata from other attributes. These are

  • customer.externalId inherits permissions and metadata from customer.externalIds
  • customer.firstName, customer.lastName, and customer.displayName inherits permissions and metadata from customer.name

Custom Attributes

Custom attributes are optional and allow you to specify custom key-value pairs.

Kustomer uses a naming convention for custom attributes to specify the field data type with a name suffix:

Naming Suffix

  • Num number or null
  • At date-time or null
  • Str string or null, length: [ 0 .. 1024 ] characters
  • Txt string or null, length: [ 0 .. 1024 ] characters
  • Bool boolean or null
  • Url string or null, format: uri
About this resource

Custom attributes

Custom attributes are your own fields on Kustomer objects, such as a loyalty tier on a customer or an order number on a conversation. Their metadata tells Kustomer each field's label, type, allowed values and sensitivity.

Every customer, company, conversation, message, note, user, KObject and tracked event can carry custom attributes in its custom object, and the suffix of each attribute's name sets its type. Metadata is the per-object-type configuration that makes these fields usable in Kustomer. It gives each attribute the label agents see in the agent desktop, turns a string into a dropdown of allowed values, links an ID to another object, or marks a field as sensitive. Admins edit the same metadata in Kustomer's settings.

Naming conventions

Attribute names are camelCase and end in a type suffix:

Suffix Type Example
Str String, up to 1,024 characters loyaltyTierStr
Txt Text, shown as a multi-line field notesTxt
Num Number lifetimeValueNum
At Date and time lastOrderAt
Bool Boolean marketingOptInBool
Url URI accountUrl
Id Reference to another object primaryOrderId

Every type also accepts null. Keep names stable: the API, workflows and search use the system name (search uses forms like customer_custom_loyaltyTierStr), even if an admin later changes the display name.

Metadata resources and properties

The resource path parameter picks which object type's attributes you are configuring: customer, company, conversation, message, note, user, kobject, kobject.<klassName> for one Klass, event, or event.<suffix>. The body's properties maps attribute names to their settings: displayName (defaults to the title-cased name without its suffix, so totalOrdersNum becomes "Total Orders"), enumeration for allowed values, target for what an Id attribute points to, and sensitive to mask the value. standardProperties configures built-in attributes the same way, for example to mark them sensitive.

An attribute ending in Id must have metadata before you write values to it, because Kustomer checks that each value refers to an existing object of the target type. Some standard attributes inherit sensitivity from others: customer.externalId follows customer.externalIds, and customer.firstName, customer.lastName and customer.displayName follow customer.name.

Which endpoint to use

To Call
Read the attribute configuration for an object type GET /v1/metadata/{resource}
Add or change attribute labels, types, allowed values or sensitivity PUT /v1/metadata/{resource}

PUT merges: it only touches the attributes you include, merging your settings into what is already there, and sending null for an attribute removes its metadata. One request can set up to 100 properties. Pass translate=false to read display names without translation. Each object type has its own metadata, so configure customer and conversation attributes with separate requests.

RelatedCustom attributes conceptsKlassesCustomer unmasking windows

Path parameters

resourcestringrequired

Resource for custom attribute metadata retrieval. Valid values: company, conversation, customer, message, note, user, kobject, kobject.<klassSlug>, event, and event.<suffix>.

Example "customer"

Query parameters

translatestring

Set to false to return untranslated metadata.

One offalseExample "false"

Request body

application/jsonrequired
standardPropertiesobject
relationshipsobject
propertiesobject
validationsarray<string<object-id>>
max items 10 · unique items

Responses

OK

objectrequired