> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect HubSpot

> Connect HubSpot to Brilo with a Service Key so your agent can find callers by phone, keep contacts up to date and log every call on the contact.

Connect HubSpot to Brilo in about five minutes with a Service Key from your HubSpot account. Your
agent can then look callers up by phone during the call, create and update contacts, and log each
call and a note on the contact's timeline. Writing to HubSpot runs after the call ends, so the
caller never waits for it.

## Before you start

* A HubSpot user with Super Admin or Developer Tools access, which creating a Service Key needs.
* A Brilo plan that includes the app store. Logging every call automatically also needs
  automations after a call. See [Plans and what they include](/supported/plans).
* An agent to give the HubSpot actions to, even an unfinished one.
* In Brilo, this happens in the dashboard under **App Store**.

## Steps

<Steps>
  <Step title="Create a Service Key in HubSpot">
    In HubSpot, go to **Settings**, then **Integrations**, then **Service Keys**, and create a
    key. Some accounts show the same page under **Development**, then **Keys**, then **Service
    Keys**. Name the key after Brilo so your team knows what uses it.
  </Step>

  <Step title="Give the key two scopes">
    Add `crm.objects.contacts.read` and `crm.objects.contacts.write`. These two cover contacts,
    calls and notes. A key can only get scopes that the person creating it already has.
  </Step>

  <Step title="Copy the key">
    Create the key, then copy its value. Keep the HubSpot tab open until Brilo has tested it.
  </Step>

  <Step title="Open HubSpot in the Brilo app store">
    In the Brilo dashboard, open **App Store**, choose the HubSpot app marked **Native**, click
    **Connect**, then **Continue**.
  </Step>

  <Step title="Paste the key">
    Paste the key into **Access token**. **Connection name** is optional and helps when you
    connect more than one HubSpot account. Click **Continue**.
  </Step>

  <Step title="Test the connection, then install">
    Click **Test connection**. When the test passes, click **Install App**.
  </Step>
</Steps>

## You will know it worked when

* **Test connection** passes and Brilo says HubSpot is now linked to your workspace.
* HubSpot shows as connected in the app store.
* On a test call as someone who is in HubSpot, your agent uses that contact's first name.
* After a test call with the after-call setup on this page, a call and a note appear on the
  caller's contact in HubSpot.

## What your agent can do in HubSpot

Brilo's HubSpot connection gives your agent seven actions. Add each one from your agent's
**Actions** tab with **Add Actions**, then **HubSpot**. A new HubSpot action runs after the call
by default, which its **Trigger** setting shows as **After the call (post-call)**. See
[What are actions](/actions/what-are-actions) for how actions work in general.

This table lists each HubSpot action, what it does, and the timing it suits best.

| HubSpot action | What it does | Best timing |
| - | - | - |
| Find contact by phone | Finds the contact whose phone or mobile number matches a number | During and after the call |
| Search contacts | Finds contacts by name, email, phone or company | During the call |
| Get contact | Reads one contact's details | During the call |
| Create contact | Adds a new contact | After the call |
| Update contact | Changes a contact's name, email, phone, company or job title | After the call |
| Log call | Adds the call and a summary to a contact's timeline | After the call |
| Create note | Adds a note to a contact's timeline | After the call |

Looking someone up suits the call itself, because your agent can use what it finds straight away.
Writing to HubSpot suits the time after the call, because the caller never waits for it.

## Know the caller during the call

Your agent can look the caller up in HubSpot while the call is happening, so it greets a known
caller by name and skips questions HubSpot already answers. Open **Find contact by phone** in your
agent's **Actions** tab and set its **Trigger** to **During and after the call (post-call)**. That
setting keeps the action available to an after-call workflow as well; choose **During the call**
if you only want the lookup.

Then say when to use it in your agent's **Prompt** tab, for example:

```text theme={null}
At the start of the call, look the caller up in HubSpot with Find contact by phone, using their
phone number. If you find them, greet them by first name and do not ask for details HubSpot
already has.
```

## Log every call in HubSpot automatically

HubSpot gets a record of every call when an automation after the call runs three HubSpot actions
in order: find the caller, log the call, add a note. Add **Find contact by phone**, **Log call**
and **Create note** to your agent first. An after-call workflow only offers actions whose
**Trigger** includes after the call, so leave Log call and Create note on **After the call
(post-call)**, and give Find contact by phone **After the call (post-call)** or **During and
after the call (post-call)**.

Then open your agent's **Post Call Workflows** tab and create a workflow. Tick the three actions
under **Allowed actions**, paste these instructions, turn on **Run on real calls**, and save.

```text theme={null}
- Find the caller in HubSpot with Find contact by phone, using the caller's phone number.
- If no contact is found, stop.
- Log call on the contact found, with a two sentence summary of the call, direction INBOUND and status COMPLETED.
- Create note on the same contact with what the caller wanted and any follow-up they asked for.
```

The call and the note carry the time the workflow ran, a few seconds after the caller hangs up.
See [Automate what happens after a call](/reports/automate-what-happens-after-a-call) for
workflows in general.

## What is not supported

* **Deals, companies, tickets and custom objects.** The HubSpot actions cover contacts, calls
  and notes.
* **Signing in with your HubSpot account.** Brilo connects with a Service Key or a private app
  token, not a HubSpot sign in screen.
* **Sending call recordings to HubSpot.** The call is logged with a summary, without the audio.
* **Choosing a HubSpot owner** for a contact, a call or a note.
* **Reading HubSpot's own call history or reports.**

<Note>
  If you need one of these, or another HubSpot action, email
  [support@brilo.ai](mailto:support@brilo.ai) with what you are trying to do. What customers ask
  for is how the list grows.
</Note>

## What else you can do here

* [Decide what your CRM should hold after a call](/actions/update-your-crm).
* [Put a summary of every call where your team reads it](/reports/personalised-call-summary).
* [Automate other work when a call ends](/reports/automate-what-happens-after-a-call).
* [Reach a system that is not in the app store](/actions/build-a-custom-action).

## If it did not work

**The test says HubSpot did not accept this token.** The key was copied only in part, or it was
rotated or deleted in HubSpot. Copy the whole key again from **Service Keys** and paste it with
no spaces around it.

**The test says the token works, but cannot reach your contacts.** The key is missing a scope.
Add `crm.objects.contacts.read` and `crm.objects.contacts.write` to the key in HubSpot, then test
again.

**Your agent did not find a caller who is in HubSpot.** Find contact by phone matches most
reliably when HubSpot stores the number with its country code. A contact created in the last few
seconds can also be missing from HubSpot's search for a moment.

**Your agent does not use the caller's name during the call.** Check that the **Trigger** on Find
contact by phone includes during the call, and that your **Prompt** tells your agent to look the
caller up at the start.

**Nothing appeared on the contact after a call.** Check that **Run on real calls** is on, then
open the workflow's **Run History**. When no contact matches the caller, the workflow stops
without writing anything.

Anything else: [An action did not run](/actions/an-action-didnt-run).

## FAQ

<AccordionGroup>
  <Accordion title="Does Brilo work with HubSpot?">
    Yes. Connect HubSpot from the app store with a Service Key, and your agent can find callers
    by phone, create and update contacts, and log calls and notes on a contact's timeline.
    HubSpot contacts, calls and notes are covered today. Deals, companies and tickets are not.
  </Accordion>

  <Accordion title="Can Brilo log every call in HubSpot automatically?">
    Yes, with an automation after the call. A workflow that runs Find contact by phone, Log call
    and Create note finds each caller in HubSpot and writes a call and a note to that contact's
    timeline. Automations after a call need a plan that includes them. See
    [Plans and what they include](/supported/plans).
  </Accordion>

  <Accordion title="Can my agent greet HubSpot callers by name?">
    Yes. Set Find contact by phone to run during the call and tell your agent to look the caller
    up at the start. When HubSpot has the number, your agent knows the contact's name, company
    and job title before it asks anything, and greets the caller by first name.
  </Accordion>

  <Accordion title="Why does Brilo say HubSpot is limiting requests?">
    HubSpot caps how often one account can call it, and the Brilo connection test hit that cap.
    Nothing is wrong with the HubSpot key. Wait a minute and click Test connection again. If the
    message keeps coming back, another tool on the same HubSpot account may be using most of the
    allowance.
  </Accordion>

  <Accordion title="Should I use a HubSpot Service Key or a private app token?">
    Use a Service Key. HubSpot is replacing private apps with Service Keys, and new HubSpot
    accounts can no longer create private apps. Brilo accepts either one in the same Access token
    field, so an existing private app token keeps working until you replace it with a Service
    Key.
  </Accordion>

  <Accordion title="Will Brilo create duplicate contacts in HubSpot?">
    Not when your agent looks the caller up first. Find contact by phone checks HubSpot before
    anything is written, and a workflow that stops when nobody matches never adds a contact.
    Create contact always makes a new HubSpot record, so tell your agent to use it only when the
    lookup finds nobody.
  </Accordion>

  <Accordion title="What happens if I rotate or delete my HubSpot Service Key?">
    The HubSpot actions stop working as soon as the old key is rotated or deleted. Create a new
    Service Key with the same two scopes. Then, on the HubSpot page in the Brilo app store, click
    Connected, confirm Remove Connection with Yes, and connect again with the new key.
  </Accordion>

  <Accordion title="Do I need a developer to connect HubSpot to Brilo?">
    No. Creating a Service Key is a settings page in HubSpot, and connecting it is a paste in the
    Brilo app store. The person creating the key needs Super Admin or Developer Tools access in
    HubSpot, because a key can only get scopes its creator already has.
  </Accordion>

  <Accordion title="Why are there two HubSpot apps in the app store?">
    Brilo builds one HubSpot app, marked Native, and the other comes from a connector library
    Brilo also offers. Use the HubSpot app marked Native: it connects with a Service Key, finds
    callers by phone and logs calls. Your agent needs only one HubSpot connection.
  </Accordion>
</AccordionGroup>

## Related

* [Update your CRM](/actions/update-your-crm) for what is worth writing after a call
* [What are actions](/actions/what-are-actions) for how a connected app gets used on a call
* [Automate what happens after a call](/reports/automate-what-happens-after-a-call) for
  after-call workflows
* [Supported integrations](/supported/integrations) for everything else Brilo connects to
* [An action did not run](/actions/an-action-didnt-run) when nothing reaches HubSpot


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.