# HeyReach

> Integrate with HeyReach for campaign and lead management with LinkedIn outreach automation.

Source: https://cotera.co/docs/reference/tools/individual-tools/hey-reach

---

**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](https://help.heyreach.io/en/articles/12504692-how-to-integrate-n8n-with-heyreach).

***

## 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:**

```json
{}
```

***

## 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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