> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lead Custom Fields: Capture Extra Prospect Data

> Create and manage custom fields for leads in Workspace Config so your team can track industry, budget, referral source details, and other prospect data beyond the default CRM fields.

Lead custom fields let you store extra information on each prospect — beyond name, email, company, and the default CRM fields. Define the fields once in **Workspace Config**, then fill them in on every lead card.

<Note>
  Only **SuperAdmin** and **Admin** roles can create, edit, or delete custom field definitions. Team members with lead access can fill in values on lead profiles.
</Note>

## Before you start

* Access to **Workspace Config** → **Custom Fields**
* A plan that includes CRM custom fields for your workspace

## How lead custom fields work

1. An admin creates a **definition** (name + type) with **Belongs to = Lead**.
2. That definition appears on every lead profile in the workspace.
3. Your team (or Claude/Cursor via MCP) fills a **value** on each lead.
4. Lead and client fields are separate catalogs. A lead field named `Industry` does **not** automatically create a client field with the same name.

## Create a lead custom field

<Steps>
  <Step title="Open Custom Fields">
    Go to **Workspace Config** → **Custom Fields**.
  </Step>

  <Step title="Start a new field">
    Click **Create Custom Field**.
  </Step>

  <Step title="Choose Lead as the owner">
    In **Belongs to**, select **Lead**. The field will appear only on lead profiles (not on clients or tasks).
  </Step>

  <Step title="Name the field and pick a type">
    Enter a clear **name** (for example, `Industry` or `Estimated budget`). Choose a **type**:

    | Type                         | Use for                          |
    | ---------------------------- | -------------------------------- |
    | **Text**                     | Free-form notes or short answers |
    | **Number**                   | Budgets, scores, quantities      |
    | **Boolean**                  | Yes/no flags                     |
    | **Dropdown (Single Select)** | One choice from a list           |
    | **Dropdown (Multi Select)**  | Multiple choices from a list     |
    | **Attachment**               | Files related to the lead        |

    For dropdown types, add the allowed **options**. Toggle **Required** if the field must be filled when creating or editing a lead.
  </Step>

  <Step title="Save">
    Click **Create**. The field appears in the Custom Fields list with belongs-to **Lead**.
  </Step>
</Steps>

<Tip>
  Use names your sales team already uses in calls and spreadsheets. Consistent labels make filters and handoffs clearer.
</Tip>

## Duplicate field names

AgencyHandy blocks a second **lead** field with the same name (case and spacing ignored). Examples:

| You try to create | Existing lead field          | Result                                              |
| ----------------- | ---------------------------- | --------------------------------------------------- |
| `Industry`        | `Industry`                   | Not created — **Field already exists**              |
| `industry`        | `Industry`                   | Not created (same name after normalize)             |
| `  Budget  `      | `budget`                     | Not created (whitespace normalized)                 |
| `Industry`        | Client field `Industry` only | **Allowed** — lead and client catalogs are separate |

If create is blocked for a duplicate, use the existing field from the list (or via `ah_custom_field_list`) instead of creating another.

## Fill in values on a lead

<Steps>
  <Step title="Open a lead">
    Go to **CRM** → **Leads** and open a lead card.
  </Step>

  <Step title="Open the Custom Fields tab">
    In the lead detail view, open the **Custom Fields** section or tab.
  </Step>

  <Step title="Enter values and save">
    Complete the fields your workspace defined, then save. Values stay with the lead through pipeline stages.
  </Step>
</Steps>

## Use with Claude or Cursor (MCP)

With [AgencyHandy MCP](/integrations/claude-cursor-mcp) (`agencyhandy-mcp@1.5+`):

1. List lead definitions: ask Claude to list lead custom fields (`ah_custom_field_list`, type `lead`).
2. Fill values by **definition id** — never invent ids.
3. Create a lead and set fields in one step, or set values on an existing lead.
4. To **update** a value later, open the member’s fields first (`ah_member_custom_fields`) and prefer the existing value row id when one is already filled.

Example prompts:

* “List our lead custom fields.”
* “Create a lead for Nora at Bright Studio and set Industry to Agency software.”
* “On lead [nora@brightstudio.com](mailto:nora@brightstudio.com), set Estimated budget to 12000.”

Admins can also create definitions from MCP (`ah_custom_field_create`). Duplicate names return in `notCreatedCustomFields` with reason **Field already exists**.

## Convert a lead that has custom fields

When you **Convert to Client**, AgencyHandy can prompt you to carry over lead custom fields that should also exist on the client.

* If matching **client** custom fields already exist, map or copy values during conversion.
* If a lead field has no client equivalent, create the client field first under **Workspace Config** → **Custom Fields** (belongs to **Client**), or skip that value.

See [Client Custom Fields](/crm/client-custom-fields) for defining client-side fields.

## Manage existing lead fields

From **Workspace Config** → **Custom Fields**:

* **Search** or filter by name and belongs-to (**Lead**)
* **Edit** the field name, options, or required setting
* **Delete** fields you no longer need (existing values on leads may be cleared — confirm before deleting)

## Related

* [Leads](/crm/leads) — pipeline, email, and conversion
* [Client Custom Fields](/crm/client-custom-fields) — fields that appear on client profiles
* [Clients](/crm/clients) — client list, import, and portal access
* [Claude & Cursor MCP](/integrations/claude-cursor-mcp) — fill fields from AI tools