Custom attributes
Extend the contact schema with your own typed fields — text, number, boolean, or date. Define attributes per agent, store values on every contact, archive fields you no longer use without losing data, and read or set them via the API.
View as MarkdownCustom attributes let you extend a contact beyond the built-in fields with your own typed data — a plan tier, lifetime value, signup date, a VIP flag, anything that matters to your business. You define them once per agent, and every contact on that agent can carry values for them.
How custom attributes work
An attribute is part of an agent's contact schema. Defining one adds a typed field that appears as a column in the Contacts table and as an input in the add/edit form. Each contact stores its own value for the attribute.
Every attribute has:
| Property | Description |
|---|---|
| Name | The machine key — must start with a letter and contain only letters, numbers, underscores, or hyphens, and is unique per agent. This is what you reference in the API. |
| Label | The human-friendly display name shown in the dashboard. |
| Type | One of text, number, boolean, or date — drives validation and the input control. |
| Description | Optional notes on what the attribute is for. |
| Archived | Whether the attribute is hidden from the UI (its data is kept). |
The name is the stable key you use in code and the API (e.g. plan_tier); the label is the friendly text shown in the dashboard (e.g. "Plan tier"). You can change the label freely; treat the name as permanent once contacts reference it.
Attribute types
Pick the type that matches your data — it controls how values are validated and how the dashboard renders the input.
| Type | Stores | Examples |
|---|---|---|
| Text | Free-form strings. | Plan name, account tier, region, internal note. |
| Number | Numeric values. | Lifetime value, order count, loyalty points. |
| Boolean | True / false. | VIP, opted-in to marketing, churn risk. |
| Date | A calendar date. | Signup date, last order date, renewal date. |
A number stored as text can't be sorted or compared numerically, and a date stored as text won't behave like a date. Choosing the correct type when you define the attribute keeps your data clean and your table sortable.
Defining attributes in the dashboard
Use the Manage attributes view on an agent's Contacts tab:
- 1Open Manage attributesFrom the Contacts tab, open the attribute manager.
- 2Create an attributeGive it a name, a label, a type, and an optional description. The name is validated to be a clean machine key, unique on this agent.
- 3Set values on contactsThe new attribute appears as a typed input in the add/edit form and as a selectable column in the table.
Archiving attributes
When you no longer need an attribute, archive it rather than deleting it. Archiving hides the attribute from the dashboard and the column picker but keeps the values already stored on contacts — so you don't lose historical data. You can restore an archived attribute later, and it reappears with its data intact.
Deleting an attribute removes it from the schema. Archiving is the safer default: it cleans up the UI while preserving the data, and it's reversible. Reach for delete only when you're sure the field and its data are no longer needed.
Custom attributes and the API
Both the schema and the values are available over the API. You can list and create attributes, and set their values when you create or update a contact — passing values keyed by the attribute name. See:
- Custom attributes API — manage the attribute schema programmatically.
- Create contacts and Update a contact — set attribute values on contacts.
Values you set via the API are validated against the attribute's type, the same as the dashboard — so a number attribute expects a number, a date attribute expects a date, and so on.
Examples worth defining
A few attributes that pay off for most ecommerce stores:
plan_tier(text) — so the agent and team know the customer's plan at a glance.lifetime_value(number) — sortable, so you can find your most valuable customers.vip(boolean) — flag accounts that should get white-glove handling.signup_date(date) — useful for cohorts and tenure-based logic.