Skip to main content
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 on the next phone call or SMS chat. Contact memory adds a running brief of previous conversations. Open it from the Contacts tab under Data in the dashboard.
Contacts page in the Retell dashboard showing a table of contacts with columns for phone number, first name, last name, related conversations, latest conversation, do not call, external ID, and a custom email field. Custom field columns continue off to the right.

The Contacts page, showing each contact's conversation count and last conversation.

​
When to use it

  • Your CRM is the source of truth. Sync contacts in from your CRM 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 Extraction. 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 through these flows, all matched by 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, or through Actions → Upload CSV.
  • From your CRM, if you’ve connected a CRM integration 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

1

Open the form

Select Actions → Add contact.
Add Contact dialog with a required phone number field showing the placeholder +14155552671, first name, last name, a Do not call dropdown set to False, and a Custom fields section listing the workspace's own fields: Company, Email, Preferred language, an Account tier selector, and a Renewal date picker.

The Add Contact form, with the workspace's custom fields below the built-in ones.

2

Enter the phone number

Required, and it has to be a valid number. Use E.164 format, for example +14155552671. This is the key everything else matches on.
3

Fill in the rest

First name, last name, Do not call, and tags 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.
4

Create

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: 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, tags, 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.
Contact detail panel for Ada Lovelace showing Contact information with first and last name, related conversations, latest conversation, do not call, external ID, contact ID, and custom fields such as Company, Account tier, Renewal date, and Situation summary, beside a Conversations panel with total time, average call length, an inbound and outbound split bar, and a list of call summaries tagged successful or unsuccessful with sentiment and disconnection reason.

A contact's fields on the left, every call and chat with that number on the right.

​
View and edit conversation memory

The Conversation Memory field in Contact information holds the contact’s running brief. Select View all to expand a long memory and View less to collapse it. If the contact has no saved memory, the field shows “No memory yet. Conversation memory can be enabled in agent settings.” This message appears regardless of the agents’ settings. To check whether an agent saves memory, open Post call memory settings on that agent and check Save conversation to memory.
Ada Lovelace's contact detail panel with Conversation Memory highlighted in blue. The empty field reads: No memory yet. Conversation memory can be enabled in agent settings.

An empty memory shows the same message regardless of whether an agent has saving enabled.

The editor appears once a contact has nonempty memory. For an empty contact, generate memory from an eligible conversation or use backfill first. To update existing memory:
1

Edit Contact information

Open the contact and select Edit in Contact information. Update Conversation Memory inline, or use its expand control for a larger editor.
2

Apply the draft

In the expanded editor, select Save to place your draft back into the contact form. This does not save the contact yet. Cancel discards edits made inside that dialog.
3

Save the contact

Select Save in Contact information to persist the memory and any other field edits. Memory accepts up to 2,000 characters (as of September 2026); over-limit text blocks saving. If saving fails, keep the form open and retry after resolving the error.
Conversation Memory dialog over the contact detail panel, with an editable memory brief and a character counter out of 2000. The description says to save Contact information after editing this memory. Cancel and Save are at the bottom.

The expanded memory editor stages changes; save Contact information afterward to apply them.

To clear memory, delete its text and save Contact information. Clearing it doesn’t disable future updates. Later conversations can write new memory if Save conversation to memory remains enabled on their agents. See agent memory settings for saving, reading, and the workspace prompt.

​
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 Extraction field that writes to it, and when it last changed.
Contact Fields page listing the built-in Phone Number, First Name, Last Name, and Do Not Call fields above custom fields such as Company, Email, Account tier, and Renewal date. Each row shows the HubSpot field it syncs with, the Post Call Extraction field that writes to it, an update mode badge reading Overwrite, Fill only if empty, or Accumulate and summarize, and when it last changed.

Contact fields, with CRM sync and post-call mappings shown per field.

1

Add the field

Select Add Contact Field, then pick a type: Text, Number, Boolean, Selector, Date, or Datetime. Type is fixed after creation, so choose deliberately.
Add contact field dialog with a Type dropdown set to Text, a Field name input with the placeholder 'e.g. Customer need', a note that the field type can't be changed once created, a Description box reading 'What this field captures', and a Map with Post-Call Data toggle.

Adding a contact field. The type can't be changed once the field exists.

2

Name it

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

Describe what it holds

The description tells you what the field captures. It does more than document: for fields filled by Post Call Extraction with Accumulate & summarize, the description is the instruction the model follows when combining an old value with a new one.
4

Map it to post-call data (optional)

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 for mapping details. Built-in contact memory saves a separate conversation brief without these mappings.
Built-in fields behave differently from custom ones. First name, last name, do-not-call, and tags can be edited and mapped, but not deleted. Phone number is fixed. Custom fields can be edited or deleted.

​
Import from CSV

Use Actions → Upload CSV to import a contact list, such as leads from an event. Include a header row and a phone number column. CSV files can be up to 50 MB. Contacts are matched by phone number. If a number already exists, the import overwrites its mapped fields and leaves unmapped fields unchanged. New numbers create new contacts. Imported tags are added to existing tags without duplicates.
1

Upload and preview

Select your CSV file, review the preview, then select Continue.
Preview CSV uploading dialog showing computer-science-contacts.csv with 12 contacts, phone_number, first_name, and last_name columns, and sample rows starting with Ada Lovelace, Alan Turing, and Grace Hopper. The upload is completed and Continue is available.

Preview a CSV with 12 sample contacts, starting with Ada Lovelace.

2

Map the columns

Select the columns to import and map each to a contact field. Map exactly one column to Phone Number; each contact field can receive only one CSV column. You can select an existing field or create a custom field from the mapping selector.Choose the default country for phone numbers that don’t include a country code, then select Confirm mapping.
3

Add tags and confirm

Optionally select existing tags or type to create new ones, for example event_lead. These tags apply to every contact in the import. Leaving this step empty keeps existing contacts’ tags unchanged.Select Confirm to submit the import.

​
Use contact data in a conversation

When a phone call or SMS chat 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, contact_memory when stored, and one per custom field, each named after the field. Reference them in the prompt the same way as any other dynamic variable, for example {{first_name}}. This applies to inbound calls, outbound calls, batch calls, and SMS chats. If no contact matches the number, the variables are absent, so write prompts that read naturally without them. Enable Use contact memory to include stored memory in the agent’s context automatically, without adding a variable to its prompt.

​
Read contacts from the API

The Contact API returns the same records the dashboard shows, so your own systems can check who you’ve already spoken to before placing a call. Every contact carries: Use these endpoints to read them:
  • Get contact by phone looks up one number. Send it in E.164 format.
  • List contacts filters the whole set by last_conversation_timestamp, do_not_call, external_id, tags, and custom fields, up to 1,000 per page.
  • List contact conversations returns every call and chat with the number, newest first, with each one’s start time, duration, direction, disconnection reason, summary, sentiment, and success flag.
The counts update when a phone call or SMS chat ends, after post-call analysis runs, so expect a short delay after hang-up. Every outbound phone call counts as a conversation, including ones that reach voicemail or go unanswered, so a cooldown based on last_conversation_timestamp also covers dial attempts. Web calls and web chats never count.

​
Limit how often you call a number

Retell doesn’t cap how often your agent calls a number. Create Phone Call checks do_not_call only when you pass honor_internal_dnc: true (see do-not-call requests), and batch calls don’t check it. To avoid calling someone too often, check the contact before you dial. A debt collection team, for example, calls each customer at most once every 48 hours. Before each call, their dialer looks up the number and skips it if the last conversation was too recent:
Skip the call if do_not_call is true or last_conversation_timestamp is less than 48 hours ago. A 404 means you’ve never spoken to that number, so it’s safe to call. To build a whole call list at once, ask List contacts for everyone last spoken to before your cutoff who isn’t marked do-not-call:
For a rule like “no more than three calls a week”, list the contact’s conversations and count the calls whose start_timestamp falls inside the window.

​
Backfill fields from past conversations

Enabling memory saving or adding an extraction mapping only affects future conversations. To populate contacts from past phone calls and SMS chats, open Actions → Backfill. The dialog is titled Backfill from past conversations.
1

Choose the fields

Select Memory, mapped contact fields, or both. Memory is always a built-in target and needs no Post Call Extraction mapping. Other fields appear only when they have an analysis mapping.
2

Filter the conversations

Choose an Agent filter, optionally with versions, or a Conversation time filter. At least one agent or time bound is required. Review the selected range before running the job.
3

Start and monitor the backfill

Select Backfill. The Contacts header shows backfill activity, and a notification tracks the job and reports completion or errors. If starting the job fails, the dialog stays open with your selection and an error.
Backfill from past conversations dialog with Memory selected at $0.005 per conversation, the mapped contact fields unchecked, and a Conversation time filter. The Backfill button starts the job; Cancel closes the dialog.

Select Memory to summarize historical conversations independently of mapped fields.

For memory backfill:
  • The agent’s latest configuration must have Save conversation to memory enabled. This lets you process earlier conversations even if saving wasn’t enabled when they happened.
  • Only ended phone calls and SMS chats with retained transcripts are eligible. Conversations stored with Basic Attributes Only, missing or unreadable transcripts, and transcripts with failed PII redaction are skipped. A conversation also needs a usable user message to generate memory.
  • Retell starts with the contact’s current memory and processes selected conversations oldest first, using the current workspace memory prompt. A failed or empty rewrite keeps the previous brief.
  • The price is $0.005 per conversation processed as of September 2026, not per contact. Repeating a backfill can process and charge for the same conversations again.
Mapped fields use existing Post Call Extraction results and their configured update modes. To regenerate those extraction results, rerun analysis first. Only one contact backfill can run at a time per workspace. If one is already running, wait for it to finish before starting another. After completion, open a contact to check the result. If memory is still empty, check agent eligibility, the selected time range, and transcript availability before retrying.

​
Keep contacts in sync with your CRM

With a CRM connected, 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.
  • 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 or memory, running a backfill, or triggering a full sync. Without edit permission the controls are visible but disabled. See Access Control.

​
FAQ

Yes. Import from CSV to map your columns to contact fields and optionally tag the imported contacts. If your contacts live in a CRM, connect the CRM and let inbound sync bring them in instead.
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.
Use Delete 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.