TPSClear for HubSpot: setup guide.

Before you start

• A HubSpot account where you are a Super Admin, or a user with permission to install apps and create properties.
• The real-time and workflow features apply to contacts and companies. The workflow action requires a HubSpot plan that includes Workflows (Professional or Enterprise). The status property, sidebar card, and daily backfill work on every plan.
• UK phone numbers. TPSClear screens UK TPS and CTPS registrations. Non-UK and malformed numbers are marked Unknown rather than screened.

Step 1: Install via OAuth

1. 1. Start the install

   Click Install on HubSpot above, or open the TPSClear listing in the HubSpot App Marketplace and click Install. You are redirected to HubSpot's standard OAuth consent screen.

2. 2. Choose the account and review scopes

   Pick the HubSpot account to connect, then review the requested scopes. TPSClear asks only for read and write on contacts and companies, and read and write on their property schemas. No marketing, email, sales-engagement, or files scopes are requested. The full list and the reason for each is in the Scopes and data access section below.

3. 3. Connect

   Click Connect app. HubSpot returns you to TPSClear, which creates the screening properties and components on your portal automatically and confirms the connection. If property creation cannot complete, you are sent to a page that tells you exactly how to retry or reach support.

Step 2: What gets created on your portal

On a successful install, TPSClear creates the following on your HubSpot account. Nothing else is added, and no existing data is modified except the status properties TPSClear owns.

• A tps_status property on contacts and on companies, in a dedicated "TPSClear" property group. The value is one of Clean, TPS-listed, CTPS-listed, or Unknown (not screened).
• A tps_checked_at timestamp property on contacts and companies, recording when each number was last screened.
• A TPSClear sidebar card on contact and company records, showing the verdict for every mapped phone property and a one-click re-screen button.
• A "Screen for TPS/CTPS" workflow action available in HubSpot Workflows for contacts and companies.
• Webhook subscriptions on the phone fields (contact phone, mobilephone, fax, hs_additional_phones; company phone) so a number change triggers an immediate re-screen.

Step 3: Configure (optional)

TPSClear works immediately on the default phone fields. Open the TPSClear settings page inside HubSpot (Settings, then Integrations, then Connected Apps, then TPSClear) to tune two things.

1. 1. Phone-property mappings

   Add or remove the phone properties you want screened on contacts and companies. Pick from the standard HubSpot phone fields or enter a custom property name for direct lines or work numbers. Each mapping gets its own status property so verdicts stay independent per number.

   

2. 2. Daily backfill hour

   Choose the UTC hour for the daily backfill sweep. The real-time path handles live edits within seconds; the backfill catches anything imported or bulk-edited outside the webhook path. Pick a quiet hour for your team and save.

   

Step 4: The screening journey

1. 1. First screen

   After install, existing records are screened on the next daily backfill run. To screen a record immediately, open it and click Re-screen now on the TPSClear card.

2. 2. Real-time re-screen on change

   When a phone number changes, by a rep, a form submission, an import, or another integration writing to the field, the webhook fires and the verdict updates within seconds. The sidebar card and the tps_status property both reflect the new result.

   

3. 3. Use the verdict anywhere

   Because tps_status is a normal HubSpot property, you can filter lists on it, branch workflows, gate sequence enrolment, and build reports. For example, exclude tps_status is any of TPS-listed from a calling list before a campaign.

   

4. 4. Audit trail

   Every screen is logged with a timestamp, the number checked, the verdict, and the source (the TPSL register or a manual override), so you can evidence due diligence under PECR.

Scopes and data access

TPSClear requests the minimum OAuth scopes needed to read phone numbers and write verdicts back. Each scope and its purpose:

• crm.objects.contacts.read, crm.objects.companies.read read the phone numbers on contacts and companies so they can be screened.
• crm.objects.contacts.write, crm.objects.companies.write write the verdict and checked-at timestamp back onto the record.
• crm.schemas.contacts.read, crm.schemas.companies.read read property definitions to confirm the status properties exist.
• crm.schemas.contacts.write, crm.schemas.companies.write create the tps_status and tps_checked_at properties and their property group on install.

Contact and company data is two-way: TPSClear reads phone numbers from HubSpot and writes verdicts back. Contact and company properties are also two-way: TPSClear reads property definitions and creates its own status properties. No marketing, email, sales-engagement, deals, or files scopes are requested. Full detail is in our privacy policy.

Uninstall and data retention

To uninstall, open Settings, then Integrations, then Connected Apps in HubSpot, select TPSClear, and click Uninstall. This revokes the OAuth tokens and stops all screening. The status properties and their existing values are left on your records so historical verdicts are preserved. You can delete those properties manually if you want them gone.

Troubleshooting

• Verdicts not appearing. Confirm the install completed and the properties exist (Settings, Properties, search for "TPS"). Click Re-screen now on a record to force a check.
• Properties were not created on install. Reinstall from your Connected Apps list, or email support@tpsclear.co.uk with your portal ID and we will re-run property creation.
• A number shows Unknown. The number is non-UK, empty, or not in a recognisable format. TPSClear screens UK numbers only.