Skip to main content
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

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.
A row whose metadata isn’t a valid JSON object is skipped, and the import page lists it with the reason. See Campaigns 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.
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 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.