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

# HubSpot

> Sync respondents to HubSpot contacts, create follow-up tasks and send Usertick surveys from HubSpot workflows.

The HubSpot integration writes each response to the respondent's HubSpot contact: Usertick properties with the latest scores and AI readings, the answers you map, a note, the company link and a list for each survey. A Usertick [workflow](https://docs.usertick.com/workflows/overview.md) runs these writes, and it can also create follow-up tasks. In the other direction, two actions in HubSpot's own workflows send a Usertick survey or add a contact to a Usertick audience. HubSpot is available on the Pro plan and above.

## Connect HubSpot

**1. Open the HubSpot integration**

In **Settings → Integrations**, select **HubSpot**, then **Continue with HubSpot**.

**2. Approve the permissions**

In the HubSpot window that opens, select the HubSpot account, review the permissions and approve them. To get every feature, leave the optional permissions selected.

**3. Check the features**

After the window closes, the **In HubSpot** list shows the account by its domain and Hub ID, and which features are on.

HubSpot connects with OAuth only, so no API key or access token is needed. On connecting, Usertick creates the **Usertick** contact property group.

### Permissions

Usertick requires these permissions:

| Permission | Used for |
| - | - |
| Contacts, read and write (`crm.objects.contacts.read`, `crm.objects.contacts.write`) | Finding, creating and updating contacts, and adding notes and tasks to them |
| Contact properties, read and write (`crm.schemas.contacts.read`, `crm.schemas.contacts.write`) | Listing your contact properties for the mapping and creating the Usertick properties |

The other permissions are optional, and each one turns on one feature:

| Permission | Feature |
| - | - |
| Companies, read and write (`crm.objects.companies.read`, `crm.objects.companies.write`) | **Company link** links the contact to the company with the same email domain |
| Lists, read and write (`crm.lists.read`, `crm.lists.write`) | **List per survey** adds the contact to a static list named after the survey |
| Owners, read (`crm.objects.owners.read`) | **Task owner** sets who owns the tasks a workflow creates |
| Automation (`automation`) | **HubSpot workflow actions** send a Usertick survey or add a contact to an audience from a HubSpot workflow. Requires HubSpot Professional or Enterprise |

HubSpot grants an optional permission only when the account's plan includes it. A feature without its permission shows **Not granted**, and everything else keeps working. If an optional permission was cleared during approval, or the HubSpot plan now includes it, select **Reconnect** to turn the feature on.

Without the contacts permissions, Settings shows "HubSpot didn't grant access to contacts, so workflows can't sync them. Reconnect and approve every permission." Select **Reconnect** and approve every permission.

The **Usertick properties** row shows **Ready** when the property group exists, **Needs reconnect** when the contact properties permission is missing and **Couldn't be created** when HubSpot refused. **Test** in the connection's menu checks again and recreates any Usertick property that was deleted.

### Connect more than one account

An organization can connect several HubSpot accounts. A new HubSpot step starts with the connection the organization used last, or the default connection, and each step can use another one under **Connection**. Several Usertick organizations can also connect the same HubSpot account.

## How Usertick finds the contact

Usertick looks for the respondent's contact in this order:

1. **Your user ID** from [`identify()`](https://docs.usertick.com/installation/identify), in the contact property **Usertick user ID**. Usertick creates this property the first time a sync has a user ID. Its values are unique, so one user ID belongs to one contact.
2. **The email**, in HubSpot's own email property.

When neither finds a contact and **Create the contact when HubSpot has none** is on, the sync creates one, but only for a person Usertick can trust:

* a verified identity, from `identify()` with a valid hash,
* an email entered in a [Contact question](https://docs.usertick.com/surveys/question-types.md#contact-details),
* the contact an [email send](https://docs.usertick.com/channels/email.md) went to.

An identity without a valid hash can find an existing contact but never creates one.

The [verification mode](https://docs.usertick.com/installation/verify-users.md#choose-a-mode) changes what counts. In **Off**, a user ID and an email from `identify()` without a valid hash still find contacts. In **Monitor** and **Enforced**, they count as no one, and only a verified user ID, a verified email, a Contact question email or the contact an email send went to identify the person.

A sync fills in the person's details only where HubSpot has none:

* The email and the user ID. Usertick never replaces a different email or user ID.
* The first and last name, from the respondent's name, when the contact has neither.
* The company name, when the contact has none.

## Sync the contact

In a [workflow](https://docs.usertick.com/workflows/overview.md), add HubSpot's **Sync the contact** step and fill in its panel.

| Setting | What it does | Default |
| - | - | - |
| **Create the contact when HubSpot has none** | Creates the contact when none matches, only from a verified identity, a Contact question or a campaign. When it is off, a response without a contact is skipped | On |
| **Answers to contact properties** | Writes the answers you select to contact properties | None |
| **Add a note with the response** | Adds a note to the contact | On |
| **Note** | Sets the note's text, while the note is on | The survey name, the answers and a link to the response |
| **Link the company** | Links the contact to the company with the same email domain | On |
| **Add to a list for this survey** | Adds the contact to a static list named after the survey | Off |

### Usertick properties

Every sync writes these properties, whatever else the step does. They are in the **Usertick** property group on contacts:

| Property | Internal name | Value |
| - | - | - |
| Usertick last NPS | `usertick_last_nps` | The NPS score of the contact's latest response |
| Usertick last CSAT | `usertick_last_csat` | The rating answer of the contact's latest response, such as 4 on a 5-star scale |
| Usertick last CES | `usertick_last_ces` | The effort score of the contact's latest response |
| Usertick last response date | `usertick_last_response_at` | When the contact last answered a Usertick survey |
| Usertick last response link | `usertick_last_response_url` | A link that opens the contact's latest response in Usertick |
| Usertick response count | `usertick_response_count` | How many Usertick responses the contact sent |
| Usertick last feedback type | `usertick_last_type` | The feedback type the AI read in the latest response |
| Usertick last urgency | `usertick_last_urgency` | The urgency the AI read in the latest response |
| Usertick last theme | `usertick_last_theme` | The name of the theme the AI filed the latest response under |
| Usertick last sentiment | `usertick_last_sentiment` | The sentiment of the latest response's strongest answer |
| Usertick identity verified | `usertick_verified` | Yes when the latest response came with a verified identity |
| Usertick user ID | `usertick_user_id` | The user ID your product sends with `identify()`, created the first time it is needed |

The scores come from the survey's first answered NPS, rating and effort questions, each as the number given on that question's scale. **Usertick last CSAT** holds the rating answer itself, and the CSAT percentage that Usertick shows in results isn't written to HubSpot. The AI properties are written only for a response the AI analyzed, as lowercase values such as `bug`, `high` or `negative`. The "last" properties change only for a response at least as recent as the one they hold, so an older response that arrives late leaves them unchanged. The count goes up once per response, even when a run is retried.

### Map answers to contact properties

Under **Answers to contact properties**, add a row for each question, then select the question and a HubSpot property. The list shows your contact properties by label, with their kind: Text, Paragraph text, Number, Checkbox, Dropdown, Multiple checkboxes, Date or Date and time. Read-only and calculated properties, the email, Usertick user ID, the Usertick properties and the "Usertick:" question properties aren't in the list.

**Create a Usertick property for this question** creates a new property in the Usertick group, labeled "Usertick:" followed by the question. It is a number for score questions, a checkbox for yes or no questions and paragraph text for the rest.

* Up to 50 questions can be mapped, and each question and each property can appear once.
* Each answer is converted for its property: a number, yes or no, a dropdown option matched by its value or label, or a date. Choices go to text properties by their labels.
* A **Date** property gets the calendar day the answer names, as written. A **Date and time** property gets an answer only when the answer names its time zone. A date question's answer has none, so it is left out, and the run's details list the property under `skippedProperties`. To keep such an answer, map it to a **Date** or a text property.
* An answer the property can't hold, such as a word in a number property, is left out, and so is a value HubSpot refuses. The rest of the sync still goes through.
* A question the person skipped leaves its property unchanged.

### The note

**Add a note with the response** adds a note to the contact, and to the linked company. The note is dated at the response time, and its text is set under **Note**. Usertick adds a last line with "Usertick ref" and a code, so a retry never writes the same note twice.

### Company and list

**Link the company** takes the domain of the respondent's email and links the contact to the company with that domain, or to the oldest one when several have it. Usertick never creates a company, and public email domains such as gmail.com are skipped. This step requires the companies permission.

**Add to a list for this survey** adds the contact to a static HubSpot list named "Usertick:" followed by the survey name. Usertick creates the list the first time, or uses an existing static list with that name. If an active list has that name, the contact isn't added. This step requires the lists permission.

When the permission for the company link or the list is missing, that part is skipped, the rest of the sync goes through, and the feature's row under **In HubSpot** shows **Not granted**.

### When the sync runs

The workflow's trigger decides when the sync runs. In a workflow that starts **After AI analysis**, the response has its feedback type, urgency, theme and sentiment by then, so the AI properties are filled. A response the AI doesn't analyze still runs the step at that point, without AI values.

In a workflow that starts **When a response is submitted**, the sync runs right away, and the AI properties keep their previous values.

## Create a task

In a workflow, add HubSpot's **Create a task** step. The task is added to the respondent's contact, which is found the same way a sync finds it: by user ID, then by email. A task step never creates a contact or a property, so a response without a contact is skipped. To make sure the contact exists, put a **Sync the contact** step before it in the same workflow.

| Setting | What it does | Default |
| - | - | - |
| **Title** | Sets the task's title | `Follow up on {{survey.name}} feedback` |
| **Notes** | Sets the task's body | The survey name, the answers and a link to the response |
| **Due** | Sets the due date: **Today**, **In 1 day**, **In 2 days**, **In 3 days**, **In 5 days**, **In 1 week**, **In 2 weeks** or **In 30 days** after the step runs | **In 1 day** |
| **Priority** | Sets **Low**, **Medium**, **High** or **Match the AI urgency** | **Medium** |
| **Owner** | Sets the HubSpot user who owns the task. If left empty, the task is assigned to the contact's owner | The contact's owner |

The task is a to-do that isn't started yet, linked to the contact. Selecting an owner requires the owners permission; without it, tasks go to the contact's owner.

**Match the AI urgency** gives a response with High urgency a High task and one with Low urgency a Low task. Any other response, including one the AI didn't judge, gets Medium. A step with this priority reads the AI analysis, so its workflow has to start **After AI analysis** or **When a response becomes urgent**.

The workflow's **Only if** conditions, or an **If / else** step before the task, limit it to the responses that need a task, such as a low NPS score or a complaint.

## Test the steps

During a workflow's **Test run**, a HubSpot step uses the survey's latest response and writes to that person's real HubSpot contact. The note and the task title start with "\[Test]". When the survey has no response yet, the test uses a sample response, and the HubSpot step is skipped without writing anything. See [Test a workflow](https://docs.usertick.com/workflows/overview.md#test-a-workflow).

## Use the HubSpot workflow actions

Two actions let a HubSpot workflow reach Usertick: **Send Usertick survey** and **Add contact to Usertick audience**. Both work on contacts and require a HubSpot Professional or Enterprise plan and the automation permission.

**1. Create a workflow**

In HubSpot, go to **Automation → Workflows** and create a contact-based workflow.

**2. Add a Usertick action**

Add an action, search for **Usertick** and select **Send Usertick survey** or **Add contact to Usertick audience**.

**3. Select the survey or audience**

Select the **Survey** or the **Audience**. The list shows the surveys or contact lists of every Usertick organization connected to this HubSpot account, with the organization's name when there are several.

**4. Turn the workflow on**

Turn the workflow on. Each enrolled contact needs an email address.

If no Usertick organization has connected the HubSpot account, the list shows "This HubSpot account is not connected to Usertick. Connect it in Usertick first."

### Send Usertick survey

The action emails the selected survey to the enrolled contact. The email goes out the same way as a send from Usertick: from your sender, with the survey's email, within your plan's email limits, and never to someone who unsubscribed. Usertick finds the contact by email, or adds it with the name from HubSpot, and a contact added this way shows "Added from a HubSpot workflow".

A survey that can't be sent by email shows "Turn on link sharing in Usertick to send it by email." in the list. Later workflow steps can use **Usertick campaign ID** and **Usertick contact ID**.

### Add contact to Usertick audience

The action adds the enrolled contact to one of your [contact lists](https://docs.usertick.com/channels/email.md#contacts-and-lists) in Usertick. A contact that is already in the list counts as done. The list of audiences shows each one's member count, and later workflow steps can use **Usertick contact ID** and **Usertick audience ID**.

HubSpot may retry a call, and Usertick acts once per call, so a retry never sends a survey twice.

### When an action fails

A failed action shows its message in the workflow's history and sets **Usertick error code**, and the contact moves on to the next step.

| Code | Message in HubSpot | Action |
| - | - | - |
| `PORTAL_NOT_CONNECTED` | This HubSpot account is not connected to Usertick. Connect it again in Usertick. | Both |
| `MISSING_SURVEY` | No survey is selected. Pick one in this action. | Send Usertick survey |
| `SURVEY_NOT_FOUND` | Usertick could not find this survey. Pick another one in this action. | Send Usertick survey |
| `MISSING_AUDIENCE` | No audience is selected. Pick one in this action. | Add contact to Usertick audience |
| `AUDIENCE_NOT_FOUND` | Usertick could not find this audience. Pick another one in this action. | Add contact to Usertick audience |
| `PLAN` | Your Usertick plan does not include HubSpot. Upgrade to use this action. | Both |
| `NO_EMAIL` | This contact has no valid email address. | Both |
| `UNSUBSCRIBED` | This contact unsubscribed from Usertick emails. | Both |
| `LINK_SHARING_OFF` | Link sharing is off for this survey. Turn it on in Usertick first. | Send Usertick survey |
| `SENDER_NOT_READY` | Usertick cannot send email yet. Finish the email setup in Usertick. | Send Usertick survey |
| `NOT_REACHABLE` | This contact cannot get this survey by email. | Send Usertick survey |
| `NO_EMAIL_QUESTION` | The survey email has no question block. Add it in Usertick. | Send Usertick survey |
| `QUOTA` | Usertick reached an email sending limit. Try again later or upgrade your plan. | Send Usertick survey |
| `LINK_NOT_ALLOWED` | The survey email has links Usertick cannot send. Remove them in Usertick. | Send Usertick survey |
| `SURVEY_NOT_LIVE` | The survey isn't live, so it can't collect responses. Publish it or set it live in Usertick. | Send Usertick survey |
| `ORGANIZATION_INACTIVE` | The Usertick organization is deactivated or scheduled for deletion, so it can't send surveys. If deletion is scheduled, the owner can select Keep organization in Usertick. Otherwise, contact Usertick support. | Send Usertick survey |
| `SEND_FAILED` | Usertick could not send the survey. Try again later. | Send Usertick survey |

## Limits

HubSpot limits how often an app may call each HubSpot account, and Usertick stays under that limit for each account: at most 100 requests every 10 seconds and 4 searches a second, shared by every Usertick connection and organization that uses the account. A sync makes several calls, so when responses arrive faster than that, runs wait their turn and go out a little later. Waiting never counts as a failure. When HubSpot asks Usertick to slow down, every call to that account pauses for as long as HubSpot asks.

## Disconnect HubSpot

**Disconnect** in the connection's menu removes the connection, and workflow steps that use it stop sending until another connection is assigned to them. When no other Usertick organization still uses that HubSpot account, Usertick also uninstalls its app there, and HubSpot emails the account's admins. Another connection to the same account keeps the app installed.

Uninstalling Usertick in HubSpot also ends the connection. Within about 15 minutes, the connection shows **Revoked** with "HubSpot uninstalled the Usertick app. Reconnect HubSpot to continue.", and members whose role has the **Manage integrations** permission receive a notification that HubSpot was disconnected. To continue, select **Reconnect**.

Usertick deletes nothing in HubSpot: contacts, the Usertick properties, notes, tasks and lists stay. The workflow actions stop working and fail with the "not connected" message.

## Troubleshooting

A workflow's **Activity** lists each run, and a skipped step gives the reason:

* **"The response has no email address."** (`no_email`) Usertick has neither a user ID nor an email it may use for this person. In **Monitor** and **Enforced**, an identity without a valid hash counts as no one. Send the user's hash with `identify()`, add a Contact question, or send the survey by email.
* **"No HubSpot contact matches this person, and contacts are created only by a sync rule with a verified email."** (`no_contact`) No contact matched, and the step may not create one: **Create the contact when HubSpot has none** is off, the person is known only from an identity without a valid hash, or the step creates tasks, which never creates contacts.

Missing permissions appear like this:

* **"HubSpot did not grant access to contacts. Reconnect HubSpot and approve every permission."** The connection can't read contacts. Reconnect and approve every permission.
* **"HubSpot did not grant Usertick the … permission. Reconnect HubSpot and approve it."** A run failed because a permission is missing. Reconnect and approve it.
* **The company isn't linked, or the contact isn't in the list.** The companies or lists permission isn't granted. Also check that a company has the email's domain, that the email isn't from a public provider and that no active list has the survey's list name.
* **No task owner can be selected.** The owners permission isn't granted, so tasks go to the contact's owner.
* **The Usertick actions don't appear in a HubSpot workflow.** HubSpot offers them on the Professional and Enterprise plans, and the **HubSpot workflow actions** row in Usertick must show **On**. If it shows **Not granted**, reconnect after your HubSpot plan includes workflows.


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