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

# Import HubSpot contacts into Text and keep lead qualification in sync

> Run a Go service that imports your HubSpot contacts into Text and updates a property on each contact as Text qualifies or disqualifies them.

This guide is for teams who run their sales process in HubSpot and want their whole CRM contact base available for qualification in Text.

By the end of this guide, all of your existing HubSpot contacts are added to Text as customers that qualification applies to, and the moment Text qualifies or disqualifies one, their HubSpot contact is updated to match — so your team can filter for qualified leads directly in your CRM.

## How the service works

The service runs two flows, each with a single source of truth, so neither can overwrite the other.

**HubSpot into Text** is an import you run on demand. HubSpot decides which contacts exist, and each run copies the ones Text doesn't have yet.

**Text into HubSpot** runs continuously. Text decides whether a customer is qualified, and a listener updates the matching HubSpot contact whenever that verdict changes, in either direction.

The asymmetry is deliberate. A contact added to HubSpot after an import stays unknown to Text until the next run, and only the customers the listener monitors can send a qualification update back.

> [!WARNING]
>
> This sample doesn't retry failures or carry state between runs, so the two
> systems can drift apart. Adapt it to your needs before running the service
> against your real contact base — see [Prepare the service for
> production](#prepare-the-service-for-production).

## Prerequisites

**You'll need:**

* A [Text account](https://accounts.livechat.com/signup?landing_page=https%3A%2F%2Fwww.text.com%2F\&client_id=fc7bf1555adb6d3d2a441f10fd5b6eb5\&redirect_uri=https%3A%2F%2Fwww.text.com%2Fapp\&response_type=token\&source_type=website\&source_id=content-signup\&source_url=https%3A%2F%2Fwww.text.com%2F) with API access permission. The service connects as this account.
* A [HubSpot](https://www.hubspot.com/) account with permission to edit property settings and create a Service Key.
* [Docker with Docker Compose v2](https://docs.docker.com/get-started/get-docker/).
* [Git](https://git-scm.com/downloads) to clone the sample repository.

## Set up the integration

**1. Define qualification in Text**

Qualification runs on [customer fields](https://www.text.com/help/customer-fields/). If you don't have this definition set up yet, in Text, go to **Settings → [Customer fields](https://www.text.com/app/settings/customers/customer-fields)** and create the fields your team uses to determine a lead — company size, budget, whatever your sales process turns on. Assign the **Qualification** category to these fields so they appear in the **Qualification** section of the customer's profile.

A customer qualifies once every **Qualification** field has a value and they have an email address or a phone number.

**2. Create the Text personal access token**

Go to **Settings → API access → [Personal access tokens](https://www.text.com/app/settings/integrations/api-access/personal-access-tokens)** and create a token with these [scopes](https://www.text.com/docs/authentication/scopes.md):

* `customers:ro` — to look up customers by email, read merged profiles, and receive pushes.
* `customers:rw` — to create the customers the import is missing.

Copy the Base64-encoded value Text displays. It encodes `account_id:personal_access_token`, and you'll set it as `TEXT_TOKEN_BASE64`. See [Personal access tokens](https://www.text.com/docs/authentication/personal-access-tokens.md) for the full flow.

Create the token on the agent account you want the listener to run as. That account's team membership decides which customers the listener sees.

> [!WARNING]
>
> Treat the token like a password. Store it in a secrets manager for a
> deployed service and never commit it.

**3. Create the HubSpot property and access token**

The listener writes the qualification information to a contact property which you need to create yourself — the service validates it at startup but never creates it.

In HubSpot, go to **Settings → Properties**, select **Contact properties**, and create:

| Setting | Value |
| - | - |
| Label | Text qualified lead |
| Internal name | `text_qualified_lead` |
| Field type | Single checkbox |

The service writes only to this property. Check the internal name before saving, because HubSpot doesn't let you change it afterwards. Put the property in whichever contact property group suits your team. For more details, see HubSpot's [Create and edit properties](https://knowledge.hubspot.com/properties/create-and-edit-properties).

Then follow HubSpot's [Service Key setup](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys) and grant these [scopes](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/scopes):

* `crm.objects.contacts.read` — to page through contacts and look one up by email.
* `crm.objects.contacts.write` — to update the property.
* `crm.schemas.contacts.read` — to validate the property at startup.

If your HubSpot account already has a private app with these scopes, use its access token instead of creating a Service Key.

**4. Clone and configure the service**

Clone the repository and enter its directory:

```shell theme={null}
git clone https://github.com/livechat/hubspot-customer-qualification-guide.git
cd hubspot-customer-qualification-guide
```

Copy the example environment file:

```shell theme={null}
cp .env.example .env
```

Fill in `.env`:

| Variable | Description |
| - | - |
| `TEXT_TOKEN_BASE64` | The Base64-encoded token from Text, without the `Basic` prefix |
| `HUBSPOT_ACCESS_TOKEN` | Your HubSpot Service Key or private-app access token |
| `HOST_PORT` | The port the health endpoints bind to on your machine. Defaults to `8080` |

Git and the Docker build both ignore `.env`.

Both the import and the listener read this `.env` file.

**5. Import your HubSpot contacts**

Start with a dry run. It reads every contact and reports what a real import would do, without writing anything to Text:

```shell theme={null}
docker compose run --rm --build qualification import --dry-run
```

The command pages through every non-archived HubSpot contact, normalizes each primary email to lowercase, checks for an exact match in Text with [List customers](https://www.text.com/docs/api/customer-data-platform/customers/list-customers.md), and counts what it finds. Every counter below is a number of records. Review the summary before you run the final import:

| Counter | Meaning |
| - | - |
| `read` | Contacts read from HubSpot, before any filtering. |
| `missing_email` | Contacts skipped because they have no primary email address. |
| `invalid` | Contacts skipped because the email isn't a plain address, or the first and last name together exceed 255 characters. |
| `duplicate` | Contacts skipped because the same primary email appears on more than one HubSpot contact. Every copy is skipped. |
| `existing` | Contacts that matched exactly one Text customer. Nothing is created for them. |
| `ambiguous` | Contacts skipped because more than one Text customer has that email address. |
| `would_create` | Contacts missing from Text. Counted in both a dry run and a real run. |
| `created` | Customers created in Text. Always `0` in a dry run. |
| `failed` | Customers Text rejected. Always `0` in a dry run. |

A high `missing_email` or `duplicate` count is worth resolving in HubSpot first, because email is the only key that connects the two systems. Only the primary email counts — a contact's secondary addresses and HubSpot's own alias resolution are outside what this sample matches on.

> [!NOTE]
>
> There's no ceiling on how many contacts a run covers, so a large contact
> base costs time rather than coverage. Requests are paced at one every
> 200ms, which puts a floor of about five minutes on 55,000 contacts,
> before response times.

When the numbers look right, run the import:

```shell theme={null}
docker compose run --rm qualification import
```

The import creates the missing customers in batches of up to 100 with [Create customers](https://www.text.com/docs/api/customer-data-platform/customers/create-customers.md), copying the email and the combined first and last name. Run one import at a time.

The command exits `0` when the run completes and `1` when it stops on an error.

Rerun the import whenever you want to pick up contacts added to HubSpot since the last run, because nothing else brings them into Text. A later run doesn't create anything twice, because it finds the customers earlier runs created and counts them as `existing`. An import never propagates later edits to a HubSpot contact, and it never deletes a Text customer.

> [!WARNING]
>
> Check in Text that the last run's customers are there before you rerun an
> import. A newly created customer isn't guaranteed to be visible to the
> next lookup, so a rerun can otherwise duplicate them. A run that stopped
> partway leaves what it created, with no rollback.

**6. Start the qualification listener**

Build and start the service:

```shell theme={null}
docker compose up -d --build qualification
```

At startup the service validates the HubSpot property, finds your qualified lead definition, resolves your organization from your token, and opens an RTM connection with online customer monitoring. Any of those failing stops the service with a message naming the cause.

From then on the listener has to stay running. It updates HubSpot only while it's connected, and a push that arrives while the service is stopped is gone — Text doesn't queue it, and the listener doesn't catch up on reconnect. Run it as a long-lived service rather than starting it when you need it.

Confirm the service is connected:

```shell theme={null}
curl --fail --include http://localhost:8080/readyz
```

`/readyz` returns `204` once RTM login succeeds and `503` while disconnected. `/healthz` reports process liveness. Readiness describes the connection, not whether every qualification update succeeded.

Follow the logs while you test:

```shell theme={null}
docker compose logs --follow qualification
```

From here, a [`segment_memberships_updated`](https://www.text.com/docs/api/agent-chat/v3.6/rtm/pushes#segment_memberships_updated) push arrives whenever a monitored customer joins or leaves a segment. The listener ignores pushes for other segments. For one that matches, it re-reads the customer's [merged profile](https://www.text.com/docs/api/customer-data-platform/customers/get-merged-customer.md) to get the current verdict rather than trusting the event alone.

The service updates the property only when the value differs. It doesn't create new contacts.

**7. Verify qualification reaches HubSpot**

Test with a visitor who is online, identified by an email address that exists on exactly one HubSpot contact and one Text customer. Text monitors only live visitors, so an imported contact who isn't on your site can't trigger an update.

Change that visitor's data so they meet your qualified lead conditions. The log records the event, and the contact's **Text qualified lead** checkbox in HubSpot turns on.

Then change the data back so they no longer qualify. The checkbox turns off again.

## Act on qualification from HubSpot

Your team now has one property in HubSpot carrying the verdict your Qualification fields define. Those fields decide what qualifying means for your organization, and a conversation that fills the last one in moves the contact into view while it's still going on.

It's an ordinary contact property, so your usual HubSpot tools work on it: a list can filter on it, a workflow can enroll a contact the moment its value changes, and a view can order a day's follow-ups around it.

One characteristic is worth designing around: the property reflects membership as it stands, not history. A contact who stops meeting your conditions leaves a filtered list as quietly as they joined it. If a record of who was ever qualified matters to your team, capture it in HubSpot when the value changes, because the service doesn't keep one.

## Troubleshooting

| Symptom | Likely cause | What to check |
| - | - | - |
| The service exits at startup naming the token | `TEXT_TOKEN_BASE64` isn't a Base64-encoded `account_id:personal_access_token` | Copy the encoded value Text showed when you created the token. |
| The service exits naming the HubSpot property | The property is missing, isn't a single checkbox, or is read-only | Compare the internal name and field type against the table in step 3. |
| The service asks you to configure a segment | No customer field has the Qualification category yet | Assign the category to at least one field, which creates the definition. |
| The service exits right after starting | RTM login was rejected | Confirm `customers:ro` and an agent rather than a bot account. "Not allowed because of license settings" means your organization caps the monitoring level below `online`. |
| `/readyz` stays `503` | The connection keeps dropping and the listener is reconnecting | Follow the logs for reconnect warnings — repeated short failures stop the service. |
| A qualified customer never reaches HubSpot | The listener skipped them, or they aren't monitored | Find the customer in the logs. `missing_email` means they qualified on a phone number alone, `missing_hubspot` that no contact has their address, `ambiguous_text` or `ambiguous_hubspot` that more than one record matches, and `unchanged` that both systems already agree. No entry at all means they weren't monitored. |

## Prepare the service for production

Before you deploy this service, address these four areas.

> [accordion] Keep Text current as contacts are added to HubSpot
>
> An import only covers the contacts that existed when it ran, and it reads your
> whole contact base each time. Scheduling `docker compose run --rm
>     qualification import` keeps Text roughly current without depending on someone
> remembering to run it.
>
> For a continuous flow, a HubSpot app can subscribe to contact creation events
> and create the Text customer as each contact appears, leaving the import to seed
> what came before. That shifts the HubSpot side from a batch you remember to run
> to an integration that keeps itself current.

> [accordion] Close the coverage gap on qualification
>
> The listener only hears about customers Text is monitoring, and it never
> backfills. Customers already in the qualified lead segment when you first
> start it are never written to HubSpot, and neither are the verdicts that
> changed while the service was down.
>
> Before deploying:
>
> * Reconcile periodically by listing qualified customers and comparing them against the HubSpot property, so a missed event self-corrects.
> * Decide what an unset property means to your sales team, given that it covers both "not qualified" and "never seen."
> * Widen the agent's team membership if monitoring misses customers you care about, or subscribe to specific groups with [`subscribe_customers`](https://www.text.com/docs/api/agent-chat/v3.6/rtm/customers#subscribe-customers). Group subscriptions add to login monitoring, so overlapping coverage delivers the same change twice.

> [accordion] Make updates durable
>
> Every request gets one attempt, including rate-limited and server-error
> responses, and the listener holds pending updates in a 256-event in-memory
> buffer that discards an update when it overflows. A failed update is logged
> once and never retried.
>
> Before deploying:
>
> * Retry temporary Text and HubSpot failures with backoff, and alert when one still fails.
> * Replace the in-memory buffer with a durable queue so a restart doesn't drop pending updates.
> * Monitor `/readyz` and alert on sustained disconnection, because a stopped listener fails silently. The listener reconnects with backoff but gives up after repeated failures, so the container exits rather than retrying indefinitely.

> [accordion] Protect customer data in both systems
>
> The service copies customer identity and a qualification verdict from Text into
> HubSpot. Its logs hold counts, outcome labels, and status codes, and omit
> emails, names, customer IDs, and payloads.
>
> Before deploying:
>
> * Store both credentials in a secrets manager and rotate them like any other credential.
> * Confirm that copying qualification into HubSpot meets your consent and retention requirements.
> * Run the listener as a dedicated agent account, because connecting affects that account's presence and monitoring settings.

***

**Keep exploring**

&#x20;[Customer Data Platform API
reference](https://www.text.com/docs/api/customer-data-platform.md)

&#x20;[Agent Chat RTM API reference](https://www.text.com/docs/api/agent-chat/v3.6/rtm.md)

&#x20;[Customer identities and merged
customers](https://www.text.com/docs/key-concepts/customer-identities.md)

&#x20;[Personal access
tokens](https://www.text.com/docs/authentication/personal-access-tokens.md)


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