HubSpot

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 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

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: The other permissions are optional, and each one turns on one feature: 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(), 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,
• the contact an email send went to.

An identity without a valid hash can find an existing contact but never creates one. The verification 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, add HubSpot’s Sync the contact step and fill in its panel.

​

Usertick properties

Every sync writes these properties, whatever else the step does. They are in the Usertick property group on contacts: 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. 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.

​

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. 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 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.

​

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.