> ## 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.
# Map CRM fields to Retell contacts and call data
> Understand how data flows between your CRM, Retell contacts, and post-call analysis — including field mappings, sync direction, and update modes.
This page explains the data relationships between your external CRM, Retell contacts, and post-call analysis data, and how to configure the mappings that control data flow.
## Data Model Overview
The CRM integration involves three main entities and four data flows between them:
Your Salesforce or HubSpot contact records with their native fields.
A unified contact record in Retell with default fields and custom fields.
Structured data extracted from each call/chat by your [post-call analysis](/features/post-call-analysis-overview) configuration.
| Data Flow | Direction | Description |
| -------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| **Inbound Sync** | External CRM → Retell Contact | Import and update contacts from your CRM on a recurring schedule |
| **Analysis Mapping** | Post-Call Analysis → Retell Contact | Map extracted conversation data to contact fields after each call/chat |
| **Outbound Sync** | Retell Contact → External CRM | Push updated contact fields back to your CRM |
| **Activity Logging** | Retell Contact → External CRM | Log call and chat records as activities on the CRM contact |
## How Data Flows
### 1. Inbound Sync: CRM to Retell
Inbound sync imports contacts from your CRM into Retell.
**Matching logic:** Contacts are matched between systems using **phone number** as the primary key. When Retell finds a CRM contact with a phone number that matches an existing Retell contact, it updates the existing record. Otherwise, it creates a new contact.
**Inbound sync mappings** control which CRM fields are imported:
| CRM Field (Example) | Direction | Retell Field |
| ---------------------------------------- | ------------- | ------------------------- |
| `Phone` (Salesforce) / `phone` (HubSpot) | CRM -> Retell | `phone_number` (required) |
| `FirstName` / `firstname` | CRM -> Retell | `first_name` |
| `LastName` / `lastname` | CRM -> Retell | `last_name` |
| `Default Field` / `hs_field` | CRM -> Retell | Your custom field name |
| `Custom_Field__c` / `custom_property` | CRM -> Retell | Your custom field name |
The `phone_number` mapping is required and hardcoded for inbound sync. Without it, Retell has no way to match CRM records to Retell conversations.
### 2. Analysis Data Mapping: Analysis to Contact
After each call or chat, [post-call analysis](/features/post-call-analysis-overview) extracts structured data from the conversation. You can map these analysis results to contact fields, building a richer contact profile over time.
For example, if your post-call analysis extracts a `lead_qualification_status` field, you can map it to a custom contact field so each contact's qualification status is automatically updated after every conversation.
**Example mappings:**
| Analysis Data Field | Direction | Contact Field | Update Mode |
| ------------------- | ------------------- | ---------------------- | ------------- |
| `lead_status` | Analysis -> Contact | `qualification_status` | Overwrite |
| `email_address` | Analysis -> Contact | `email` | Fill if empty |
| `customer_notes` | Analysis -> Contact | `interaction_summary` | Merge |
#### Update Modes
Each analysis data mapping has an **update mode** that controls how the new value interacts with the existing value:
Always replace the existing value with the new analysis result. Use this for fields where the latest value is always the most relevant (e.g., sentiment, status).
Only write the new value if the field is currently empty. Use this for fields you want to capture once and preserve (e.g., email address, company name).
Intelligently combine the existing and new values using LLM. Only available for string fields. Use this for cumulative fields where you want to preserve context from previous conversations (e.g., interaction notes, preferences).
#### How Merge Works
The **Merge** update mode uses an LLM to intelligently combine the existing contact field value with the new analysis result from the latest conversation. Instead of simply appending or replacing text, the LLM reads both values and produces a single, coherent merged result.
The **field description** you set when creating or editing the custom field plays a critical role in this process. The LLM uses the field description as its primary instruction for how to perform the merge — it tells the model what kind of data the field holds, what information to prioritize, and how the merged output should be structured.
**Example field descriptions for merge:**
| Field Name | Good Description | Why It Works |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `interaction_notes` | `A running summary of all conversations with this contact. Include key topics discussed, action items, and any commitments made. Keep the most recent interaction details prominent while preserving important context from earlier conversations.` | Tells the LLM to maintain a chronological summary and what details matter. |
| `customer_preferences` | `The contact's stated preferences and requirements. Consolidate preferences across conversations — update changed preferences and keep unchanged ones. Format as a bullet list.` | Guides the LLM to reconcile conflicting information and specifies an output format. |
| `objections_raised` | `A deduplicated list of objections or concerns the contact has raised across all conversations. Merge new objections into the existing list without repeating ones already captured.` | Instructs the LLM to deduplicate rather than blindly concatenate. |
Think of the field description as a prompt to the LLM. The more specific you are about what to keep, what to discard, and how to structure the output, the better the merge results will be.
### 3. Outbound Sync: Retell to CRM
When a contact's fields are updated in Retell — either manually or via analysis data mapping — the changed fields can be pushed back to your CRM through **outbound sync mappings**.
Outbound sync only triggers when:
* The contact has an `externalId` (i.e., was originally imported from the CRM)
* There is an active connected CRM app
**Outbound sync mappings** control which Retell fields are pushed:
| Retell Field | Direction | CRM Field (Example) |
| ---------------------- | ------------- | -------------------------------- |
| `qualification_status` | Retell -> CRM | `Lead_Status__c` / `lead_status` |
| `interaction_summary` | Retell -> CRM | `Notes__c` / `notes` |
### 4. Conversation Activity Logging
When enabled, Retell logs each call and chat as an activity record in your CRM, associated with the matched contact. This gives your sales team a complete conversation history directly in the CRM.
Activity records include:
* Call/chat direction (inbound or outbound)
* Duration (for calls)
* Summary
* Timestamp
## End-to-End Data Flow Example
Here's how a typical interaction flows through the system:
An inbound sync imports a contact from Salesforce with fields: `Phone: +1234567890`, `FirstName: Alice`, `LastName: Smith`, `Lead_Status__c: New`.
A Retell contact is created with: `phone_number: +1234567890`, `first_name: Alice`, `last_name: Smith`, `lead_status: New`.
Your voice agent calls Alice. During the call, contact fields are injected as dynamic variables, so the agent knows Alice's name and lead status.
After the call, post-call analysis extracts:
* `lead_qualification_status: Qualified`
* `customer_notes: Interested in enterprise plan, wants demo next week`
* `email: alice@example.com`
The analysis results are applied to Alice's contact based on your mappings:
* `lead_status` is **overwritten** with `Qualified`
* `interaction_summary` is **merged** with the new notes, preserving previous conversation context
* `email` is **filled** (was previously empty)
Updated fields are synced back to Salesforce:
* `Lead_Status__c` updated to `Qualified`
* `Notes__c` updated with the merged interaction summary
A Task record is created in Salesforce with the call summary, duration, and direction, associated with Alice's contact record.
## Configuring Field Mappings
### Custom Fields
Before you can map CRM fields to non-default Retell fields, you need to create **custom fields** on your Retell contacts.
Custom fields support the following types:
| Type | Example Values |
| ---------- | ---------------------------------- |
| `string` | `"Interested in enterprise plan"` |
| `number` | `42`, `99.5` |
| `boolean` | `true`, `false` |
| `date` | `2025-03-15` |
| `datetime` | `2025-03-15T10:30:00Z` |
| `enum` | One of a predefined set of options |
Custom field names must be in `snake_case` and cannot conflict with the built-in field names (`phone_number`, `first_name`, `last_name`, `do_not_call`).
### Field Type Compatibility
When configuring sync mappings, the CRM field type must be compatible with the Retell field type. Retell handles type coercion automatically:
* CRM date strings are parsed into Retell `date`/`datetime` fields
* CRM picklist values map to Retell `enum` fields
* CRM numeric strings are converted to Retell `number` fields
* CRM boolean-like values (`"true"`, `"false"`) are converted to Retell `boolean` fields
## Best Practices
* **Start with essential mappings.** Map `phone_number`, `first_name`, and `last_name` for inbound sync first. Add custom fields incrementally as you identify what data is valuable.
* **Use "Fill if empty" for stable data.** Fields like email address or company name rarely change — use "Fill if empty" to capture them on first mention without overwriting later.
* **Use "Merge" sparingly.** The merge update mode uses AI to combine values, which works well for free-text notes but adds latency and cost. Use "Overwrite" or "Fill if empty" when possible.
* **Write descriptive field descriptions for merge fields.** The field description acts as the LLM's instruction for how to merge values. A specific, well-written description (e.g., "A running summary of interactions — keep recent details prominent, deduplicate action items") produces much better results than a vague one. See [How Merge Works](#how-merge-works) for examples.
* **Use "Overwrite" for status fields.** Fields like lead status or sentiment should always reflect the most recent conversation.
* **Enable activity logging for sales visibility.** Your sales team can see the full conversation history in the CRM without switching to the Retell dashboard.
* **Use a dedicated CRM integration user.** For Salesforce, use a dedicated service account as the Run-As user to avoid permission issues when team members change roles.