> ## 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. # HubSpot contact sync > Sync HubSpot contacts with Retell AI: field mappings, post-call analysis write-back, and call and chat logging on the contact activity timeline. Contact sync imports the connected portal's contacts into Retell, writes [post-call analysis](/features/post-call-analysis-overview) 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](/integrations/crm-overview) explains the four data flows all CRM providers share. Contact sync requires a [connected HubSpot portal](/integrations/hubspot). Integration tools work without it — see [HubSpot agent functions](/integrations/hubspot-functions). ## Required scopes Contact sync uses three of the private app's scopes, granted in [Step 2 of connecting](/integrations/hubspot#step-2-grant-scopes): | Scope | Used for | | ---------------------------- | --------------------------------------------------------- | | `crm.objects.contacts.read` | Importing contacts | | `crm.schemas.contacts.read` | Reading property definitions for field mapping | | `crm.objects.contacts.write` | Outbound sync and logging calls and chats to the timeline | 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](/integrations/crm-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](/integrations/hubspot-functions), but that's an explicit tool call, not sync. Yes. Map any HubSpot contact property, including custom ones, to a Retell [custom field](/integrations/crm-mappings#custom-fields). 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 Map HubSpot properties to Retell contacts, choose update modes, and control what syncs back. Accumulate what your agents learn across conversations into the contact record. Reference synced contact fields from your agent's prompt. Look up callers, read their deals and companies, and create tasks and notes mid-conversation.