Contacts and leads

A contact is one person, keyed by phone number, that a sub-account can call: a lead that has just arrived and has never been dialled, one part-way through a cadence, one already called, or somebody who called you. The record exists from the moment the lead arrives, which is why a contact with callCount of 0 is an ordinary contact and not a missing one. The contact record is where you answer “how many times did we try, what happened, and when do we try again?” It is also where you say “never call this person”. Where contacts live depends on the sub-account. One with a CRM connected keeps its contacts there, and the platform keeps the calling history against each CRM contact. A sub-account with no CRM keeps its contacts on the platform: add them in the dashboard, import a CSV, post them with your API key, or point a form at the sub-account’s lead link. See Adding contacts by API, and Contacts without a CRM for managing them afterwards: custom fields, do-not-call, deletion and the lead link.

What one contact holds

GET /api/contacts returns one row per unique contact.

Field	Meaning
`id`	The contact record id.
`contactId`	The contact’s id in whichever system holds it: the GoHighLevel contact id, or the native contact id, which starts with `nct_`. A contact may have none, and is then reachable by number only, so treat it as optional.
`phoneNumber` and `leadName`	Who they are.
`projectName` and `locationId`	Which project they belong to. `locationId` also builds the deep link into the sub-account.
`dateAdded`	The day the platform first saw them, at midnight UTC.
`leadGeneratedAtInCrm` and `leadGeneratedAtInCrmPrecision`	When the sub-account’s CRM created the lead, and whether that is an exact `time` or only a `day`. See How old a lead was when it arrived.
`leadReceivedByTfuAi`	The exact moment the lead reached the platform.
`callCount`	How many calls they have had.
`disposition`	The most recent outcome, as `type`, `label`, `color`, and the appointment details when there was a booking.
`nextScheduledCall`	`nextCallTime` and `cadenceStep` when the power dialer has a call queued.
`isInternal`	`true` when you have marked this contact as one of your own test leads.

How old a lead was when it arrived

A lead is usually created in the CRM and sent to the platform seconds later. A lead from an old list is different: it was created months ago and only sent now. The gap between leadGeneratedAtInCrm and leadReceivedByTfuAi tells the two apart.

leadGeneratedAtInCrmPrecision is time when the CRM sent the exact moment, and day when it sent only the date. A day value reads as midnight UTC, so measure gaps under a day only when it is time.
leadReceivedByTfuAi is null for leads received before it was recorded. For those, dateAdded gives the day only.
leadGeneratedAtInCrm is null when the CRM sent no creation date.

GET /api/contacts/{phoneNumber}/calls returns everything the platform has done with one person: their calls and a dispositionSummary counting how the calls ended.

Outcome types on a contact

A contact’s disposition.type and the disposition filter use these values:

Value	Meaning
`appointment`	Booked an appointment.
`appointmentConfirmed`	Confirmed an appointment they already had.
`appointmentRescheduled`	Moved an appointment to another time.
`appointmentCancelled`	Cancelled an appointment.
`callBack`	Asked to be called back.
`askedForInfo`	Asked for information.
`whatsAppFollowUp`	Asked to carry on over WhatsApp.
`humanNeeded`	Needs someone on your team to take over.
`liveTransfer`	Was handed to a person.
`failedTransfer`	A transfer was attempted and did not connect.
`killSwitch`	Opted out. Asked not to be called again.
`disqualified`	Was a wrong number, did not qualify, or was not interested.
`tagged`	The call applied a tag in GoHighLevel. `tagged` never masks another outcome. Tagged plus booked reads `appointment`.
`spamDetected`	The other person said one of the campaign’s spam call phrases in the first seconds, so the call was ended and nothing ran after it. `spamDetected` never masks another outcome.

These are the contact-level names. The per-call outcome constants that workflows route on, such as SUCCESS and KILL_SWITCH, are listed in What your agent records.

Five ways to stop calling someone

They look similar and they are not. Pick the one that matches who decided and how wide it reaches.

Mechanism	Who decides	Reach	How
Standby after a booking	The engine, when the lead books	The whole project	The lead is tagged `tfu_ai_standby` and no campaign in the project calls them while it stays. Callbacks they asked for, reminders and confirmation calls still go ahead. Cancelling the booking or removing the tag lets campaigns call them again, but does not call them by itself; the next trigger does. The campaign’s execution history lists these under Not called.
Exit tag	Your CRM automation, or you	One campaign	The contact picks up a tag listed in the campaign’s `inactiveTags` and leaves that campaign’s list. See Who gets called.
Opt-out outcome	The agent, on the call	The whole project	The lead asks to stop. The call ends `KILL_SWITCH`, the contact is tagged `tfu_ai_kill_switch`, and every campaign in the project treats them as opted out.
Do-not-call flag	You, deliberately	The whole project	Stop calling on the contact, or `PATCH /api/contacts/{contactId}` with `doNotCall: true` and the project’s `locationId`. On GoHighLevel this adds the same `tfu_ai_kill_switch` tag as an opt-out.
GoHighLevel DND	The contact record in GoHighLevel	Per campaign setting	A campaign skips contacts who arrive with Do Not Disturb on, unless Call leads marked Do-Not-Disturb is on. If DND is turned on later for a contact already here, it becomes a stop for the whole project.

How far each way of stopping calls reaches. Opting out on a call, Stop calling and a booking block every campaign in the sub-account; callbacks and reminders still go after a booking. An inactive tag blocks only the campaign that lists it.

On GoHighLevel, the do-not-call flag and an opt-out are the same tag. Clearing the flag also clears an opt-out the lead asked for on a call, so check why a contact was stopped before you clear it.

Exit tags and GoHighLevel DND need the sub-account to use GoHighLevel. A sub-account that keeps its contacts here has one flag for both the opt-out and do-not-call, shown as the Do not call switch, and a booking pauses calls there too; see Contacts without a CRM.

Clearing a do-not-call flag can produce a call that should not be placed. Treat doNotCall: false as a deliberate act, and scope API keys that hold contacts:write accordingly.

Your own test leads

You will dial yourself and your team while building. Mark those contacts as internal with PATCH /api/contacts/{contactId} and isInternal: true, identifying the contact by contactId, or by phone number with idType: phone, with the project’s locationId. The response’s actionResults reports each flag as saved, or unconfirmed when the save failed part-way. In the dashboard it is Mark as internal on the contact, and it covers that phone number across the sub-account, past calls included.

Their calls are left out of every performance figure: lead counts, booking and transfer rates, pickup, trends and the heatmap.
Their cost is kept. The minutes were really spent and really billed, so the dashboard stays in step with your wallet.
They still get called. The mark changes reporting only.

GET /api/contacts lists them by default with isInternal set on each row. Send internal=only to see just them, or internal=exclude to hide them. Clear the mark with isInternal: false.

Adding contacts by API

For a sub-account that keeps its contacts on the platform (no CRM connected), post one lead at a time:

curl -X POST https://api.teamfollowup.ai/api/contacts/add/{locationId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+13125550142","first_name":"Ana","last_name":"Diaz","email":"ana@example.com"}'

The key needs contacts:write. phone is required. first_name, last_name (or name), email, timezone, address1, city, state and postalCode are optional, and so is any of the sub-account’s custom fields, by its key or its name. A number already in the sub-account updates that contact instead of adding it twice, and a blank never erases a value. A new contact starts any campaign whose trigger is “New contact”. The response is 201 for a new contact and 200 for an update, with the contact’s id either way. A form, Zapier or Make step that cannot set a header can post the same body to the sub-account’s lead link instead, shown under API and webhook on the Contacts page. The secret in that link is its only credential: keep it private, and regenerate it from the same place if it leaks. A sub-account with a CRM keeps its contacts there and answers 400. Reading, updating and deleting those contacts, defining the custom fields your prompts read, and rotating the lead link are all in Contacts without a CRM.

Finding contacts

To find	Send
One project’s contacts	`locationId`. Several at once: `locationIds`, comma-separated. Names are display labels and cannot select contacts.
Contacts one campaign dialled	`campaignId`
Contacts an entire master agent dialled, across every linked project	`masterCampaignId`. Mutually exclusive with `campaignId`.
Contacts one split-test variant spoke to	`agentVariantId`, together with `campaignId`
By outcome	`disposition`, repeated or comma-joined
With or without a call queued	`nextCall`: `none` for contacts the power dialer has nothing queued for, `scheduled` for those it has, `all` for both (the default). It agrees with each contact’s `nextScheduledCall`. In the dashboard it is the Next call filter.
By name, number or id	`search`
Added in a date range	`dateFromUTC` and `dateToUTC`. A plain `YYYY-MM-DD` covers the whole day.
Added on your own days, not UTC days	`tz` beside the dates, an IANA zone such as `America/Los_Angeles`. A contact is then matched on the moment in `leadReceivedByTfuAi`; one received before that was recorded is matched on its `dateAdded` day. See Dates and times.

Sort with sortBy (leadName, phoneNumber, projectName, dateAdded, callCount) and sortOrder (asc, desc). Page with page and limit. Project ids come from GET /api/v2/projects; disposition takes the outcome constants in What your agent records. On one contact, include accepts calls to return their calls with the record.

Boundaries

A contact is unique per phone number within a project.
projectName on a write is a display label only. locationId is the tenant identity.
Marking a contact internal never suppresses a call. Use the do-not-call flag for that.

In the API

List contacts; project filter values come from List projects
Get contact, with include=calls for the person’s calls
Update contact sets or clears doNotCall and isInternal
Add a contact posts a lead into a sub-account that keeps its contacts on the platform (no CRM connected)
Every field above is defined in the Glossary

Call records hold the per-call detail behind each contact.
Backfill existing leads enrols contacts that were already in the CRM.

Start here

How it works

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Voices

CRM connections

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

What one contact holds

How old a lead was when it arrived

Outcome types on a contact

Five ways to stop calling someone

Your own test leads

Adding contacts by API

Finding contacts

Boundaries

In the API

​What one contact holds

​How old a lead was when it arrived

​Outcome types on a contact

​Five ways to stop calling someone

​Your own test leads

​Adding contacts by API

​Finding contacts

​Boundaries

​In the API

​Related

What one contact holds

How old a lead was when it arrived

Outcome types on a contact

Five ways to stop calling someone

Your own test leads

Adding contacts by API

Finding contacts

Boundaries

In the API

Related