Skip to main content
If Planhat is where your post-sale truth lives — health, phase, renewal dates, conversation history — connecting it gives Thread’s agents that context to work from, and a place to leave a trail: timeline notes summarizing what ran, tasks created and closed with evidence, and company field updates. The connection is org-level: one Planhat workspace per Thread organization, authenticated with a Planhat Private App API token. Every read and write is scoped to the account the agent is working — an agent never picks which Planhat company it touches.

​
What it powers

Reads (agent tools, read-only): Writes (approval-gated like every state-changing action):
  • Timeline write-back — post a note to the company timeline summarizing what a Thread run did, keyed by the run ID so retries never duplicate an entry.
  • Task lifecycle — create a Planhat task tied to a Thread action, then close it later with evidence appended to the description (the original task notes are preserved).
  • Company updates — update fields on the linked company record.
Planhat writes are made as the Private App’s service identity, and they follow the same per-action autonomy rules as everything else an agent does — actions you haven’t opted out of approval for land in your Inbox before anything reaches Planhat.

​
Connect Planhat

You’ll need a Planhat Private App and its API Access Token. Only Thread org admins can connect.
1

Create a Private App in Planhat

In Planhat, create a Private App (service account) and grant it the permissions Thread uses. The connector page shows a live checklist; the cells to tick are:Copy the API Access Token generated for the app.
2

Enter the token and cluster

In Thread, open Connectors → Planhat. Pick your cluster — US (api.planhat.com), EU (api-eu5.planhat.com), or enter another cluster URL — paste the token, and click Connect Planhat. Thread validates the token before storing it (encrypted, in a vault).
3

Check the company count

As part of validation Thread asks the token how many companies it can see.
If the token authenticates but reports 0 companies, Thread still connects — a brand-new Planhat tenant legitimately shows zero — but surfaces a persistent warning. If you already have customers in Planhat, you likely connected the wrong workspace, or created the Private App without data access. Re-create the Private App copying permissions from a full-access Role.
4

Test the connection

Use the Test connection card on the connector page to confirm reads work end to end.
Thread keeps a per-account link between each Thread account and its Planhat company. Company-scoped tools — timeline reads, notes, tasks, company updates — resolve that link automatically at run time.
  • Linked account — tools just work; the agent never supplies a company ID.
  • Not linked yet — tools return a precise “this account isn’t linked to a Planhat company yet” result instead of guessing. The company lookup tool can still find the right company directly by web domain, Planhat external ID, or CRM ID (the Salesforce/HubSpot account ID — useful when Planhat is synced from the same CRM).

​
Planhat → Thread (inbound)

Thread has an inbound webhook endpoint that lets Planhat Automations post events back to Thread, authenticated with a Thread-issued access key.
The inbound direction isn’t currently surfaced on the connector page — today’s integration is read-plus-write-back from the Thread side. If you need Planhat Automations triggering Thread, contact support.

​
Troubleshooting

When the Private App is missing a permission cell, Thread’s error names the exact one — e.g. Conversation: Create. Add that permission to the Private App in Planhat and retry; no need to reconnect.
The account has no Planhat link. Have the agent look the company up by domain, external ID, or CRM ID — or check that the company exists in Planhat at all (Planhat’s own CRM sync runs on its own schedule, so a just-closed deal may not be there yet).
The token is valid but can’t see any companies. If your Planhat tenant has customers, re-create the Private App copying permissions from a full-access Role, or confirm you picked the right workspace and cluster.
Disconnecting removes the stored token and stops all Planhat reads and write-backs. Existing timeline entries and tasks in Planhat are untouched. You can reconnect at any time.

Connectors overview

How Thread’s connectors scope what agents can see and do.

Motion agents

Where Planhat tools show up in agent runs and approvals.