HeyReach

Authentication Type: API Key
Description: Integrate with HeyReach for campaign and lead management with LinkedIn outreach automation.

Authentication

To authenticate, you'll need a HeyReach API key. Learn how to get one in the HeyReach help documentation.

API Key Verification

Authentication verification and account management.

Check API Key

Verify the validity of a HeyReach API key and retrieve account details.

Operation Type: Query (Read)

Parameters:

None

Returns:

Empty string response indicating successful authentication

Example Usage:

{}

Campaigns

Campaign management and statistics for HeyReach outreach campaigns.

Get All Campaigns

Retrieve a paginated list of all campaigns in your HeyReach workspace.

Operation Type: Query (Read)

Parameters:

offset number (required): Number of records to skip for pagination
limit number (required): Maximum number of campaigns to return

Returns:

totalCount number: Total number of campaigns in the workspace
items array of objects: Campaign objects with fields:
- id number: Campaign unique identifier
- name string: Campaign name
- status string: Campaign status (e.g. ACTIVE, PAUSED, DRAFT)
- campaignType string (nullable): Type of campaign
- createdAt string (nullable): Creation timestamp
- updatedAt string (nullable): Last updated timestamp
- linkedInAccountIds array of numbers: LinkedIn account IDs used in the campaign

Example Usage:

{
  "offset": 0,
  "limit": 25
}

Get Campaign

Retrieve details of a specific HeyReach campaign by its numeric ID.

Operation Type: Query (Read)

Parameters:

id number (required): Numeric campaign ID to retrieve

Returns:

id number: Campaign unique identifier
name string: Campaign name
status string: Campaign status
campaignType string (nullable): Type of campaign
createdAt string (nullable): Creation timestamp
updatedAt string (nullable): Last updated timestamp
linkedInAccountIds array of numbers: LinkedIn account IDs used in the campaign

Example Usage:

{
  "id": 123456
}

Create Campaign

Create a new LinkedIn outreach campaign in HeyReach with optional LinkedIn account and campaign type configuration.

Operation Type: Mutation (Write)

Parameters:

name string (required): Name for the new campaign
linkedInAccountIds array of numbers (nullable): LinkedIn account IDs to associate with the campaign
campaignType string (nullable): Type of campaign to create

Returns:

Created campaign object (same structure as Get Campaign response)

Example Usage:

{
  "name": "Q1 2025 LinkedIn Outreach",
  "linkedInAccountIds": [789, 790],
  "campaignType": "OUTREACH"
}

Add Leads to Campaign

Add one or more leads to a specific HeyReach campaign.

Operation Type: Mutation (Write)

Parameters:

campaignId number (required): The campaign ID to add leads to
accountLeadPairs array of objects (required): Array of LinkedIn account and lead pairs
- linkedInAccountId number (nullable): LinkedIn account ID of the sender
- lead object (required): Lead details
  - firstName string (required): Lead first name
  - lastName string (required): Lead last name
  - location string (nullable): Lead location
  - summary string (nullable): Lead summary
  - companyName string (nullable): Lead company name
  - position string (nullable): Lead position or job title
  - about string (nullable): Lead about/bio section
  - emailAddress string (nullable): Lead email address
  - customUserFields array of objects (nullable): List of custom field key-value pairs
    - name string: Custom field name
    - value string: Custom field value
  - profileUrl string (required): LinkedIn profile URL for the lead

Returns:

addedLeadsCount number: Number of leads successfully added
updatedLeadsCount number: Number of leads updated (profileUrl match)
failedLeadsCount number: Number of leads that failed to add or update

Example Usage:

{
  "campaignId": 123456,
  "accountLeadPairs": [
    {
      "linkedInAccountId": 789,
      "lead": {
        "firstName": "John",
        "lastName": "Doe",
        "location": "San Francisco, CA",
        "summary": "Software Engineer at Tech Co",
        "companyName": "Tech Co",
        "position": "Senior Software Engineer",
        "about": "Passionate about building scalable systems",
        "emailAddress": "john.doe@techco.com",
        "customUserFields": [
          { "name": "source", "value": "linkedin" },
          { "name": "priority", "value": "high" }
        ],
        "profileUrl": "https://www.linkedin.com/in/johndoe"
      }
    }
  ]
}

Get Overall Statistics

Fetch overall statistics for HeyReach accounts and campaigns within a date range. Account IDs are optional - if not provided, stats for all accounts will be returned.

Operation Type: Query (Read)

Parameters:

accountIds array of numbers (nullable): Array of HeyReach account IDs (optional; null or empty array = all accounts)
campaignIds array of numbers (nullable): Array of campaign IDs (optional; null or empty array = all campaigns)
startDate string (required): Start date in ISO datetime format (UTC, inclusive)
endDate string (required): End date in ISO datetime format (UTC, inclusive)

Returns:

byDayStats object (nullable): Statistics grouped by date (ISO date string keys)
- profileViews number (nullable): Profile views count
- postLikes number (nullable): Post likes count
- follows number (nullable): Follows count
- messagesSent number (nullable): Messages sent count
- totalMessageStarted number (nullable): Total messages started
- totalMessageReplies number (nullable): Total message replies
- connectionsSent number (nullable): Connection requests sent
- connectionsAccepted number (nullable): Connections accepted
- messageReplyRate number (nullable): Message reply rate percentage
- connectionAcceptanceRate number (nullable): Connection acceptance rate percentage
overallStats object (nullable): Aggregated statistics for the entire date range (same structure as byDayStats)

Example Usage:

{
  "accountIds": [1234, 5678],
  "campaignIds": [101, 102],
  "startDate": "2024-12-01T00:00:00.000Z",
  "endDate": "2024-12-07T23:59:59.999Z"
}

Leads

Retrieve lead information from HeyReach campaigns.

Get Leads

Retrieve a paginated list of leads from HeyReach, optionally filtered by campaign.

Operation Type: Query (Read)

Parameters:

campaignId number (nullable): Filter leads by campaign ID; omit to return leads across all campaigns
offset number (required): Number of records to skip for pagination
limit number (required): Maximum number of leads to return

Returns:

totalCount number: Total number of leads matching the query
items array of objects: Lead objects with fields:
- id number: Lead unique identifier
- firstName string: Lead first name
- lastName string: Lead last name
- profileUrl string: LinkedIn profile URL
- emailAddress string (nullable): Lead email address
- companyName string (nullable): Lead company name
- position string (nullable): Lead job title or position
- location string (nullable): Lead geographic location
- summary string (nullable): LinkedIn headline or summary
- about string (nullable): LinkedIn about section
- status string (nullable): Lead status in the campaign
- campaignId number (nullable): Campaign ID this lead belongs to
- customUserFields array of objects (nullable): Custom field key-value pairs
  - name string: Field name
  - value string: Field value

Example Usage:

{
  "campaignId": 123456,
  "offset": 0,
  "limit": 50
}

Get Lead

Retrieve detailed information about a specific HeyReach lead by its numeric ID.

Operation Type: Query (Read)

Parameters:

id number (required): Numeric lead ID to retrieve

Returns:

Lead object (same structure as individual items in Get Leads response)

Example Usage:

{
  "id": 987654
}

Inbox

Manage LinkedIn conversations and messages through HeyReach.

Get Conversations

Retrieve LinkedIn inbox conversations from HeyReach campaigns with message history and lead details.

Operation Type: Query (Read)

Parameters:

campaignId number (nullable): Filter conversations by campaign ID
page number (nullable): Page number for pagination (default: 1)
pageSize number (nullable): Number of conversations per page (default: 25)

Returns:

conversations array of objects: List of inbox conversations
- leadId number: Lead identifier
- leadName string (nullable): Lead full name
- profileUrl string (nullable): LinkedIn profile URL
- messages array of objects (nullable): Conversation messages
  - text string (nullable): Message content
  - sentAt string (nullable): Timestamp when message was sent
  - isIncoming boolean: Whether message was received (true) or sent (false)

Example Usage:

{
  "campaignId": 123456,
  "page": 1,
  "pageSize": 50
}

Send Message

Send a LinkedIn message to a lead through HeyReach.

Operation Type: Mutation (Write)

Parameters:

campaignId number (required): Campaign ID containing the lead
leadProfileUrl string (required): LinkedIn profile URL of the lead to message
message string (required): Message content to send

Returns:

success boolean: Whether the message was sent successfully
messageId string (nullable): Identifier for the sent message

Example Usage:

{
  "campaignId": 123456,
  "leadProfileUrl": "https://www.linkedin.com/in/johndoe",
  "message": "Hi John, I wanted to follow up on our previous conversation about your company's growth plans."
}

Common Use Cases

Lead Management:

Import leads from external sources into HeyReach campaigns
Bulk upload prospects with LinkedIn profile information
Track lead addition success and failure rates

Campaign Analytics:

Monitor campaign performance across date ranges
Compare statistics between different accounts and campaigns
Track engagement metrics like connection acceptance and message reply rates

Account Verification:

Validate API key credentials before performing operations
Confirm account access and permissions