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

# HubSpot

> Recognize returning callers, look up contacts, deals and tickets, and log every call to HubSpot.

Connect your HubSpot CRM once, then your agent works against it live. It recognizes a returning
caller by the number they're calling from and greets them by name, looks up **contacts**,
**companies**, **tickets**, and **deals** mid-conversation, and opens new work — creating a
contact, a support ticket, or a deal. Creates confirm with the caller first; edits to an existing
record additionally require a [verified caller identity](/guides/caller-verification).

## Connect

HubSpot uses OAuth. Start the connect, finish consent in a browser, and the [Connector
Pack](#what-installs-the-connector-pack) skills install automatically.

<Steps>
  <Step title="Begin the connection">
    `POST /integrations/hubspot/connect` returns an `oauthUrl`.
  </Step>

  <Step title="Grant access in a browser">
    Open the `oauthUrl` while signed in to your dashboard and approve the HubSpot consent screen.
    The browser-only callback finishes the connection — it cannot be completed with an API key.
  </Step>

  <Step title="Confirm">
    `GET /integrations` now lists `hubspot` with `status: connected` and an `accountLabel`. The
    Connector Pack skills are compiled per-account against your connection at install.
  </Step>
</Steps>

```bash theme={null}
curl -X POST https://builder.flowyte.com/api/v1/integrations/hubspot/connect \
  -H "Authorization: Bearer flowyte_sk_…"
# → { "data": { "oauthUrl": "https://…" } }   # open this in a browser
```

## What installs: the Connector Pack

Connecting installs HubSpot's **Connector Pack** — a curated set of skills, each compiled per
account against your connection at install time. Re-installing is idempotent: a skill that already
exists is skipped and returned with `created: false`.

| Skill            | What it does                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `find_contact`   | Recognize a caller by phone (find-or-nothing lookup) so the agent can greet them by name.           |
| `find_company`   | Look up a company by name or website domain.                                                        |
| `find_ticket`    | Find a support ticket by subject or a keyword.                                                      |
| `create_contact` | Capture a caller — **find-or-create, deduped by phone**, so a returning caller is never duplicated. |
| `update_contact` | Edit a known contact by id (from a prior `find_contact`).                                           |
| `create_ticket`  | Open a support request.                                                                             |
| `create_deal`    | Open a sales opportunity.                                                                           |

<Note>
  Write skills (`create_*` / `update_*`) land **gated** — they confirm with the caller and never run
  in parallel. Updating an existing record additionally requires a
  [verified caller identity](/guides/caller-verification).
</Note>

## Interaction logging

Turn on **interaction logging** to write a record of every finished conversation back to the
matched HubSpot contact's timeline — a per-connection setting that is **off by default** and
**included free**. A voice call becomes a **Call** engagement; a chat becomes a **Note**. Each
carries an AI summary and, optionally, the full transcript — scrubbed of card and ID numbers
before export. Nothing is exported until you enable it, and past conversations are never
back-filled.

When a conversation has no CRM match, the `on_no_match` policy decides what happens:

* `skip` — the interaction is skipped and counted (the default).
* `create` — a contact is auto-created, then the interaction is logged to it.

<CodeGroup>
  ```bash curl theme={null}
  # Read the current config + delivery counters
  curl https://builder.flowyte.com/api/v1/integrations/hubspot/writeback \
    -H "Authorization: Bearer flowyte_sk_…"

  # Log a summary + transcript, auto-creating a contact on no match
  curl -X PATCH https://builder.flowyte.com/api/v1/integrations/hubspot/writeback \
    -H "Authorization: Bearer flowyte_sk_…" \
    -H "Content-Type: application/json" \
    -d '{ "mode": "summary_transcript", "onNoMatch": "create" }'
  ```

  ```js Node theme={null}
  const res = await fetch(
    "https://builder.flowyte.com/api/v1/integrations/hubspot/writeback",
    {
      method: "PATCH",
      headers: {
        Authorization: "Bearer flowyte_sk_…",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ mode: "summary_transcript", onNoMatch: "create" }),
    },
  );
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.patch(
      "https://builder.flowyte.com/api/v1/integrations/hubspot/writeback",
      headers={"Authorization": "Bearer flowyte_sk_…"},
      json={"mode": "summary_transcript", "onNoMatch": "create"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

`mode` is one of `off`, `summary`, or `summary_transcript`. `onNoMatch` (`skip` | `create`) is
optional and left unchanged when omitted.

## Beyond the pack: any object or field

The pack covers the common flows, but HubSpot is fully **open to author**: bind any object and
field — **including custom objects** — from the account's discovered schema. Three ways in:

* **"Describe it" AI authoring** — auto-map a plain-language goal to a validated binding with
  `POST /agents/{agentId}/integrations/hubspot/bindings/auto`. For a REST CRM like HubSpot this
  authors reads *and* writes (create, update, find-or-create, list-many, multi-filter, latest-sort).
* **The manual builder** — pick the object and fields yourself and map a binding with
  `POST /agents/{agentId}/integrations/hubspot/bindings`.
* **The API** — discover the schema, browse or search it, and author against the `restSearch`
  (read) and `restWrite` (create / update / find-or-create) grammars.

Walk through the whole flow in [Map an integration's fields](/guides/map-integration-fields).

## In the API

| Action                   | Endpoint                                                                                                             | Scope                  |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| Connect (OAuth consent)  | `POST /integrations/hubspot/connect`                                                                                 | `integrations:connect` |
| Get the Connector Pack   | `GET /integrations/hubspot/pack`                                                                                     | `integrations:read`    |
| Install the pack         | `POST /agents/{agentId}/integrations/hubspot/pack/install`                                                           | `skills:write`         |
| Discover the schema      | `POST /integrations/hubspot/discover`                                                                                | `integrations:write`   |
| Browse objects           | `GET /integrations/hubspot/objects` · `GET /integrations/hubspot/objects/{object}`                                   | `integrations:read`    |
| Search the schema        | `GET /integrations/hubspot/search`                                                                                   | `integrations:read`    |
| Author a binding         | `POST /agents/{agentId}/integrations/hubspot/bindings` · `POST /agents/{agentId}/integrations/hubspot/bindings/auto` | `skills:write`         |
| Read interaction logging | `GET /integrations/hubspot/writeback`                                                                                | `integrations:read`    |
| Set interaction logging  | `PATCH /integrations/hubspot/writeback`                                                                              | `integrations:write`   |

<Note>
  **Least privilege.** The consent grant requests the scopes for the standard objects (contacts,
  companies, tickets, deals). Custom-object scopes are **optional** and only requested / used when
  you author a binding against a custom object.
</Note>

<Warning>
  Installing the pack and authoring bindings edit the agent **draft**. [Publish](/concepts/agents)
  so phone and chat callers get the new skills.
</Warning>