Lead custom fields
What this page is — extra fields you can add to the lead record, defined once and available on every lead.
What it is for — capturing what your business actually qualifies on — industry, company size, budget, whether the contact can sign — without waiting for a product change.
The problem it solves — the built-in fields do not know your sales process. Custom fields let you record it, and they are the main thing scoring and assignment rules test. This page also covers the payload mistake that makes custom-field values invisible while appearing to save.
Route: /org/marketing/leads/settings?tab=fields
Permissions: View custom field definitions · .create · .edit · .delete
Section revealed by: Manage Lead Pipelines
Custom Fields has its own four permissions for the definitions themselves, but whether the section appears in the hub at all is decided by Manage Lead Pipelines. Granting the custom-field permissions alone does not reveal it.
1. What a custom field is
| Custom field | Tag | Native field | |
|---|---|---|---|
| Structure | Typed, optionally with options | A free label | Fixed |
| Defined once | Yes | No | — |
| Testable by rules | Yes | No | Yes |
| Example | industry = Healthcare | q3-target | company_name |
2. Field reference — the definition
| Field | Notes |
|---|---|
| Field name | The label shown on the record |
| Field key | The identifier. This is what scoring rules and integrations must use |
| Type | text · textarea · number · date · boolean · url · select · multi_select |
| Options | For select and multi_select — the permitted values |
| Required | Whether the record demands it |
A rule condition names is_decision_maker, not Decision Maker. Renaming a label is safe; changing a
key breaks every rule and integration that references it.
3. How values reach a lead
| Path | Notes |
|---|---|
| The lead record's Custom Fields panel | The adder offers definitions with no value yet |
API or webhook, in custom_fields | Must be a JSON object |
| Bulk update | For a selection |
| CSV import | Not supported — the importer reads four columns only |
Integration platforms commonly stringify nested JSON by default. If custom_fields arrives as text
containing JSON rather than as an object, the request is rejected with "custom_fields must be a JSON
object" — so the problem surfaces at the integration, not weeks later as rules that quietly do not
match. See the webhook reference.
4. The admin contract
| Needs | Or |
|---|---|
| Definitions before values | Values are stored and displayed nowhere |
| Keys matching what integrations send | Same |
manage_pipelines | The section is hidden |
Options on a select | The picker is empty |
5. Downstream
| A custom field reaches | As |
|---|---|
| The lead record | The Custom Fields panel |
| Scoring rules | A testable condition field |
| Assignment rules | A testable condition field |
| Quality report | A segmentation dimension |
6. Don't confuse this with…
| This | Not this |
|---|---|
| Field key | Field name |
| A custom field | A tag |
A select field's options | Lead grades or statuses |
7. Troubleshooting
| Symptom | Cause |
|---|---|
| An integration's values never arrive | Its request is being rejected — check for the custom_fields error. Section 3 |
| A rule on a custom field does not match | Check the rule names the field key, not its label. Section 2 |
| Section missing from the hub | Needs manage_pipelines. Section header |
| Import ignored custom-field columns | The importer reads four columns only |
| A rule cannot find a field | It names the label instead of the key. Section 2 |