# Custom Properties (/docs/custom-properties)



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 [#how-it-works]

Properties are scoped to an object type (currently `contacts`).

A property definition looks like this:

```json
{
  "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 [#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](/docs/api/organization-properties/organizationProperties.list) endpoints | [Workspace Properties](/docs/api/workspace-properties/workspaceProperties.list) 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 [#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.

<Callout type="info">
  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`.
</Callout>

## Property Types [#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 [#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 [#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 [#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.

<Cards>
  <Card href="/docs/api/workspace-properties/workspaceProperties.create" title="Create workspace property">
    Add a custom property to one workspace
  </Card>

  <Card href="/docs/api/workspace-properties/workspaceProperties.list" title="List effective properties">
    Retrieve organization and workspace property definitions
  </Card>

  <Card href="/docs/api/organization-properties/organizationProperties.create" title="Create organization property">
    Add a custom property to every organization workspace
  </Card>

  <Card href="/docs/api/workspace-properties/workspaceProperties.move" title="Move property">
    Reorder a property or change its scope
  </Card>
</Cards>

<Callout type="warn">
  Deleting a property removes only the definition — existing values on contacts are not cleaned up.
</Callout>