> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dcal/integrations/hubspot.md).

# HubSpot

Connect HubSpot once for the whole dCal workspace so every accepted booking becomes a contact with a meeting. Learn the two scopes the private app needs, what dCal writes, how to send booking answers

Connect HubSpot once and every booking anyone in your workspace accepts becomes a HubSpot contact with a meeting on it. Reschedules and cancellations update that same meeting. For each event, you can also choose which booking answers fill which contact properties.

***

## What reaches HubSpot

| When                                        | What dCal does in HubSpot                                                                                                     |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| A booking is accepted                       | Finds the contact by email, or creates it, then adds a meeting to it.                                                         |
| The booking is rescheduled                  | Moves the same meeting to the new time.                                                                                       |
| The booking is cancelled, or you decline it | Marks the same meeting as canceled and starts its title with `[Canceled]` (`[Cancelada]` when the host uses dCal in Spanish). |

* **Only accepted bookings.** A booking made instantly is written right away. A request that needs your OK is written when you confirm it, and a declined request is never written.
* **Every way of booking counts:** your booking pages, team pages, bookings you create from **Bookings**, your Dapta agents and the API.
* **The contact.** dCal looks the contact up by the exact email the guest typed. An existing contact keeps its name. A new one is created with the email, a first name (the first word of the name the guest typed) and a last name (the rest). Only the person who booked becomes a contact, never the extra guests.
* **The meeting.** Its title is the event's name, it carries the start and end time, and its body lists the host, each answer the guest gave, the booking's campaign when it has one (a line such as `utm_source: newsletter` for each UTM tag it kept) and the booking reference. Text that looks like HTML, in an answer or a UTM tag, arrives as plain text. The link to manage the booking is never included. dCal does not set a HubSpot owner on it: the host appears as text in the body.
* **Nothing is ever deleted** in HubSpot, and dCal never creates properties there.
* **It never slows a booking.** dCal writes to HubSpot in the background, so the guest's booking goes through even if HubSpot is slow.

> **💡 Tip:** The **HubSpot tracking ID** you can set on an event, in **CRM Connection** > **Tracking and pixels**, is separate from this integration. It loads HubSpot's tracking code on that event's booking page so visits count in HubSpot, and with collected forms on in your HubSpot portal, HubSpot can also capture the booking form. Bookings themselves reach HubSpot only through this integration. See [Tracking and pixels](https://docs.dapta.ai/dcal/events/event-settings.md#tracking-and-pixels).

***

## Before you start

* You are an admin or owner of your dCal workspace.
* You can create a private app in your HubSpot account.

***

## Connect HubSpot

**Step 1:** Go to **Settings** > **Integrations**, or open [app.dcal.ai/admin/settings/integrations](https://app.dcal.ai/admin/settings/integrations). The **HubSpot** card reads **Not connected**. Click **Connect**.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-ae212667d7f12df3d4790adec5a695d1a9ca32ce%2Fdcal-hubspot-01-card-not-connected.png?alt=media" alt="The HubSpot card on the Integrations tab with the Not connected badge and the Connect button, both boxed, and the line Nothing is being sent to HubSpot from this workspace."><figcaption><p>One card, one connection for the whole workspace.</p></figcaption></figure>

***

**Step 2:** The **Connect HubSpot** dialog lists the two scopes the private app needs. In HubSpot, create a private app and grant it both:

* `crm.objects.contacts.read`
* `crm.objects.contacts.write`

Then copy the app's access token. The dialog points you to Settings, Integrations, Private Apps in HubSpot; newer HubSpot accounts list private apps under Development, Legacy apps. HubSpot's [private apps guide](https://developers.hubspot.com/docs/guides/apps/private-apps/overview) has the current steps.

<figure><img src="https://3835013762-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCy5rSNtQmtqYCGzJlNEB%2Fuploads%2Fgit-blob-80acb64e30e40afa717b869a7ca0d379a6f9f57a%2Fdcal-hubspot-02-connect-dialog.png?alt=media" alt="The Connect HubSpot dialog with the two scopes crm.objects.contacts.read and crm.objects.contacts.write as an unticked, boxed checklist, an empty Access token field, the optional Portal name field and the Connect button still disabled"><figcaption><p>Tick each scope as you grant it in HubSpot. The ticks are only a checklist for you.</p></figcaption></figure>

> **⚠️ Note:** Grant both scopes before you paste the token. dCal checks the token by reading from HubSpot, so a token that can only read still connects, and the card then turns **Needs attention** at the first accepted booking.

***

**Step 3:** Paste the token in **Access token**. If you like, give the connection a **Portal name (optional)**, such as `Acme sales portal`, so you recognize it later. Click **Connect**.

dCal checks the token with HubSpot before it saves anything, and never shows it again. You see **HubSpot connected.** and the card reads **Connected**, with the portal name, **Token ending in** and its last four characters, and **Last checked** with a date.

If the check fails, nothing is saved and the dialog says why:

| Message                                                                                    | What to do                                                                      |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| **HubSpot rejected that token. Check that the private app is active and has both scopes.** | Copy the token again from the private app and make sure the app is active.      |
| **HubSpot says these scopes are missing:** followed by the scope names                     | Grant those scopes to the private app in HubSpot, then click **Connect** again. |
| **We could not reach HubSpot to check that token. Try again in a moment.**                 | Wait a moment and click **Connect** again.                                      |

***

## Send booking answers to contact properties

Mappings are set per event. Anyone who can edit the event can set them, once the workspace is connected.

**Step 4:** Open the event from **Events** and select **CRM Connection** > **Send answers to your CRM**. Click **+ Map an answer**, choose the **Answer** and the **Contact property** it fills, then click **Save changes**.

| Group                | Answers you can send                                                                                                                                                                                                                                                                                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Intake questions** | The booking questions of this event.                                                                                                                                                                                                                                                                            |
| **Attendee details** | **Phone**, **Notes**, **Time zone**, **Language**.                                                                                                                                                                                                                                                              |
| **Event details**    | **Event name**, **Booking start**, **Length in minutes**, **Assigned host**, **Assigned host email**.                                                                                                                                                                                                           |
| **Campaign (UTM)**   | **Source (utm\_source)**, **Medium (utm\_medium)**, **Campaign (utm\_campaign)**, **Term (utm\_term)**, **Content (utm\_content)**: the UTM tags of the link the guest booked from. See [Track where bookings come from](https://docs.dapta.ai/dcal/share/your-booking-page.md#track-where-bookings-come-from). |

* **Always sent:** name and email identify the contact, so they cannot be mapped.
* **+ Add another property** sends the same answer to more than one property, up to 10.
* Each property can take only one answer, and one event holds up to 50 mappings.
* The property list only offers properties that fit the answer, such as a number property for a number answer, and only ones dCal can write to. If the one you want is missing, create it in HubSpot and click **Refresh properties**.
* **Suggest mappings** fills in the obvious pairs for you. Review them: nothing is saved until you click **Save changes**.
* For a choice question, each option is matched to a HubSpot option by its value or label, ignoring case, accents and spacing. The section tells you how many options match, and an option with no match is not sent.
* A UTM tag fills a text property, or a single-choice dropdown such as a lead source: there, the tag's value is matched to an option the same way, and a value with no match is not sent.

If the workspace has not connected HubSpot yet, the section reads **No CRM is connected yet** with a **Go to Integrations** link. Mappings you already set are kept, and they work again when HubSpot is reconnected.

***

## Overwrite rules

| Rule                                                           | What it means for you                                                                                                                                                                   |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A mapped property is overwritten on every accepted booking.    | It always holds the contact's most recent answer.                                                                                                                                       |
| A blank answer never erases a value.                           | An optional question left empty keeps what HubSpot already has.                                                                                                                         |
| A campaign is written as one set.                              | When a booking has any UTM tag, a mapped tag it lacks empties its property, so two campaigns never mix on one contact. A booking with no UTM tags leaves the earlier campaign as it is. |
| Name and email are written only when dCal creates the contact. | A contact HubSpot already knows keeps the name it has.                                                                                                                                  |
| Mapped properties are written when a booking is accepted.      | Rescheduling or cancelling does not touch them.                                                                                                                                         |

***

## Connection states

| Badge               | What it means                                                                          | What to do                                                                                                         |
| ------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Not connected**   | Nothing is sent to HubSpot from this workspace.                                        | Click **Connect**.                                                                                                 |
| **Connected**       | Accepted bookings reach HubSpot.                                                       | Nothing.                                                                                                           |
| **Needs attention** | Bookings stopped reaching HubSpot. The card lists the scopes HubSpot says are missing. | Grant those scopes in HubSpot. The next accepted booking goes through on its own; there is nothing to paste again. |
| **Disconnected**    | The token was removed. Existing bookings still point at their meetings.                | Click **Reconnect** and paste a token for the same portal to pick up where you left off.                           |

To stop sending bookings, click **Disconnect**, then **Yes, disconnect**. Nothing is deleted inside HubSpot: contacts and meetings already there stay as they are.

## Related

* [Booking questions](https://docs.dapta.ai/dcal/events/booking-questions.md): the questions you can map.
* [Confirm or decline requests](https://docs.dapta.ai/dcal/bookings/confirm-or-decline.md): when a request reaches HubSpot.
* [Webhooks](https://docs.dapta.ai/dcal/integrations/webhooks.md): send the same bookings to your own system.
* [Integrations](https://docs.dapta.ai/dcal/integrations.md): everything dCal connects to.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dapta.ai/dcal/integrations/hubspot.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
