> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/heyreach.md).

# HeyReach

The HeyReach integration connects your HeyReach organization to Harmony. You see who has access to HeyReach, what role each person holds, which people hold a LinkedIn sender seat, and how much outreach each sender runs. HeyReach appears as a managed application in Application Management.

#### What the HeyReach integration enables

| Capability                 | Description                                                                                                                                                   |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User Discovery             | Surface every member of your HeyReach organization, including external Managers and pending invitations                                                       |
| Role Visibility            | See each member's HeyReach role; members who can manage billing, members or workspaces are flagged as administrators                                          |
| Seat Visibility            | See which people hold a LinkedIn sender, the seat HeyReach bills for                                                                                          |
| Sender Activity            | Track the messages, connection requests, InMails, profile views and replies each sender's campaigns produce per day, across every workspace you add a key for |
| Multi-Organization Support | Connect several HeyReach organizations, each as its own instance                                                                                              |

***

#### Prerequisites

1. **A HeyReach plan with API access** - HeyReach includes its API on the Growth, Agency and Unlimited plans
2. **A HeyReach organization Admin** - only organization Admins can see the Organization API key
3. **Optional: workspace API keys** - needed only for sender activity, one per workspace, and each workspace needs at least one LinkedIn sender (see [Step 2](#step-2-optional-copy-workspace-api-keys))
4. **A Harmony account** with admin privileges

***

#### Connect HeyReach to Harmony

HeyReach has two kinds of API key, and each one only works on its own part of the API:

* The **Organization API key** lists members and LinkedIn senders across every workspace in the organization. Harmony requires it.
* A **workspace API key** reads one workspace's sender statistics. Workspace keys are optional: add one for each workspace whose senders you want activity for. Without any, Harmony syncs users and seats only.

**Step 1: Copy your Organization API key**

Sign in to HeyReach as an organization Admin, then:

1. Open your **Organization settings**
2. Find the **Organization API key**
3. **Copy the key**

{% hint style="warning" %}
**Use the Organization key here, not a workspace key.** A workspace API key cannot read the organization's members, and Harmony refuses it in this field when you click **Connect**.
{% endhint %}

**Step 2 (optional): Copy workspace API keys**

For each workspace whose senders you want activity for, open the workspace, then:

1. Go to **Integrations** > **HeyReach API**
2. **Copy the workspace's API key**. If the workspace has none yet, create one there

{% hint style="info" %}
**Each workspace needs a LinkedIn sender.** Harmony confirms that a workspace key belongs to your organization by finding one of the workspace's senders on the organization's sender list. A key for a workspace with no LinkedIn sender is refused when you click **Connect**. Add it once the workspace has a sender.
{% endhint %}

{% hint style="warning" %}
**Creating a new workspace key deactivates the previous one.** If another tool, such as Zapier, Make or n8n, already uses this workspace's API key, copy the existing key instead of generating a new one, or update that tool afterwards.
{% endhint %}

{% hint style="info" %}
**Activity covers the workspaces you add keys for.** A workspace key reaches only its own workspace. Senders in a workspace without a key still appear as users and seats, but show no activity. Do not read them as idle.
{% endhint %}

**Step 3: Navigate to Integrations**

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **HeyReach** under **SaaS Applications**, or search for it by name
4. Click its card. If a HeyReach organization is already connected, click **+ Create instance**

**Step 4: Enter Credentials**

1. **Instance name** (required) - for example the name of the HeyReach organization
2. **Organization API Key** - the key you copied in Step 1
3. **Workspace API Keys** - the keys you copied in Step 2, separated by commas, or leave the field empty
4. Click **Connect**

When you click **Connect**, Harmony checks every key with HeyReach before saving. The Organization API key must list your organization's workspaces, and each workspace key must open a workspace of that same organization. If a key fails, the connection is refused and the message names the key at fault, numbering workspace keys in the order you entered them, each key counted once (for example, `workspace API key #2`). HeyReach can be slow to answer these checks, so saving can take a minute or more.

Once connected, Harmony begins syncing members and LinkedIn senders from your HeyReach organization. Connect each HeyReach organization once: a second connection with the same Organization API key lists the same people twice.

***

#### Disconnect HeyReach from Harmony

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **HeyReach** under **SaaS Applications** and click its card
4. Click the delete (trash) icon next to the instance you want to remove
5. Confirm when prompted

Once disconnected, Harmony stops syncing data from HeyReach. Previously synced data remains available in Harmony.

***

#### What Harmony Syncs from HeyReach

| Data             | Description                                                                                                                                                                                                                                                                                     |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Members          | Name and email address of every organization member: Admins, Members and external Managers                                                                                                                                                                                                      |
| Invitations      | Pending invitations, recorded with status **Pending** until the person joins. Expired invitations are skipped. A pending invitation has no name yet, so Harmony shows the part of the email before the `@`                                                                                      |
| Role             | The member's HeyReach role (Admin, Member or Manager), as HeyReach names it. Members who can manage billing, members or workspaces are classified as administrators; everyone else, Managers included, as members                                                                               |
| LinkedIn senders | Every LinkedIn sender account in the organization, across all workspaces: its workspace, whether it is connected, whether its LinkedIn login is still valid, its number of active campaigns, and whether it has Sales Navigator or Recruiter                                                    |
| Seat usage       | HeyReach bills per LinkedIn sender, so a person holding any sender, connected or not, is recorded as holding a paid seat and a member without one as free. Harmony counts people, not senders: a person running three senders is one paid user in Harmony and three seats on your HeyReach bill |
| Sender activity  | Daily counters per sender, from the workspaces you added a key for (see below)                                                                                                                                                                                                                  |

{% hint style="info" %}
**How members and senders are matched.** HeyReach does not record which member runs which LinkedIn sender. Harmony joins them by email: a sender whose LinkedIn email matches a member's HeyReach email is shown on that member. A sender that matches no member appears as a user of its own, named after the LinkedIn account. A rep who connected LinkedIn with a different address from their HeyReach login therefore appears twice: once as a member, once as a sender.
{% endhint %}

{% hint style="info" %}
**What sender activity counts.** For each sender and day, Harmony records messages sent, connection requests sent, InMails sent, profile views, follows, post likes, connections accepted, message replies, InMail replies, conversations started, InMail conversations started, voice notes sent, voice note replies, voice note conversations, replies auto-tagged, and replies auto-tagged as interested. These are actions a sender's campaigns run on a schedule, prospects responding, or HeyReach's AI tagging replies. None of them shows a person working in HeyReach. They appear in the **Activity** column, where a sender in a workspace you added a key for whose counts stay at zero is an idle seat, but they do not set **Last Login** or count anyone as active.
{% endhint %}

{% hint style="info" %}
**No login data.** HeyReach exposes no login, session or last-active information for members, so HeyReach users have no **Last Login** from HeyReach. As a result, HeyReach users read as inactive in License & cost and in usage insights. Harmony does not propose removing anyone's HeyReach access on this data.
{% endhint %}

{% hint style="info" %}
**No plan data.** HeyReach's API has no plan or subscription information, so Harmony shows no plan name and no seat price for HeyReach.
{% endhint %}

{% hint style="info" %}
**Sync cadence:** members and senders refresh every 6 hours. Sender activity is collected once a day for the day before yesterday (UTC), because HeyReach's sender reports can take a few hours to update. Each day is collected once. The first workspace keys you add backfill the last 90 days, whether you add them when connecting or later. A key added once other keys are already collecting activity starts from the next collected day; its earlier days are not backfilled.
{% endhint %}

***

#### Viewing HeyReach Data in Harmony

* **Application Management** - HeyReach appears as a managed application, where you can review its users, roles, seat counts and per-sender activity
* **User profiles** - individual users show their HeyReach access alongside other application data
* **Multiple organizations** - each connected HeyReach organization appears as its own HeyReach instance

***

#### Permissions Explained

All access is read-only. Harmony sends each key in the `X-API-KEY` header, and its requests use about 40% of HeyReach's limit of 300 requests a minute per key type (workspace keys and the Organization key are limited separately), leaving the rest to your other HeyReach integrations.

| What Harmony calls                                 | Key          | Why                                                                                                                              |
| -------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `POST /management/organizations/users`             | Organization | Members, pending invitations, roles and permissions                                                                              |
| `POST /management/organizations/linkedin-accounts` | Organization | LinkedIn senders across all workspaces. When you click **Connect**, confirms each workspace key's sender is in your organization |
| `GET /management/organizations/workspaces`         | Organization | Checks the key when you click **Connect**, and identifies your organization by its workspaces                                    |
| `POST /li_account/GetAll`                          | Workspace    | The workspace's LinkedIn senders. When you click **Connect**, one sender per key confirms the key belongs to your organization   |
| `POST /stats/GetOverallStats`                      | Workspace    | Daily statistics for each sender                                                                                                 |

Things to know about the keys:

* **HeyReach keys carry no scopes.** The Organization API key has the highest access HeyReach offers, which is why only organization Admins can see it
* Harmony never reads, creates or rotates your workspaces' integration keys (Zapier, Make, n8n, MCP), even though the Organization API key allows it
* Harmony only reads. It does not invite or remove members, connect or move senders, or start, pause or edit campaigns

***

#### Troubleshooting

<details>

<summary>The connection is rejected with "HeyReach rejected the Organization API key"</summary>

**Possible causes:**

* A workspace API key was entered in the **Organization API Key** field
* The key was rolled over in HeyReach

**Solutions:**

1. Ask an organization Admin to copy the current key from HeyReach's **Organization settings**
2. Enter it in the **Organization API Key** field

</details>

<details>

<summary>The connection is rejected with "HeyReach rejected workspace API key #N"</summary>

**Possible causes:**

* The Organization API key was entered in the **Workspace API Keys** field
* A newer workspace key was generated, which deactivates the previous one

**Solutions:**

1. Find the key by its number: keys are counted in the order you entered them
2. Copy the current key from **Integrations** > **HeyReach API** in that workspace
3. Or drop the key, so that workspace's senders sync without activity: clear the **Workspace API Keys** field and enter the other keys again

</details>

<details>

<summary>A workspace key is rejected because its workspace has no LinkedIn senders</summary>

**Cause:** Harmony confirms a workspace key by finding one of its workspace's senders on your organization's sender list. A workspace with no sender gives it nothing to check.

This also happens when a workspace loses its last LinkedIn sender after its key was added: Harmony checks every stored key on each save, so the stored key then blocks any change to the integration, replacing the Organization API key included.

**Solutions:**

1. Leave that key out for now: clear the **Workspace API Keys** field and enter the other keys again
2. Add it once a LinkedIn sender is connected in the workspace

</details>

<details>

<summary>A workspace key is rejected because it belongs to another HeyReach organization</summary>

**Cause:** the key's workspace is not part of the organization the Organization API key opens. This happens when you manage several HeyReach organizations, for example as an agency.

**Solutions:**

1. Enter only the workspace keys of the organization whose Organization API key is in this connection
2. Connect the other organization as its own HeyReach instance

</details>

<details>

<summary>Syncs stop with an authentication error after connecting</summary>

**Possible causes:**

* The Organization API key was rolled over or deleted in HeyReach
* Every workspace API key in the integration was replaced by a newly generated one, or its workspace was deleted. While at least one workspace key still works, Harmony skips the refused ones instead of failing

**Solutions:**

1. Copy the current key from HeyReach
2. Update the HeyReach instance in Harmony with it: for the Organization API key, click **Replace** next to **Organization API Key** and paste the new key; for workspace keys, edit **Workspace API Keys**. Then click **Save changes**. Syncing restarts straight away, even after it has stopped retrying, and picks up from where the data stopped

</details>

<details>

<summary>Senders appear as users but show no activity</summary>

**Possible causes:**

* No workspace API key is connected, so Harmony syncs users and seats only
* The senders belong to a workspace with no key in the integration
* The sender ran no campaigns in the period
* Activity for the last two days has not been collected yet
* The workspace's key was added after those days, while other keys were already collecting activity. Such a key starts from the next day Harmony collects, not the days before it
* The workspace key was refused by HeyReach during a sync while other keys still worked. Harmony skips the refused key and collects the others, but does not go back for that workspace's skipped days
* The sender's LinkedIn account has no email address. It still appears as a user, but Harmony has no user to credit its activity to

**Solutions:**

1. Add the workspace's API key to the integration's **Workspace API Keys**
2. If the workspace's key was replaced in HeyReach, update it in Harmony
3. If activity is missing for a sender in that workspace, check its numbers on HeyReach's sender performance report for the same days, allowing for a day's difference at the edges of the period

</details>

<details>

<summary>The same person appears twice</summary>

**Possible causes:**

* This is expected when the person connected their LinkedIn sender with a different email address from their HeyReach login - see [What Harmony Syncs from HeyReach](#what-harmony-syncs-from-heyreach)

**Solutions:**

1. No action is needed in Harmony. The sender record carries the seat and activity; the member record carries the role
2. When the person leaves, check the sender record too: when its LinkedIn email is not one Harmony knows for the employee, Harmony cannot link it to them, so it does not follow the member record through offboarding

</details>

<details>

<summary>Rotating the API keys</summary>

Rolling over the Organization API key, or generating a new workspace API key, immediately deactivates the old key. Update the HeyReach integration in Harmony with the new key straight away, and update any other tools that use the same workspace key, such as Zapier, Make or n8n. Until you do, a sync with the old Organization key fails and is retried. A refused workspace key is skipped while other workspace keys still work, and that workspace's activity for the skipped days is not collected later. When no workspace key works, the activity sync fails instead, and the missed days are collected once you update a key.

* **Workspace API Keys:** to add, remove or replace a key, clear the field and enter every key again, separated by commas
* **Organization API Key:** Harmony accepts a new key only if it opens the same HeyReach organization, which it checks against the workspaces recorded when you connected: the new key must open at least one of them. A key of another HeyReach organization is refused: connect that organization as its own HeyReach instance instead
* **Deleted workspaces:** adding workspaces, or deleting some, does not block a change. If every workspace recorded when you connected has been deleted, Harmony refuses any change to the integration, workspace keys included. Delete the instance and connect the organization again; the new connection appears as a new HeyReach instance, and the old one's synced data remains

</details>

***

#### Data & Privacy

<details>

<summary>Key privacy principles</summary>

For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).

* Harmony accesses HeyReach data in read-only mode and does not modify anything in your HeyReach organization
* The integration can be revoked at any time by disconnecting it in Harmony or by rolling over the keys in HeyReach

</details>

<details>

<summary>What Harmony does not collect</summary>

Harmony reads only organization membership, LinkedIn sender accounts and daily outreach totals. It does not collect:

* Leads, lists, prospects or their contact details
* Campaigns, sequences, message templates or message content
* Inbox conversations
* Invitation links, or your workspaces' integration keys
* IP addresses or login history - HeyReach exposes neither

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/saas-applications/heyreach.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
