> ## 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.

# Client Custom Fields: Track Extra Client Details

> Create and manage custom fields for clients in Workspace Config so your team can capture contract terms, industry tags, preferred contact methods, and other client data beyond the default profile.

Client custom fields let you store extra information on each client profile — beyond name, email, company, and address. Define the fields once in **Workspace Config**, then fill them in on client profiles and keep them visible for the whole team.

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

## Before you start

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

## How client custom fields work

1. An admin creates a **definition** (name + type) with **Belongs to = Client**.
2. That definition appears on every client profile in the workspace.
3. Your team (or Claude/Cursor via MCP) fills a **value** on each client.
4. Client and lead fields are separate catalogs. Reusing the name `Industry` on clients is fine even if leads already have `Industry` — they are two definitions with different ids.

## Create a client 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 Client as the owner">
    In **Belongs to**, select **Client**. The field will appear only on client profiles (not on leads or tasks).
  </Step>

  <Step title="Name the field and pick a type">
    Enter a clear **name** (for example, `Contract renewal date` or `Preferred channel`). Choose a **type**:

    | Type                         | Use for                          |
    | ---------------------------- | -------------------------------- |
    | **Text**                     | Free-form notes or short answers |
    | **Number**                   | Seats, retainers, numeric scores |
    | **Boolean**                  | Yes/no flags (for example, VIP)  |
    | **Dropdown (Single Select)** | One choice from a list           |
    | **Dropdown (Multi Select)**  | Multiple choices from a list     |
    | **Attachment**               | Contracts, NDAs, or other files  |

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

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

<Tip>
  Mirror important lead fields on the client side when you regularly convert prospects. That makes conversion mapping smoother.
</Tip>

## Duplicate field names

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

| You try to create   | Existing client field | Result                                              |
| ------------------- | --------------------- | --------------------------------------------------- |
| `VIP`               | `VIP`                 | Not created — **Field already exists**              |
| `vip`               | `VIP`                 | Not created (same name after normalize)             |
| `Preferred channel` | `preferred channel`   | Not created                                         |
| `VIP`               | Lead field `VIP` only | **Allowed** — lead and client catalogs are separate |

If create is blocked for a duplicate, reuse the existing client field id from the list instead of creating another.

## Fill in values on a client

<Steps>
  <Step title="Open a client">
    Go to **CRM** → **Clients** and open a client profile.
  </Step>

  <Step title="Find Custom Fields">
    In the client profile, open the section that shows **Custom Fields** (often under primary information or a dedicated block).
  </Step>

  <Step title="Enter values and save">
    Complete the fields your workspace defined, then save. Values stay on the profile for orders, billing, and team handoffs.
  </Step>
</Steps>

## Use with Claude or Cursor (MCP)

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

1. List client definitions: `ah_custom_field_list` with type `client`.
2. Fill by **definition id** (`ah_custom_field_set_values` or `customFields` on `ah_client_create`).
3. To update an already-filled value, load the client with `ah_member_custom_fields` and prefer the existing value row id when present.

Example prompts:

* “List our client custom fields.”
* “Create client Ada Lovelace and set VIP to true.”
* “On client [ada@acme.com](mailto:ada@acme.com), set Preferred channel to Slack.”

## Carry fields over from a lead

When converting a lead to a client, you may be asked which **lead** custom fields to add or map onto the **client**.

1. Create matching **Client** custom fields first if they do not exist yet.
2. During conversion, select which lead fields to carry over.
3. Confirm values on the new client profile after conversion.

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

## Manage existing client fields

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

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

## Import and lists

Client list views and CSV import focus on standard profile columns. Custom field definitions still live in **Workspace Config**; fill custom values on each profile (or after import) so data stays consistent.

## Related

* [Clients](/crm/clients) — create, import, export, and portal access
* [Lead Custom Fields](/crm/lead-custom-fields) — fields on prospects before conversion
* [Leads](/crm/leads) — pipeline and convert to client
* [Claude & Cursor MCP](/integrations/claude-cursor-mcp) — fill fields from AI tools