Set Up The Twain HubSpot Integration

#What the app does

Twain researches the people in your HubSpot CRM and writes their outreach for you. The integration moves data in both directions:

• Into Twain. Contacts from a HubSpot list or segment, along with their company, standard properties, and any custom properties you keep. Optionally the conversation history on the contact, so a follow-up reads like a follow-up.
• Back into HubSpot. The sequence Twain wrote, the research behind it, and any custom variables — written onto the contact record as properties, so reps work from HubSpot without switching tools.

Nothing is written back to HubSpot until you run an export and choose which properties to write to.

#Before you start

You need:

• A Twain account. Sign up at usetwain.com — the free plan is enough to complete this setup.
• A HubSpot account with permission to install apps and to read the lists you plan to use. In HubSpot, that is a Super Admin, or a user with App Marketplace access enabled under Settings → Users & Teams.
• At least one contact list or segment in HubSpot to import from.

If you are not a Super Admin, HubSpot will show a permission error on the approval screen rather than installing partially. Ask an admin to grant App Marketplace access, or to complete the connection step for you.

#Install and connect your HubSpot account

The connection is made from inside Twain, and can be started from three places. They all open the same HubSpot approval screen and produce the same connection — pick whichever matches what you are doing.

1. Creating a campaign. Choose HubSpot as the lead source in the campaign setup flow.
2. An existing campaign. Open the campaign and click Import leads, then choose HubSpot.
3. A workflow. Add a HubSpot node to a workflow, for a connection that keeps running.

Clicking Connect sends you to HubSpot's own approval screen. Sign in if you are not already, choose the account you want to connect, and review the permissions Twain is asking for.

Permissions Twain requests, and why:

• oauth — establishes the connection itself.
• crm.objects.contacts.read — reads the contacts you choose to import.
• crm.objects.contacts.write — writes sequences and research back on export.
• crm.schemas.contacts.read — lists your contact properties so you can map fields.
• crm.schemas.contacts.write — creates the Twain properties an export writes into.
• crm.lists.read — shows your lists and segments in the picker.

Three further scopes are optional, and HubSpot presents them separately on the approval screen:

• sales-email-read — reads the email threads behind Import conversation history.
• crm.objects.deals.read and crm.objects.companies.read — read activity attached to an associated deal or company rather than to the contact itself. HubSpot associations do not carry over on their own, so without these the history is limited to what sits directly on the contact record.

Decline them and everything else still works — Twain simply will not read prior conversations.

Click Connect app in HubSpot. You are returned to Twain with the account linked, and the picker now lists your HubSpot lists.

Which HubSpot account gets connected? The one you are signed into when you approve. If you manage several, use the account switcher on HubSpot's approval screen before approving — Twain connects the account you pick there, not the one you were last in.

#Configure the integration

Once connected, two things need setting before your first run. Both live in the same import form.

1. Choose the list. Pick the HubSpot list or segment to import from. A static list imports the members it has today. A dynamic (active) list keeps changing in HubSpot, which matters if you put it behind a workflow — new members are picked up on their own.

2. Map your fields. Twain shows its fields on the left and your HubSpot properties on the right. At minimum, map an identifier it can research from: LinkedIn URL or work email. Map anything else you want Twain to use — job title, company, and any custom property your team keeps, such as persona, vertical, or deal stage. Custom properties are mapped the same way as built-in ones.

Field mapping is saved per campaign, so a later import into the same campaign reuses it.

#Use it: manual and automatic

Manually. Import a list, let Twain research the contacts and draft the sequences, then export back to HubSpot when you are happy with them. Open the campaign, click Export, choose HubSpot, and pick which HubSpot properties each piece of content should be written to.

Automatically. Put the HubSpot node on a workflow and the same steps run without you. Twain checks the segment about once a minute, pulls anyone new, runs the research, writes the sequence, exports it back, and can notify a Slack channel when it is done.

#Disconnect the integration

In Twain, open any HubSpot import step and click Disconnect. Confirm on the dialog that appears.

If workflows are still using the connection, Twain will not disconnect silently. The dialog lists every workflow that depends on it, marked active or paused, with links to each. Remove the HubSpot step from those workflows, or accept that lead syncing stops for them, before confirming.

What happens to your data when you disconnect:

• Twain deletes the stored access token. It can no longer read from or write to your HubSpot account.
• Nothing is deleted in HubSpot. Contacts and any properties Twain has already written stay exactly as they are.
• Nothing is deleted in Twain. Leads already imported, their research, and their sequences remain in your campaigns, and you can still edit and export them by other means.
• Workflows that relied on the connection stop syncing new leads. They are not deleted.

Reconnecting later restores access. It does not re-import anything on its own — you start a fresh import when you want one.

#Uninstall the app

Disconnecting from Twain is enough to stop all access. To remove the app from HubSpot as well:

1. In HubSpot, go to Settings → Integrations → Connected Apps.
2. Find Twain in the list.
3. Open the Actions menu and choose Uninstall.
4. Confirm.

What happens to your data when you uninstall:

• HubSpot revokes Twain's access token immediately. Every scope granted above is withdrawn.
• Your HubSpot data is untouched. Contacts, lists, and the properties Twain wrote remain. Properties Twain created stay in your schema; delete them from Settings → Properties if you want them gone.
• Your Twain data is untouched. Imported leads, research, and drafted sequences stay in Twain.
• Any Twain workflow with a HubSpot step stops syncing and reports the connection as unavailable.

Uninstalling in HubSpot and disconnecting in Twain have the same practical effect: no further data moves between the two systems. Doing both leaves the cleanest state.

#Troubleshooting and support

"You don't have permission to install this app." Your HubSpot user lacks App Marketplace access. An admin can grant it under Settings → Users & Teams, or complete the connection step for you.

The list picker is empty. The connected account has no lists Twain can read, or the crm.lists.read scope was not approved. Disconnect and reconnect, approving all required scopes.

Conversation history is not importing. The optional scopes were declined. Disconnect and reconnect with Import conversation history enabled, then approve them when HubSpot asks. If history arrives but looks thin, crm.objects.deals.read or crm.objects.companies.read was declined — anything logged against a deal or company is skipped without them.

An export wrote nothing. Check the field mapping on the export form — each message needs a HubSpot property to be written into. Properties must be text fields large enough for the content.

Contacts came in without research. Twain needs a LinkedIn URL or a work email to research someone. Map at least one of them in the field-mapping step.

Still stuck? Email support@usetwain.com or use the in-app chat. For how Twain stores and processes data, see our Privacy Policy and Terms of Service.