HeyReach API: Documented Endpoints, Auth, Webhooks and Integrations

The HeyReach API is a REST API that you authenticate with an X-API-KEY header and a per-workspace key, limited to 300 requests a minute. The documented endpoints we could read cover key checks and the full campaign lifecycle: create a draft, set the sequence, schedule and senders, add leads 100 at a time, start, pause and resume. Webhooks, an MCP server and native integrations with Instantly, Smartlead, Clay and HubSpot sit around it, but parts of the docs (the base URL, most non-campaign endpoints, the webhook event list) were not readable to us, and we say where.

Some tool links here are affiliate links (disclosure). You need a workspace to get a key: start a HeyReach trial (HeyReach says 14 days, 3 LinkedIn accounts, no card). For pricing, features and weaknesses of the product as a whole, read our HeyReach review.

Nerdy Joe is a certified Apollo.io Managed Services Partner and a PlusVibe Certified Silver Partner, and we are a HeyReach affiliate. We did not call the HeyReach API for this guide. Everything below comes from HeyReach's Postman docs, help center and blog, checked November 11, 2026.

HeyReach API quick facts

Authentication: the X-API-KEY header

HeyReach's docs say to add the X-API-KEY request header to every request, with your key as the value. There is no OAuth flow and no bearer token for the public API.

To get a key, HeyReach's help center says to open Integrations in your workspace, choose HeyReach API, then Get API Key. Keys are per workspace, so an agency with ten client workspaces holds ten keys, and a key from one workspace will not see another workspace's campaigns.

The docs say keys do not expire, but you can delete or deactivate them. Treat a key like a password: anyone holding it can start campaigns on real LinkedIn accounts.

Test your key

The documented test is a GET request to /api/public/auth/CheckApiKey. A 200 response means the key works.

curl -X GET "<BASE_URL>/api/public/auth/CheckApiKey" \
  -H "X-API-KEY: YOUR_API_KEY"

This snippet is our illustration, assembled from the documented path and header. <BASE_URL> is a placeholder on purpose: the docs feed we read showed paths with an empty host variable, so take the host from HeyReach's Postman documentation and not from a third-party blog.

Rate limits

HeyReach's docs state one limit: a maximum of 300 requests per minute, and requests over it get a 429 status code and an error. The limit is shared across all requests on the key, not counted per endpoint.

The docs we read do not describe a Retry-After header, a daily quota or per-plan tiers, so we cannot confirm any of those. Build a simple backoff on 429 and you are covered either way.

Add-leads calls take up to 100 leads each, so 300 requests a minute is rarely the constraint. The bottleneck is what each LinkedIn account can send, which our HeyReach pricing guide covers in the cost-per-sender math.

Documented endpoints

These are the endpoints we could read in HeyReach's Postman docs: the Authentication and Campaigns folders. The feed was cut off after the last campaign endpoint, so this is a floor and not the full API.

HeyReach's April 2026 blog post on its Campaign API also names a GET /api/public/campaign/GetCampaignSequence endpoint for reading a campaign's sequence. We did not see it in the part of the Postman feed we could read, so confirm it there.

Building a campaign by API

HeyReach's Campaign API post describes the order: Create, then UpdateSettings, UpdateSequence, UpdateAccounts and UpdateSchedule, then StartCampaign. The campaign stays in DRAFT until you start it, which gives you a natural review point.

The documented constraints worth knowing before you write code:

• Campaign name: 1 to 50 characters.
• Sender accounts: 1 to 100 LinkedIn account IDs per campaign.
• Editable statuses: HeyReach lists DRAFT, SCHEDULED, ACTIVE, PAUSED and COMPLETED, and says only DRAFT, SCHEDULED and PAUSED campaigns can be updated.
• Replace, not patch: UpdateSequence fully replaces the sequence, UpdateAccounts replaces the full sender list, and omitted exclusion fields in UpdateSettings reset to defaults. Send the complete object every time.
• Message lengths (per the blog post): connection request notes up to 300 characters, messages up to 8,000, InMail subject up to 200 and body up to 1,900.

Check field names against the Postman docs before you build, since a blog post is not a reference.

Adding leads

Both add-leads endpoints accept up to 100 leads per request. The V2 version returns counts of leads added, updated and failed, which makes it the better choice for any sync you need to audit.

Custom fields go in as customUserFields, and the docs say the names must use only letters, numbers or underscores. A field named "First Line" with a space will fail; "first_line" will not.

One behavior to plan for: HeyReach's Clay article says that when leads arrive without a named LinkedIn account, they are randomly assigned to the campaign's senders. If a specific rep must own specific accounts, pass the LinkedIn account with the lead.

What exists but we could not read endpoint by endpoint

HeyReach's own pages confirm more API areas than the two folders above. We could not read their paths, so we list the areas and not the endpoints.

Two documented gaps: HeyReach says email credits cannot be used through API calls, and voice note endpoints are "coming in v2". HeyReach also has a CLI ("Everything you'd do in the HeyReach dashboard, now scriptable"), but its install commands and command list were not readable to us.

If you want to drive HeyReach from Claude or another AI client and skip writing HTTP calls, the HeyReach MCP server exposes campaign tools over the same account.

Webhooks

Webhooks push events out of HeyReach so you do not have to poll. HeyReach's help article gives these setup steps:

1. Open Integrations from your workspace settings.
2. Go to Webhooks and click "View and Create".
3. Set a name, the webhook URL, the campaigns it applies to and the event type.
4. Click "Create Webhook". It goes live immediately, and a toggle turns it off and on.

You can scope a webhook to specific campaigns. HeyReach's own example use is pushing leads who did not accept a connection request to Instantly or Smartlead for email follow-up.

What we could and could not confirm about events

HeyReach keeps its full webhook documentation in a Notion page that our tools could not read. So we will not publish a complete event list, a payload schema or anything on retries and signing. This is what HeyReach's own readable pages name:

Not confirmed: the full list of event types, exact payload field names, whether failed deliveries are retried, whether payloads are signed, and any webhook limits. HeyReach's Login API post says a webhook for LinkedIn login completion is "on the roadmap" as of July 2026.

If your build depends on a specific event, create a test webhook pointed at a request catcher during the trial and inspect what arrives before you commit. That is a five minute check and it replaces guessing.

Native integrations

HeyReach uses the word "native" for four integrations. Everything else connects with an API key through an automation platform.

Three things to know before you rely on these.

White label accounts lose the Instantly and Smartlead integrations. HeyReach's help articles say both integrations, and the "Add to Instantly" and "Add to Smartlead" steps, are not available to whitelabel users. An agency that white labels HeyReach and still wants email follow-up has to build that handoff with webhooks or the API.

HubSpot is one-way. Data flows from HeyReach to HubSpot only, triggers apply across the whole workspace, and each agency workspace needs its own HubSpot connection. HeyReach lists no native Salesforce or Pipedrive integration, and no lemlist integration.

HeyReach does not send email. Its multichannel story depends on a second tool. If you are choosing that tool, our Instantly review and Smartlead review cover both, and you can try Instantly or Smartlead alongside a HeyReach trial. We are affiliates of both, not partners.

HeyReach's integration directory listed 33 tools when we read it. We did not read the setup articles for most of the others, so we do not describe them here.

The LinkedIn caution for API users

An API makes it easy to push volume, so this matters more here than in the app. LinkedIn's User Agreement restricts bots and other automated methods for adding contacts and sending messages, and LinkedIn's help center has a page titled Prohibited software and extensions. Our tools could not open LinkedIn's pages, so we paraphrase and link them and do not quote them.

HeyReach itself says LinkedIn's User Agreement bans software that automates connecting and messaging, and states on its site that it is not associated with or endorsed by LinkedIn. HeyReach says its per-sender limits and dedicated proxies reduce the risk of restriction. No vendor can remove that risk, and HeyReach's terms place the consequences of third-party platform action on the customer.

The practical point for developers: the API does not raise what a LinkedIn account can send. HeyReach says daily limits are set per sender and shared across that sender's campaigns. Loading 5,000 leads through the API queues them; it does not send them faster.

Our guide on whether HeyReach is safe goes through the limits and the March 2026 LinkedIn action HeyReach reported.

Honest limits of the HeyReach API

• Docs live in three places. API reference in Postman, webhook docs in Notion, how-to articles in the help center. Some help articles are dated 2024 or early 2025.
• The base URL was not readable in the docs feed we fetched. Copy it from the Postman docs yourself.
• We could read only two endpoint folders. Inbox, list, stats, webhook, LinkedIn account and blacklist endpoints exist per HeyReach's pages, but we could not verify their paths.
• Updates replace whole objects. Sequence, sender list and schedule updates are full replacements, and omitted exclusion fields reset.
• ACTIVE campaigns cannot be edited. HeyReach says only DRAFT, SCHEDULED and PAUSED campaigns can be updated.
• No email credits or voice notes by API today, per HeyReach.
• Webhook reliability details are not confirmed. Retries, signing and payload schema were not readable.
• Keys are per workspace. Multi-client setups need key management on your side.
• No SDK is mentioned in the pages we read. Plan on plain HTTP calls, the n8n nodes or the CLI.

The full HeyReach review puts these next to the product's wider strengths and weaknesses, including the plan differences that affect API users (Agency and Unlimited plans require your own proxies).

Who the HeyReach API fits

• Best for: agencies and GTM engineers who run many LinkedIn senders and want to load leads from Clay, a CRM or their own scripts into campaigns without touching the app.
• Best for: teams building a LinkedIn to email handoff with Instantly or Smartlead, where the native integrations or a webhook do most of the work.
• Not ideal for: teams that need a single developer portal with complete, versioned reference docs for every endpoint.
• Not ideal for: white label agencies that expected the Instantly and Smartlead integrations out of the box.

If lead sourcing is the part you are still solving, our Apollo vs Clay comparison covers the two most common sources feeding these campaigns, and our guide to email and LinkedIn outreach for agencies covers how the channels fit together.

Final take

The HeyReach API is simple where it is documented: one header, one rate limit, and a clear set of campaign endpoints that take a campaign from draft to live and feed it leads 100 at a time. It is included on every paid plan, which is a real point in its favor at $79 per sender per month on Growth, as of November 2026.

The weak spot is documentation, not capability. The base URL, the non-campaign endpoints and the webhook event list were not readable to us, so budget an hour in the Postman and Notion docs before you estimate a build.

The cheapest way to settle the open questions is to test them. Open a HeyReach trial, generate a key, run CheckApiKey, create a draft campaign and point a test webhook at a request catcher. If it does what your workflow needs, pick a HeyReach plan that matches your sender count.

For plans, features, safety and alternatives in one place, read the complete HeyReach review. When you are ready to build, get your HeyReach API key.

Rather not build the list yourself?

Nerdy Joe is owned by Agency Growth Partners (AGP). AGP builds verified lead lists and runs outbound for agencies, including the lead loading and handoff work described above. If you would rather hand it off, book a call with David.

Disclosure: My relationship with Instantly is that of an independent party. I do not hold any position, nor do I have the power to form binding agreements or act on behalf of Instantly. My earnings are derived from referral compensations provided by Instantly. The views I share are solely mine and should not be seen as official statements, promises, or representations of Instantly, or any related entities or personnel.

Sources

• HeyReach API documentation (Postman): https://documenter.getpostman.com/view/23808049/2sA2xb5F75
• HeyReach API documentation data feed: https://documenter.gw.postman.com/api/collections/23808049/2sA2xb5F75?segregateAuth=true&versionTag=latest
• HeyReach blog, Campaign API (April 21, 2026): https://www.heyreach.io/blog/campaign-api
• HeyReach help, webhooks: https://help.heyreach.io/en/articles/9877965-webhooks
• HeyReach webhooks documentation (Notion, not readable to us): https://www.notion.so/howitzer/HeyReach-Webhooks-Documentation-400c53b3aa8743d085937419bccfe276
• HeyReach blog, handling replies with n8n (July 14, 2026): https://www.heyreach.io/blog/handle-heyreach-replies-with-n8n
• HeyReach blog, Zapier integration: https://www.heyreach.io/blog/zapier-integration
• HeyReach help, Zapier: https://help.heyreach.io/en/articles/9892856-push-leads-and-conversations-to-your-crm-via-zapier
• HeyReach help, n8n integration: https://help.heyreach.io/en/articles/12504692-how-to-integrate-heyreach-with-n8n
• HeyReach help, Instantly integration: https://help.heyreach.io/en/articles/12855883-how-to-integrate-heyreach-with-instantly
• HeyReach help, Smartlead integration: https://help.heyreach.io/en/articles/13035892-how-to-integrate-heyreach-with-smartlead
• HeyReach help, Clay integration: https://help.heyreach.io/en/articles/9910966-how-to-integrate-heyreach-with-clay
• HeyReach help, HubSpot integration: https://help.heyreach.io/en/articles/14891660-how-to-integrate-heyreach-with-hubspot
• HeyReach help, Make integration: https://help.heyreach.io/en/articles/11677681-how-to-integrate-heyreach-with-make
• HeyReach help, custom variables: https://help.heyreach.io/en/articles/9879182-how-to-import-and-use-custom-variables
• HeyReach help, sender rotation: https://help.heyreach.io/en/articles/9897768-multiple-linkedin-senders-in-one-campaign-sender-rotation
• HeyReach blog, Login API: https://www.heyreach.io/blog/linkedin-login-via-api
• HeyReach blog, Blacklist: https://www.heyreach.io/blog/blacklist-is-live
• HeyReach blog, LinkedIn company page removal: https://www.heyreach.io/blog/heyreach-ban
• HeyReach CLI: https://www.heyreach.io/cli
• HeyReach integration directory: https://www.heyreach.io/integration
• HeyReach multichannel page: https://www.heyreach.io/multichannel-outreach
• HeyReach pricing: https://www.heyreach.io/pricing
• HeyReach terms of service: https://www.heyreach.io/terms-of-service
• LinkedIn User Agreement (linked, not readable to our tools): https://www.linkedin.com/legal/user-agreement
• LinkedIn Help, Prohibited software and extensions (linked, not readable to our tools): https://www.linkedin.com/help/linkedin/answer/a1341387