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.

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"
}

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