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

# Planhat

> Connect Planhat so agents can read customer success context — companies, timelines, opportunities — and write run summaries and tasks back under your approval.

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):**

| Tool           | What it sees                                                                          |
| -------------- | ------------------------------------------------------------------------------------- |
| Company record | The Planhat company linked to the account — phase, status, custom fields              |
| Timeline       | Conversations on the linked company: emails, tickets, calls, meetings, notes          |
| End users      | The people Planhat knows at the linked company                                        |
| Opportunities  | Deals on the linked company — stage, value, and the company an opportunity belongs to |
| Tasks          | Tasks Thread created, looked up by their Thread-side source ID                        |

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

<Note>
  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](/inbox/overview) before anything reaches Planhat.
</Note>

## Connect Planhat

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

<Steps>
  <Step title="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:

    | Planhat model | Permissions          |
    | ------------- | -------------------- |
    | Company       | View, Update         |
    | End User      | View                 |
    | Conversation  | Create, View         |
    | Task          | Create, View, Update |
    | Opportunity   | View                 |

    Copy the API Access Token generated for the app.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Check the company count">
    As part of validation Thread asks the token how many companies it can see.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Test the connection">
    Use the **Test connection** card on the connector page to confirm reads work end to end.
  </Step>
</Steps>

## How accounts link to Planhat companies

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.

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="403 errors naming a permission">
    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.
  </Accordion>

  <Accordion title="'This account is not linked to a Planhat company yet'">
    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).
  </Accordion>

  <Accordion title="Warning: workspace shows 0 companies">
    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.
  </Accordion>

  <Accordion title="Disconnecting">
    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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Connectors overview" icon="plug" href="/integrations/overview">
    How Thread's connectors scope what agents can see and do.
  </Card>

  <Card title="Motion agents" icon="robot" href="/motions/agents">
    Where Planhat tools show up in agent runs and approvals.
  </Card>
</CardGroup>