Get custom attribute metadata
/v1/metadata/{resource}org.permission.metadata.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves the metadata properties for the custom attributes of a specific resource (for example, Company, Conversation, Customer, Message, and KObject (custom Object)).
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.
Path parameters
Resource for custom attribute metadata retrieval. Valid values: company, conversation, customer, message, note, user, kobject, kobject.<klassSlug>, event, and event.<suffix>.
"customer"Query parameters
Page number of results to return.
1Number of results to return per page.
100Set to false to return untranslated metadata.
falseExample "false"Comma-separated related resources to include when supported by the endpoint.
"customer,conversation"Responses
OK