> ## 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.
# Connect HubSpot
> Connect HubSpot to Retell with a private app access token to sync contacts both ways, map post-call analysis to properties, and log calls to timelines.
Connecting HubSpot lets Retell import your contacts, enrich them with [post-call analysis](/features/post-call-analysis-overview) results, push property updates back, and log every call and chat on the contact's activity timeline. This page covers the HubSpot-side setup and the token Retell needs.
This is the setup guide for using HubSpot as a **CRM data source**. If you want to trigger outbound calls *from* HubSpot workflows instead, see the [HubSpot Marketplace app](/integrations/hubspot-marketplace). The two are independent and can be used together.
## When to use it
Connect HubSpot when it's your system of record and you want your agents working from it without anyone copying data between tools. It's the right choice when you want to:
* **Call or text people who already exist in HubSpot.** Contacts sync into Retell automatically, so your agent greets callers by name and knows their deal stage or lifecycle stage instead of asking.
* **Keep HubSpot current without manual data entry.** Analysis results from each conversation write back to contact properties.
* **Give your team call history where they already work.** Each call and chat appears on the contact's activity timeline with its summary and duration.
## Prerequisites
* A HubSpot account with **Super Admin** permissions. Only a super admin can create a private app and grant it scopes.
## Step 1: Create a private app
In HubSpot, click **Development** at the bottom of the left sidebar, then select **Legacy Apps**. Click **Create legacy app** in the top-right corner, then choose **Private** in the dialog.
HubSpot renamed the private apps section to **Legacy Apps** and is steering new development toward its projects platform. Private apps still work and remain the supported way to connect HubSpot to Retell. Depending on your account you may reach the same screen through **Settings > Integrations > Legacy apps**, or see **Private Apps** as its own sidebar item.
On the **Basic Info** tab, enter:
* **Name** — a descriptive name, for example `Retell AI Integration`.
* **Description** — optional, for example "Syncs contacts and logs call activity for Retell AI".
## Step 2: Grant scopes
On the **Scopes** tab, click **Add new scope**, search for each scope below in **Find a scope**, check it, then click **Update**.
Retell needs three scopes:
| Scope | Required for |
| ---------------------------- | ------------------------------------------------------------------------ |
| `crm.objects.contacts.read` | Importing contacts, and the connection test Retell runs when you connect |
| `crm.schemas.contacts.read` | Reading contact property definitions so you can map fields |
| `crm.objects.contacts.write` | Outbound sync, and logging calls and chats to the timeline |
A missing scope doesn't fail the connection test or flag the connection as broken, because Retell only treats rejected credentials as a connection error. The affected feature just silently stops working, so grant the correct scope up front.
## Step 3: Generate the access token
Click **Create app** in the top-right corner. Review the scopes in the confirmation dialog and click **Continue creating**.
Click **Show token**, then copy it.
This is the only time HubSpot displays the full token. Store it somewhere safe. You can rotate it later, but rotating invalidates the old token immediately.
## Step 4: Connect HubSpot in Retell
In the Retell Dashboard, open **Integrations**, select the **Available** tab, find **HubSpot**, and click **+ Add Account**.
Fill in the fields:
| Field | Value |
| ------------------- | ----------------------------------------- |
| **Connection name** | Alias for this connection. |
| **Access Token** | The private app access token from Step 3. |
Click **Connect**. Retell creates the connection and immediately tests it by reading a page of contacts from HubSpot.
On success the dialog reports the connection as verified and offers **Set up contact sync**. On failure it shows HubSpot's own error and re-enables the field so you can paste a corrected token.
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.
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
* On the **Connected** tab, the HubSpot connection shows as connected.
* 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 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.
## Manage the private app
### Rotate the access token
Go to **Development > Legacy Apps** and click your Retell app's name. Next to the access token, click **Rotate**, then choose how the old token expires:
* **Rotate and expire later** keeps the old token valid for 7 days. Pick this one. Retell keeps working while you swap the credential over.
* **Rotate and expire now** kills the old token immediately, so contact sync and activity logging fail until Retell has the new one.
The connection settings dialog shows a saved token masked and read-only, so there's no field to paste a new one into. Delete the connection and create it again with the new token.
Your Retell contacts survive the delete. Only the stored connection goes away, so you'll need to set up field mappings again.
### Change scopes
Go to **Development > Legacy Apps**, click your Retell app's name, then click **Edit app** in the top-right corner to change its scopes. Adding a scope takes effect without a new token. Removing one stops the corresponding Retell feature working, without flagging the connection as broken.
## Troubleshooting
Confirm you pasted the private app **access token** and not a HubSpot API key or an OAuth client secret. Check that the app has `crm.objects.contacts.read`, which the connection test needs, and that the token hasn't been rotated since you copied it.
Retell flags a connection as errored when HubSpot rejects the credentials with an HTTP 401. The usual cause is a rotated or deleted token. Delete the connection and reconnect with a current token.
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
No. Contact sync only updates contacts that already exist in HubSpot, and never deletes them. Contacts that Retell creates on its own, for example from an inbound call from an unknown number, stay in Retell and are not pushed to HubSpot.
You can add multiple connections, but only one of them can drive contact sync for your organization at a time. When contact sync is already set up on another connection, **Set up contact sync** is disabled on the new one.
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.
No, they do different jobs. This integration syncs contacts and logs activity. The [Marketplace app](/integrations/hubspot-marketplace) adds a **Make a Phone Call** action to HubSpot workflows so HubSpot can trigger outbound calls. You can run both.
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.
Use the Marketplace app to start outbound calls from a HubSpot workflow.
Reference synced contact fields from your agent's prompt.