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

# Lead Fields

> Give each lead its own details, like the product they ordered or their renewal date, and the agent knows them on the call.

A lead can carry fields of your own next to its name and phone number: `order_number`, `product`, `renewal_date`, whatever your script needs. On every call to that lead, Live or Standard, the agent sees the lead's name, notes and these fields. So your instructions can say "mention the product they ordered" and the agent says the right product to each person.

## What the agent sees

| Field | Seen by the agent |
| - | - |
| `name` | Yes |
| `notes` | Yes, up to 1,000 characters |
| Your own fields | Yes, up to 20 per lead, each value up to 256 characters |
| `email`, `status`, `tags` | No. Put a value in a field of your own if the agent needs it. |

When a lead has more than 20 fields of your own, the agent sees the first 20, sorted by field name (capital letters sort before lowercase ones). Empty fields don't count toward the 20. Keep field names to 64 characters or fewer. Line breaks inside a value become spaces.

## Add fields to your leads

### CSV upload in the dashboard

Add a column named `metadata` and put a JSON object in it for each row. Other column names that TopCalls doesn't know, such as a plain `product` column, are ignored, so the fields have to go inside `metadata`.

```csv theme={null}
name,phone_number,notes,metadata
Ana Pop,+40721000000,Asked for a call after 5 PM,"{""product"": ""Pro plan"", ""renewal_date"": ""2026-12-01""}"
```

A row whose `metadata` isn't a valid JSON object is skipped, and the import page lists it with the reason. See [Campaigns](https://docs.topcalls.ai/concepts/campaigns.md) for the rest of the CSV columns.

### API

Send the fields as `metadata` on `POST /v1/leads` or `POST /v1/leads/bulk`. `PATCH /v1/leads/{id}` with `metadata` replaces every stored field of that lead.

```json theme={null}
{
  "phone_number": "+40721000000",
  "name": "Ana Pop",
  "metadata": { "product": "Pro plan", "renewal_date": "2026-12-01" }
}
```

For a single call, `lead_context` on `POST /v1/calls` gives the agent the fields directly, or `lead_id` loads them from a lead you already have.

### MCP

The `import_leads` tool takes a `fields` object on each row, up to 50 per row. The agent still sees at most 20 of them on a call.

## Use the fields in a campaign

**1. Pick the lists**

In the campaign editor, tick the lead lists under **Who it calls**.

**2. Write the opening line**

In **What it says**, the chips under the opening line include the fields your lists carry. Select one to insert it, for example `{{product}}`. It fills in for each lead before the call, and the filled-in line is reviewed before the call is placed.

**3. Write the instructions**

In the instructions, describe what to do with the fields in plain words: "Confirm the renewal date with them" or "Ask how they like their product." In the instructions, `{{name}}` fills in with the lead's name. Other placeholders such as `{{product}}` fill in the opening line only and stay as typed in the instructions. The agent already sees the lead's name and your other fields.

**4. Test it**

Place a [test call](https://docs.topcalls.ai/guides/test-your-campaign.md) to a lead that has the fields, and listen for them.

After a call, the call's page in the dashboard shows the lead's fields under **Custom Fields**.

## What stays with you

The agent uses what is in the field, as it is. A wrong date in your list is a wrong date on the call, so check the data before you import it.

Every dial reviews the lead's data together with the name and notes. When a value tries to make the agent say something fraudulent, that call is refused before it is placed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.