Custom Properties
Define custom fields on leads and Telegram accounts
Custom properties let you extend leads and Telegram accounts with fields tailored to your business. Each property defines a field type, display name, and validation rules. Values are stored on each object using the property's key.
How It Works
Properties are scoped to an object type: contacts or telegram-accounts. Definitions and values are independent between object types.
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 leads or Telegram accounts.
Keys
Every custom property key must match custom.<identifier> and be unique within the object type. Additional dots are not supported.
| 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 leads and Telegram accounts are not cleaned up.