CRM data mappings

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:

​

How data flows

​

1. Inbound sync: CRM to Retell

Inbound sync imports contacts from your CRM into Retell. It runs every 5 minutes and picks up only records modified since the last run. A manual sync re-scans everything. 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. Records Retell skips: a CRM contact with no value in the mapped phone field, or with a phone number that can’t be parsed into a valid E.164 number. Skipped records don’t stop the sync. Inbound sync mappings control which CRM fields are imported:

​

2. Analysis data mapping: analysis to contact

After each call or chat, post-call analysis 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:

​

Update modes

Each analysis data mapping has an update mode that controls how the new value interacts with the existing value. The names in parentheses are the labels shown on the contact fields page in the dashboard.

​

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: Limits worth knowing. Merge only applies to string fields; on any other type the mapping is skipped. The merged result is capped at roughly 512 tokens, so a field set up as an ever-growing log eventually starts losing the oldest detail rather than expanding forever. Write the description to prioritize what matters most. If the merge call fails or comes back empty, Retell falls back to keeping both values, appending the new one below the existing one separated by a blank line. You never lose data to a failed merge, but the field won’t be as tidy as a successful one.

​

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 all of these hold:

• The contact was imported from your CRM and still carries its CRM record ID.
• The contact was imported by the connection that’s currently active. If you delete a connection and set up a new one, contacts imported by the old one stop syncing outbound until they’re re-imported.
• At least one outbound sync mapping is configured.
• The conversation actually changed a mapped field. An analysis result identical to the stored value writes nothing.

Outbound sync updates existing CRM records only. It never creates or deletes contacts in your CRM. It also never writes back the phone number, which stays reserved as the matching key. Outbound sync mappings control which Retell fields are pushed:

​

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
• The Retell conversation ID, and the from and to phone numbers

Retell picks the number to match on from the call’s direction: the caller’s number on an inbound call, the dialed number on an outbound one.

​

End-to-end data flow example

Here’s how a typical interaction flows through the system:

​

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:

​

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