Custom Properties
Define custom fields on contacts to capture data specific to your workflow
Custom properties let you extend contacts with fields tailored to your business. Each property defines a field type, display name, and validation rules. Property values are then stored on individual contacts using the property's key.
How It Works
Properties are scoped to an object type (currently contacts).
A property definition looks like this:
{
"key": "custom.lead_status",
"type": "single-select",
"name": "Lead Status",
"options": [
{ "label": "New", "value": "new", "color": "blue" },
{ "label": "Contacted", "value": "contacted", "color": "yellow" },
{ "label": "Qualified", "value": "qualified", "color": "green" }
]
}Organization and Workspace Properties
Choose where a property belongs based on where it should be available.
| Organization property | Workspace property | |
|---|---|---|
| Available in | Every workspace in the organization | One workspace |
| Manage through | Organization Properties endpoints | Workspace Properties endpoints |
| Best for | Shared fields such as lead source or customer segment | Workspace-specific processes and data |
Workspace list and get operations include organization properties by default, with organization properties returned before workspace properties. Pass includeOrgProperties=false to return only workspace properties.
Every property response includes a read-only scope field indicating whether the property belongs to the organization or workspace. Use the move endpoint matching its current scope to reorder any property or move a custom. property between owners. Built-in properties cannot change owners. Moving a property does not remove existing values from contacts.
Keys
Every custom property key must start with custom. followed by a descriptive identifier. Keys are dot-separated paths and must be unique within the object type.
| Key | Description |
|---|---|
custom.lead_status | A lead qualification status |
custom.company_name | The contact's company |
custom.deal_value | The monetary value of a deal |
custom.referral_source | How the contact found you |
Keys are immutable after creation — you cannot rename a property key, only delete and recreate.
Properties created from the UI have an auto-generated key (e.g., custom.wRhEVPXBZiIEx2RImfmfG).
When creating properties via the API, you choose your own key — use something descriptive like
custom.lead_status.
Property Types
| Type | Description | Extra fields |
|---|---|---|
text | Short text input | — |
textarea | Multiline text | — |
single-select | One option from a list | options, defaultValue |
multi-select | Multiple options from a list | options |
user-select | Workspace member picker | — |
url | URL input | — |
email | Email address | — |
tel | Phone number | — |
amount | Monetary value | — |
Select Options
single-select and multi-select properties require an options array. Each option has:
| Field | Type | Description |
|---|---|---|
label | string | Display label |
value | string | Stored value (immutable) |
color | string? | One of: gray, brown, orange, yellow, green, blue, purple, pink, red |
Common Fields
Every property supports these fields:
| Field | Type | Description |
|---|---|---|
key | string | Unique identifier (must start with custom.) |
type | string | Property type (see above) |
name | string | Display name shown in the UI |
description | string? | Help text for the field |
placeholder | string? | Input placeholder text |
required | boolean | Whether the field is required (default: false) |
Managing Properties
Use the endpoint matching the property's scope to update, delete, or move it. Workspace list and get operations include organization properties by default; pass includeOrgProperties=false for workspace-only results.
Create workspace property
Add a custom property to one workspace
List effective properties
Retrieve organization and workspace property definitions
Create organization property
Add a custom property to every organization workspace
Move property
Reorder a property or change its scope
Deleting a property removes only the definition — existing values on contacts are not cleaned up.