> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Contacts
> Manage the people your Retell agents call and text: contact records keyed by phone number, custom contact fields, post-call data mappings, and CRM sync.
Contacts is your workspace's record of the people your agents talk to. Each contact is keyed by phone number and collects the conversations you've had with that person, along with any fields you choose to store about them. Those fields reach the agent as [dynamic variables](/build/dynamic-variables) on the next phone call, so it can open with what it already knows instead of asking again.
Open it from the **Contacts** tab under **Data** in the dashboard.
## When to use it
* **Your CRM is the source of truth.** Sync contacts in from [Salesforce or HubSpot](/integrations/crm-overview) and map their fields to agent variables once, instead of passing the same values on every API call.
* **Conversations span more than one call.** When a long call drops or the person calls back, the agent picks up with the context from last time rather than restarting discovery.
* **You run follow-up or chase sequences.** The next call can act on what the last one produced.
* **You want one set of fields across agents.** Post-call data mappings are set per workspace, not per agent, so every agent writes to the same contact fields.
### Example
A tutoring company runs 20-minute enrollment calls. They store `program_interest`, `budget_range`, and `last_topic_discussed` as contact fields, filled from [post-call analysis](/features/post-call-analysis-overview). When a prospect calls back after a dropped call, the agent already has all three and resumes at the pricing conversation instead of starting over.
## How contacts are created
Contacts arrive three ways, and all of them match on phone number:
* **Automatically, after a conversation.** When a phone call or SMS chat ends, Retell looks up the number (the caller's number on inbound, the number you dialed on outbound). If no contact matches, it creates one, then updates the contact's conversation count and last-conversation time. Web calls and web chats have no phone number, so they don't create contacts.
* **Manually**, from **Actions → Add contact**.
* **From your CRM**, if you've connected [Salesforce or HubSpot](/integrations/crm-overview) and configured inbound sync.
A phone number identifies exactly one contact. Adding a contact whose number already exists fails with "A contact with phone number +14155551000 already exists."
## Add a contact
Select **Actions → Add contact**.
Required, and it has to be a valid number. Use E.164 format, for example `+14155552671`. This is the key everything else matches on.
First name, last name, and **Do not call** are optional, as are any custom fields you've defined. Custom field values are checked against the field's type, so a number field rejects text and an enum field rejects values outside its options.
Select **Create**. The contact appears in the table right away, with no conversations attached until one happens.
## Work with the contacts table
The table lists every contact in the workspace with these built-in columns, plus one for each custom field you've defined:
| Column | What it shows |
| ---------------------- | ------------------------------------------------------------------------ |
| Phone Number | The contact's number, and the key used to match conversations. |
| First Name / Last Name | Set manually, synced from your CRM, or written by post-call analysis. |
| Contact ID | The record's identifier, for example `contact_9f2c41ab77de05c3aa61e480`. |
| Related Conversations | How many calls and chats are attached to this contact. |
| Latest Conversation | When you last spoke to them. |
| Do Not Call | A flag you can set, filter on, and sync with your CRM. |
| External ID | The record ID in the connected CRM, when the contact came from one. |
The settings icon above the table, labelled **Manage table**, controls which columns appear and in what order. The arrangement is saved for the workspace, so everyone sees the same table.
**Search** matches phone number, first name, last name, external ID, and custom field values.
**Filters** narrow by phone number, external ID (including whether one exists at all), do-not-call, last conversation time, and any custom field.
## Open a contact
Selecting a row opens a panel with two halves:
* **Contact information** lists every field on the record and lets you edit them in place. Saving an edit on a CRM-linked contact also pushes the change back to your CRM, if outbound sync is configured.
* **Conversations** lists the calls and chats attached to that number, newest first, with total time and a split of inbound calls, outbound calls, and messages. Selecting one opens the full session.
Use the up and down arrow keys to step through contacts without closing the panel.
## Define contact fields
Beyond the built-in fields, you can define custom fields to store anything else you want to keep about a person. Open **Actions → Manage contact fields**.
The fields table shows, for each field, its type, the CRM field it syncs with, the post-call analysis field that writes to it, and when it last changed.
Select **Add Contact Field**, then pick a **type**: Text, Number, Boolean, Selector, Date, or Datetime. Type is fixed after creation, so choose deliberately.
Field names are snake\_case: lowercase letters, numbers, and underscores, starting with a letter. Names can't collide with the built-in fields, can't start with `contact` or `external` (both reserved), and can't repeat an existing field.
The description tells you what the field captures. It does more than document: for fields filled by post-call analysis with **Accumulate & summarize**, the description is the instruction the model follows when combining an old value with a new one.
Turn on the post-call mapping, choose the analysis field that feeds it, and pick how new values combine with existing ones:
* **Overwrite** replaces the stored value every time.
* **Fill only if empty** writes once and leaves it alone after that.
* **Accumulate & summarize** merges the old and new values with a model, following your field description.
Mappings apply to the whole workspace, so any agent producing that analysis field writes to this contact field. See [CRM data mappings](/integrations/crm-mappings) for the full picture, and [contact memory](/integrations/build-contact-memory) for building running context this way.
Built-in fields behave differently from custom ones. First name, last name, and do-not-call can be edited and mapped, but not deleted. Phone number is fixed. Custom fields can be edited or deleted.
## Use contact data in a conversation
When a phone call starts, Retell looks up the contact by number and passes its fields to the agent as dynamic variables: `first_name`, `last_name`, `do_not_call`, and one per custom field, each named after the field. Reference them in the prompt the same way as any other [dynamic variable](/build/dynamic-variables), for example `{{first_name}}`.
This applies to inbound calls, outbound calls, and [batch calls](/deploy/make-batch-call). Chats update contacts after they end, but don't receive contact fields as variables. If no contact matches the number, the variables are simply absent, so write prompts that read naturally without them.
## Backfill fields from past conversations
New mappings only apply going forward. To apply one to conversations that already happened, select **Actions → Backfill from Post-Call Data**, choose which fields to fill, and scope the run by agent and call time.
A few things to know before you start:
* You need at least one post-call data mapping configured, or the run is rejected.
* One backfill runs at a time per workspace. Starting a second returns "A backfill job is already running."
* Progress shows as a banner on the Contacts page while the job runs.
## Keep contacts in sync with your CRM
With [Salesforce or HubSpot connected](/integrations/crm-overview), contacts sync both directions: CRM records flow in as contacts, and edits flow back out. Two entries in the **Actions** menu control it, both disabled until a CRM is connected:
* **Manage CRM sync** opens the field mapping settings. See [CRM data mappings](/integrations/crm-mappings).
* **Run full sync** re-imports the full contact set instead of waiting for the next scheduled sync.
While two-way sync is active, contacts that came from the CRM are locked against deletion, so the CRM stays the source of truth for those records.
## Who can use it
Contacts needs CRM view permission to open, and CRM edit permission for anything that changes data: adding contacts, editing fields, running a backfill, or triggering a full sync. Without edit permission the controls are visible but disabled. See [Access Control](/accounts/access-control).
Contacts are managed in the dashboard. There's no public API for creating or listing them at the moment.
## FAQ
No. Contacts come from CRM sync, from adding them in the dashboard, or automatically after a conversation. If your contacts live in Salesforce or HubSpot, [connect the CRM](/integrations/crm-overview) and let inbound sync bring them in.
Ending a phone call or SMS chat with a number that has no contact creates one. That's what links a conversation to a person and lets the next call reuse what the last one learned.
No. The number is the identifier, and creating a duplicate is rejected.
Conversations attach by phone number, so check that the number on the call matches the contact exactly. Web calls and web chats carry no phone number and never attach to a contact.
The dashboard doesn't offer contact deletion today. You can clear a contact's field values by editing it, and you can delete custom contact fields from the contact fields page. Contacts synced from a CRM are locked against deletion while two-way sync is active.
The contacts stay. They keep their fields and their conversation history, and the External ID showing where they came from. Syncing stops, so later changes on either side no longer cross over.
