Connect AI agents to HeyReach

Scalekit connector

The HeyReach connector lets your AI agent act in each user's HeyReach account. Each user connects their own HeyReach API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 14 tools.

Tools: 14
What they doRead · write · destructive: 9 · 5 · 09 read5 write0 destructive
Users sign in with: API key

Setup

npm install @scalekit-sdk/node dotenv

pip install scalekit-sdk-python python-dotenv

Set your credentials
Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
Create the HeyReach connection
In AgentKit > Connections, create a HeyReach connection. The name you give it is the connection_name your code passes. See Configure connections.
Console steps with screenshots
Register your HeyReach API key with Scalekit so it can authenticate and proxy LinkedIn outreach requests on behalf of your users. HeyReach uses API key authentication.
1. Generate a HeyReach API key
  - Sign in to app.heyreach.io and open Dashboard -> Settings -> Integrations -> Get API Key.
  - Create a new API key, give it a descriptive name (e.g., HeyReach Agent), and confirm.
  - Copy the generated key. It is shown only once — store it somewhere safe before navigating away.
  Your HeyReach API key grants full access to your workspace — including launching campaigns, reading inbox conversations, and modifying lead lists. Never expose it in client-side code or commit it to source control.
2. Create a connection in Scalekit
  - In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find HeyReach and click Create.
  - Note the Connection name — you will use this as connection_name in your code (e.g., heyreach).
3. Add a connected account
  
  Connected accounts link a specific user identifier in your system to a HeyReach API key. Add one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.
  
  In the dashboard, to test
  - Open the connection you created and click the Connected Accounts tab → Add account.
  - Fill in:
    
    Your User’s ID — a unique identifier for this user in your system (e.g., user_123)
    
    API Key — the HeyReach API key you copied in step 1
  - Click Save.
  From your backend, if your app already has the credentials
  
  For example, when users enter them on a settings page in your app:
  Node.js
  Python
  1 import { ConnectorStatus } from '@scalekit-sdk/node' 2 3 const authorizationDetails = { 4 details: { 5 case: 'staticAuth', 6 value: { details: { api_key: 'your-heyreach-api-key' } }, 7 }, 8 }; 9 10 let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({ 11 connectionName: 'heyreach', 12 identifier: 'user_123', 13 authorizationDetails, 14 }); 15 16 // Make sure the account is ACTIVE before the first tool call. 17 if (connectedAccount?.status !== ConnectorStatus.ACTIVE) { 18 ({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({ 19 connectionName: 'heyreach', 20 identifier: 'user_123', 21 authorizationDetails, 22 })); 23 }
HeyReach enforces a rate limit of 300 requests per minute across all public API endpoints. Exceeding it returns 429 Too Many Requests. Batch operations (like adding up to 100 leads in a single heyreach_add_leads_to_campaign call) help you stay well under the limit.

Authorize a user and make your first call

Node.js
Python

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3
import { createInterface } from 'node:readline/promises'
4

5
const scalekit = new ScalekitClient(
6
  process.env.SCALEKIT_ENVIRONMENT_URL,
7
  process.env.SCALEKIT_CLIENT_ID,
8
  process.env.SCALEKIT_CLIENT_SECRET,
9
)
10
const actions = scalekit.actions
11

12
const connector = 'heyreach'
13
const identifier = 'user_123'
14

15
// Generate an authorization link for the user
16
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
17
console.log('Authorize HeyReach:', link)
18
const rl = createInterface({ input: process.stdin, output: process.stdout })
19
await rl.question('Press Enter after authorizing...')
20
rl.close()
21

22
// Make your first call
23
const result = await actions.executeTool({
24
  connector,
25
  identifier,
26
  toolName: 'heyreach_check_api_key',
27
  toolInput: {},
28
})
29
console.log(result)

npx tsx quickstart.mts

1
import os
2
from scalekit import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "heyreach"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize HeyReach:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="heyreach_check_api_key",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

python quickstart.py

Each user opens the link once and enters their HeyReach credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool

Try in Playground Request a tool

heyreach_check_api_keyVerify that your HeyReach API key is valid and the connection is working.Read-only
Check API Key
Verify that your HeyReach API key is valid and the connection is working. Returns HTTP 200 with empty body on success. Use this to validate a connection before making other API calls.
Inputs
This tool takes no inputs.
heyreach_get_all_campaignsList all LinkedIn outreach campaigns in your HeyReach account with pagination.Read-only
Get All Campaigns
List all LinkedIn outreach campaigns in your HeyReach account with pagination. Returns campaign metadata including status (DRAFT, IN_PROGRESS, PAUSED, FINISHED, FAILED), progress stats, associated lead list, and campaignAccountIds (LinkedIn sender account IDs needed for heyreach_get_overall_stats). Rate limit: 300 requests/minute.
Inputs
limitinteger
Maximum number of campaigns to return. Defaults to 10.
offsetinteger
Number of records to skip for pagination. Defaults to 0.
heyreach_get_all_linkedin_accountsList the LinkedIn sender accounts (connected LinkedIn profiles) in your HeyReach workspace with pagination.Read-only
Get All LinkedIn Accounts
List the LinkedIn sender accounts (connected LinkedIn profiles) in your HeyReach workspace with pagination. Returns each account's ID, name, profile URL, and status. Use the returned account IDs as linkedInAccountId when calling heyreach_add_leads_to_campaign, or as AccountIds in heyreach_get_overall_stats. Rate limit: 300 requests/minute.
Inputs
keywordstring
Optional search keyword to filter accounts by name.
limitinteger
Maximum number of LinkedIn accounts to return. Max 100. Defaults to 100.
offsetinteger
Number of records to skip for pagination. Defaults to 0.
heyreach_get_all_listsList all lead lists in your HeyReach account with pagination.Read-only
Get All Lists
List all lead lists in your HeyReach account with pagination. Returns list metadata including name, total lead count, list type, creation date, and associated campaign IDs. Use list IDs with heyreach_get_leads_from_list to retrieve leads. Rate limit: 300 requests/minute.
Inputs
limitinteger
Maximum number of lists to return. Defaults to 10.
offsetinteger
Number of records to skip for pagination. Defaults to 0.
heyreach_get_campaign_by_idRetrieve detailed information about a specific HeyReach campaign by its ID.Read-only
Get Campaign By ID
Retrieve detailed information about a specific HeyReach campaign by its ID. Returns campaign status, progress stats (total users, in progress, finished, failed), associated lead list, and LinkedIn sender accounts. Use get_all_campaigns first to find campaign IDs.
Inputs
campaignIdintegerrequired
The unique ID of the campaign to retrieve. Get campaign IDs from heyreach_get_all_campaigns.
heyreach_get_conversationsList LinkedIn inbox conversations across your HeyReach sender accounts with pagination and filters.Read-only
Get Conversations
List LinkedIn inbox conversations across your HeyReach sender accounts with pagination and filters. Returns conversation metadata: participants, last message, seen/unseen status, associated campaign and account. Filter by LinkedIn account IDs, campaign IDs, lead profile URL, tags, search string, or seen status. Useful to monitor replies to outreach sent via heyreach_add_leads_to_campaign. Rate limit: 300 requests/minute.
Inputs
campaignIdsarray
Filter conversations to these campaign IDs. Get campaign IDs from heyreach_get_all_campaigns.
leadLinkedInIdstring
Filter to conversations with a specific lead by their LinkedIn internal ID.
leadProfileUrlstring
Filter to conversations with a specific lead by their LinkedIn profile URL.
limitinteger
Maximum number of conversations to return (1-100). Defaults to 10 — a client-side cap applied in the jsonnet template to protect LLM context, since the HeyReach API's own default (~100) can return 400KB+ payloads. Pass a larger value explicitly if you need more.
linkedInAccountIdsarray
Filter conversations to these LinkedIn sender account IDs. Get account IDs from heyreach_get_all_linkedin_accounts.
offsetinteger
Number of records to skip for pagination. Defaults to 0.
searchStringstring
Free-text search across conversation content and participant names.
seenboolean
Filter by seen status. true = only seen conversations, false = only unseen. Omit to return both.
tagsarray
Filter conversations by lead tags.
heyreach_get_leadRetrieve detailed information about a single HeyReach lead by their LinkedIn profile URL.Read-only
Get Lead
Retrieve detailed information about a single HeyReach lead by their LinkedIn profile URL. Returns the lead's profile data (name, headline, location, company, position), email addresses (emailAddress, enrichedEmailAddress, customEmailAddress), tags, and custom fields. Useful to verify a lead exists in HeyReach before or after adding them to a campaign. Rate limit: 300 requests/minute.
Inputs
profileUrlstringrequired
The public LinkedIn profile URL of the lead to look up. Example: https://www.linkedin.com/in/janedoe
heyreach_get_leads_from_listRetrieve leads from a specific HeyReach lead list with pagination.Read-only
Get Leads From List
Retrieve leads from a specific HeyReach lead list with pagination. Returns detailed lead profiles including LinkedIn URL, name, headline, location, company, position, tags, and email addresses. Use heyreach_get_all_lists to find list IDs. Rate limit: 300 requests/minute.
Inputs
listIdintegerrequired
The unique ID of the lead list to retrieve leads from. Get list IDs from heyreach_get_all_lists.
limitinteger
Maximum number of leads to return. Defaults to 10 — a client-side cap applied in the jsonnet template to protect LLM context, since lists can hold thousands of leads (observed: 4,054). Pass a larger value explicitly if you need more.
offsetinteger
Number of records to skip for pagination. Defaults to 0.
heyreach_get_overall_statsRetrieve overall performance statistics for specific LinkedIn sender accounts and campaigns.Read-only
Get Overall Stats
Retrieve overall performance statistics for specific LinkedIn sender accounts and campaigns. Returns aggregate metrics including connection requests sent and accepted, messages sent and replied, InMail stats, and calculated rates (connection acceptance rate, message reply rate). Rate limit: 300 requests/minute.
Inputs
AccountIdsarrayrequired
IDs of the LinkedIn sender accounts (connected LinkedIn profiles) assigned to run this campaign. Each campaign has one or more sender accounts.
CampaignIdsarrayrequired
Array of campaign IDs to retrieve stats for. Get campaign IDs from heyreach_get_all_campaigns.
heyreach_add_leads_to_campaignAdd up to 100 leads to an existing HeyReach campaign.Write
Add Leads To Campaign
Add up to 100 leads to an existing HeyReach campaign. The campaign must be in an ACTIVE state (IN_PROGRESS), or use resumeFinishedCampaign / resumePausedCampaign to auto-resume. Each lead is bound to a specific LinkedIn sender account (linkedInAccountId) that will send the outreach. Use heyreach_get_campaign_by_id to find the campaign's sender accounts (campaignAccountIds). Rate limit: 300 requests/minute.
Inputs
accountLeadPairsarrayrequired
Array of lead + sender account pairs to add to the campaign (max 100). Each pair binds a lead to the LinkedIn sender account that will reach out. Minimum required per lead: profileUrl.
campaignIdintegerrequired
The ID of the HeyReach campaign to add leads to. Get campaign IDs from heyreach_get_all_campaigns.
resumeFinishedCampaignboolean
If true and the target campaign is in FINISHED state, HeyReach will resume it so the new leads can be processed. Defaults to false.
resumePausedCampaignboolean
If true and the target campaign is in PAUSED state, HeyReach will resume it so the new leads can be processed. Defaults to false.
heyreach_add_leads_to_listAdd leads directly to a HeyReach lead list, independent of any campaign.Write
Add Leads To List
Add leads directly to a HeyReach lead list, independent of any campaign. Use heyreach_create_list or heyreach_get_all_lists to find a list ID. To enroll leads into an outreach sequence instead, use heyreach_add_leads_to_campaign. Rate limit: 300 requests/minute.
Inputs
leadsarrayrequired
Array of lead profiles to add to the list (max 100). profileUrl is required per lead; other fields enrich the lead record.
listIdintegerrequired
The ID of the HeyReach list to add leads to. Get list IDs from heyreach_get_all_lists.
heyreach_create_listCreate a new empty lead list in your HeyReach account.Write
Create List
Create a new empty lead list in your HeyReach account. Use heyreach_add_leads_to_list afterward to populate it, or reference the returned list ID from campaign setup. Rate limit: 300 requests/minute.
Inputs
namestringrequired
Name for the new lead list.
listTypestring
Type of list to create. USER_LIST holds LinkedIn profile leads; COMPANY_LIST holds companies.one of USER_LISTCOMPANY_LIST
heyreach_pause_campaignPause an active HeyReach campaign so it stops sending new outreach actions.Write
Pause Campaign
Pause an active HeyReach campaign so it stops sending new outreach actions. Leads already in progress keep their current state until the campaign is resumed. Use heyreach_get_all_campaigns to find campaign IDs. Rate limit: 300 requests/minute.
- Idempotent
Inputs
campaignIdintegerrequired
The ID of the HeyReach campaign to pause. Get campaign IDs from heyreach_get_all_campaigns.
heyreach_resume_campaignResume a paused, finished, or failed HeyReach campaign so it starts sending outreach actions again.Write
Resume Campaign
Resume a paused, finished, or failed HeyReach campaign so it starts sending outreach actions again. Use heyreach_get_all_campaigns to find campaign IDs. Rate limit: 300 requests/minute.
- Idempotent
Inputs
campaignIdintegerrequired
The ID of the HeyReach campaign to resume. Get campaign IDs from heyreach_get_all_campaigns.

Workflows

Proxy API call

Node.js
Python

// Verify the connected API key works — no key needed in your code
const result = await actions.request({
  connectionName: 'heyreach',
  identifier: 'user_123',
  path: '/auth/CheckApiKey',
  method: 'GET',
});
console.log('API key valid:', result.status === 200);

# Verify the connected API key works — no key needed in your code
result = actions.request(
    connection_name='heyreach',
    identifier='user_123',
    path="/auth/CheckApiKey",
    method="GET"
)
print("API key valid:", result.status_code == 200)

Add leads to a campaign

The most common HeyReach workflow: pick an active campaign, choose a LinkedIn sender account to send from, and add up to 100 leads in a single call. Each lead is bound to a specific sender — so a campaign with multiple senders can round-robin or be sharded by your code.

1
# Step 1: Pick a campaign and one of its sender accounts
2
campaigns = actions.execute_tool(
3
    connection_name='heyreach',
4
    identifier='user_123',
5
    tool_name="heyreach_get_all_campaigns",
6
    tool_input={"limit": 25}
7
)
8
campaign = campaigns.data["items"][0]              # or filter by name/status
9
sender_account_id = campaign["campaignAccountIds"][0]
10
print(f"Adding leads to campaign {campaign['id']} via sender {sender_account_id}")
11

12
# Step 2: Add up to 100 leads bound to that sender account
13
new_leads = [
14
    {"profileUrl": "https://www.linkedin.com/in/jane-doe"},
15
    {"profileUrl": "https://www.linkedin.com/in/john-smith"},
16
]
17
result = actions.execute_tool(
18
    connection_name='heyreach',
19
    identifier='user_123',
20
    tool_name="heyreach_add_leads_to_campaign",
21
    tool_input={
22
        "campaignId": campaign["id"],
23
        "accountLeadPairs": [
24
            {"linkedInAccountId": sender_account_id, "lead": lead}
25
            for lead in new_leads
26
        ],
27
        # Auto-resume the campaign if it's paused or already finished
28
        "resumePausedCampaign": True,
29
        "resumeFinishedCampaign": True,
30
    }
31
)
32
print(f"Added {len(new_leads)} leads:", result.data)

Look up a lead before reaching out

Verify a lead already exists in HeyReach (and check their tags or enrichment status) before adding them to a campaign — this avoids duplicate outreach and lets you skip leads that are already engaged.

1
result = actions.execute_tool(
2
    connection_name='heyreach',
3
    identifier='user_123',
4
    tool_name="heyreach_get_lead",
5
    tool_input={
6
        "profileUrl": "https://www.linkedin.com/in/jane-doe"
7
    }
8
)
9

10
lead = result.data
11
if lead:
12
    print(f"{lead['fullName']} — {lead.get('position') or lead.get('summary')}")
13
    print(f"  Company:  {lead.get('companyName')}")
14
    print(f"  Location: {lead.get('location')}")
15
    print(f"  Email:    {lead.get('emailAddress') or lead.get('enrichedEmailAddress')}")
16
else:
17
    print("Lead not found — safe to add to a new campaign.")

Monitor inbox replies

After outreach goes out, poll the unified LinkedIn inbox for unseen replies. Filter by campaign or sender account so you only surface conversations relevant to your agent’s workflow.

1
result = actions.execute_tool(
2
    connection_name='heyreach',
3
    identifier='user_123',
4
    tool_name="heyreach_get_conversations",
5
    tool_input={
6
        "campaignIds": [campaign["id"]],   # filter to one campaign
7
        "seen": False,                      # only unseen conversations
8
        "limit": 25,
9
    }
10
)
11

12
for convo in result.data.get("items", []):
13
    profile = convo.get("correspondentProfile", {})
14
    messages = convo.get("messages", [])
15
    last_msg = messages[-1] if messages else {}
16
    print(f"📬 {profile.get('fullName')} — {profile.get('profileUrl')}")
17
    print(f"   {last_msg.get('createdAt')} ({last_msg.get('sender')}): "
18
          f"{(last_msg.get('body') or '')[:120]}")

Track campaign performance

Pull aggregate metrics for one or more campaigns — connection acceptance rate, message reply rate, InMail performance — to power dashboards or trigger follow-up actions when a campaign underperforms.

1
# Get all sender accounts associated with the campaign
2
sender_accounts = campaign["campaignAccountIds"]
3

4
stats = actions.execute_tool(
5
    connection_name='heyreach',
6
    identifier='user_123',
7
    tool_name="heyreach_get_overall_stats",
8
    tool_input={
9
        "CampaignIds": [campaign["id"]],
10
        "AccountIds": sender_accounts,
11
    }
12
)
13

14
# Response wraps aggregates under `overallStats` and a per-day breakdown
15
# under `byDayStats` — use `overallStats` for top-line numbers.
16
s = stats.data["overallStats"]
17
print(f"Campaign {campaign['id']} — '{campaign['name']}'")
18
print(f"  Connection requests: {s['connectionsSent']} sent / {s['connectionsAccepted']} accepted")
19
print(f"  Acceptance rate:     {s['connectionAcceptanceRate']:.1%}")
20
print(f"  Messages:            {s['messagesSent']} sent / {s['totalMessageReplies']} replied")
21
print(f"  Reply rate:          {s['messageReplyRate']:.1%}")

LangChain integration

Let an LLM decide which HeyReach tool to call based on natural language. This example builds an agent that can list campaigns, add leads, and surface inbox replies on demand.

1
from langchain_openai import ChatOpenAI
2
from langchain.agents import AgentExecutor, create_openai_tools_agent
3
from langchain_core.prompts import (
4
    ChatPromptTemplate, SystemMessagePromptTemplate,
5
    HumanMessagePromptTemplate, MessagesPlaceholder, PromptTemplate
6
)
7

8
# Load all HeyReach tools in LangChain format. Use page_size=100 so connector tool lists are not truncated.
9
tools = actions.langchain.get_tools(
10
    identifier='user_123',
11
    providers=["HEYREACH"],
12
    page_size=100
13
)
14

15
prompt = ChatPromptTemplate.from_messages([
16
    SystemMessagePromptTemplate(prompt=PromptTemplate(
17
        input_variables=[],
18
        template=(
19
            "You are a LinkedIn outreach assistant with access to HeyReach tools. "
20
            "Use heyreach_get_all_campaigns to find campaigns, heyreach_add_leads_to_campaign "
21
            "to enroll new prospects, heyreach_get_conversations to monitor replies, and "
22
            "heyreach_get_overall_stats to report on performance. Always confirm the campaign "
23
            "and sender account before adding leads."
24
        )
25
    )),
26
    MessagesPlaceholder(variable_name="chat_history", optional=True),
27
    HumanMessagePromptTemplate(prompt=PromptTemplate(
28
        input_variables=["input"], template="{input}"
29
    )),
30
    MessagesPlaceholder(variable_name="agent_scratchpad")
31
])
32

33
llm = ChatOpenAI(model="gpt-4o")
34
agent = create_openai_tools_agent(llm, tools, prompt)
35
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
36

37
result = agent_executor.invoke({
38
    "input": "Show me unread replies from my active LinkedIn campaigns in the last 24 hours, and tell me which campaign has the highest acceptance rate."
39
})
40
print(result["output"])

Setup

Install the SDK

Set your credentials

Create the HeyReach connection

Generate a HeyReach API key

Create a connection in Scalekit

Add a connected account

Authorize a user and make your first call

Tools

Call it

Returns

Check API Key

Inputs

Get All Campaigns

Inputs

Get All LinkedIn Accounts

Inputs

Get All Lists

Inputs

Get Campaign By ID

Inputs

Get Conversations

Inputs

Get Lead

Inputs

Get Leads From List

Inputs

Get Overall Stats

Inputs

Add Leads To Campaign

Inputs

Add Leads To List

Inputs

Create List

Inputs

Pause Campaign

Inputs

Resume Campaign

Inputs

Workflows

Related: other CRM & Sales connectors