Skip to main content
Contact sync imports the connected portal’s contacts into Retell, writes post-call analysis results back to their properties, and logs every call and chat on the contact’s activity timeline. This page covers the HubSpot-specific behavior; CRM integrations explains the four data flows all CRM providers share. Contact sync requires a connected HubSpot portal. Integration tools work without it — see HubSpot agent functions.

​
Required scopes

Contact sync uses three of the private app’s scopes, granted in Step 2 of connecting: A missing scope doesn’t flag the connection; the affected part of sync silently stops working.

​
Set up contact sync

After the connection test passes, click Set up contact sync to open the field mapping dialog, then map the HubSpot properties you want to import and the Retell fields you want to write back. For a connection made earlier, the same dialog opens from the Connected tab: open the connection’s settings and click Set up contact sync. Retell pre-fills one mapping in each direction: HubSpot phone to Retell phone_number. Phone number is how contacts are matched between the two systems, so it stays mapped and can’t be removed. See CRM data mappings for how to map the rest, create custom fields, and choose update modes. To log conversations to HubSpot, turn on Log activities automatically on the Sync to HubSpot tab.

​
Verify it worked

  • Open Contacts. After the first sync, HubSpot contacts appear with correctly formatted phone numbers and your mapped fields populated.
  • The first sync is a full scan of every contact that has the mapped phone property, so a large portal takes a while. After that, Retell polls every 5 minutes (as of August 2026) and imports only contacts modified since the last run.
Contacts with no value in the mapped phone property are excluded from the sync entirely, as are contacts whose phone number can’t be parsed into a valid E.164 number. Fix or remove malformed numbers in HubSpot before relying on two-way sync.

​
How are conversations logged in HubSpot?

A call becomes a Call engagement associated with the matched contact, with its status set to COMPLETED, plus the duration and direction. A chat becomes a Communication object on the SMS channel, since HubSpot has no chat engagement type. Both carry a body with the conversation ID, the from and to numbers, the disconnection reason for calls, and the summary.

​
Troubleshooting

A scope or permission error on a single property doesn’t fail the sync or flag the connection, because Retell only treats credential rejections as connection errors. Check that the property is mapped on the right tab of the sync settings, and that the app has the write scope if you expect Retell to update it.
Activity logging needs three things: Log activities automatically enabled on the Sync to HubSpot tab of the sync settings, a Retell contact that was imported from this HubSpot connection, and the crm.objects.contacts.write scope on your private app. Retell attaches the activity to the contact it matched by phone number, so a call from a number that isn’t a synced HubSpot contact is never logged.
Retell only imports contacts that have a value in the mapped phone property, and skips any whose number can’t be parsed into E.164. A contact with a phone number stored in a different property than the one you mapped won’t sync. Check which HubSpot property you mapped to phone_number in the sync settings.

​
FAQ

Only if you opt in. By default, outbound sync updates contacts that already exist in HubSpot and never creates or deletes them. Turn on Create new contacts in CRM on the Sync to HubSpot tab to have Retell create a HubSpot contact after a conversation when the matched contact isn’t linked to one yet. With the toggle off, contacts Retell creates on its own, for example from an inbound call from an unknown number, stay in Retell and aren’t pushed to HubSpot. Your agent can also create a contact through the Create Contact tool, but that’s an explicit tool call, not sync.
Yes. Map any HubSpot contact property, including custom ones, to a Retell custom field. Objects other than contacts, such as deals and companies, are not part of contact sync.
They stay. Turning contact sync off stops future syncs, and deleting the connection removes the stored credentials. Contacts already imported remain in Retell either way.

​
Next steps

CRM data mappings

Map HubSpot properties to Retell contacts, choose update modes, and control what syncs back.

Build contact memory

Accumulate what your agents learn across conversations into the contact record.

Dynamic variables

Reference synced contact fields from your agent’s prompt.

HubSpot agent functions

Look up callers, read their deals and companies, and create tasks and notes mid-conversation.