ACTION_ID: heyreach_add_leads_to_campaign
NAME: HeyReach: Add Leads to a Campaign
CATEGORY: sheets
CREDITS: 0

Add a lead to a campaign in HeyReach.

================================================================================
PREREQUISITE — USER ACTION REQUIRED
================================================================================

This action only works if the user has connected their HeyReach account
in Floqer. The connection cannot be made via the API or by an AI agent.

The user must do this themselves before this action will run:
  1. Sign in to Floqer at https://app.floqer.com
  2. Open the Connections page from the sidebar
  3. Click HeyReach and complete the OAuth flow

If the user has not connected HeyReach, this action will fail with a
connection / authentication error. Before configuring or running this
action, confirm with the user that the HeyReach connection exists.

INDEX:
  1. Inputs
  2. Outputs
  3. How to configure
  4. Key notes
  5. Where it fits in a workflow
  6. When to use
  7. When not to use

================================================================================
1. INPUTS
================================================================================

campaign_id (dynamicDropdown, required)
  Campaign ID. The campaign to add the lead to. Values from the
  heyReach list.

linkedin_url (url, required)
  LinkedIn URL. LinkedIn profile URL of the lead.

first_name (string, optional)
  First Name.

last_name (string, optional)
  Last Name.

email (email, optional)
  Email.

company_name (string, optional)
  Company Name.

location (string, optional)
  Location.

summary (string, optional)
  Summary.

position (string, optional)
  Position.

about (string, optional)
  About.

custom_fields (jsonArray, optional)
  Custom Fields. `[{name, value}]` for custom merge tags referenced in
  the HeyReach sequence template.

================================================================================
2. OUTPUTS
================================================================================

status (string) — Status. e.g. "completed".

================================================================================
3. HOW TO CONFIGURE
================================================================================

Resolve the campaign list via Get Action Field Options:

  POST /api/v1/workflows/{workflow_id}/sheets/{sheet_id}/actions/{action_instance_id}/options/campaign_id
       (body: {})

Configure Action body:

{
  "inputs": {
    "campaign_id": "<heyreach_campaign_id>",
    "linkedin_url": "{{input.linkedin_url}}",
    "first_name": "{{input.first_name}}",
    "last_name": "{{input.last_name}}",
    "email": "{{input.email}}",
    "company_name": "{{input.company_name}}",
    "position": "{{input.job_title}}",
    "custom_fields": [
      { "name": "personalized_intro", "value": "{{llm_models_1.generated_content}}" }
    ]
  }
}

Field-by-field:
  - campaign_id     HeyReach campaign ID from the `campaign_id` options
                    call.
  - linkedin_url    LinkedIn profile URL — required.
  - first_name / last_name / email /
    company_name / location /
    summary / position / about   Optional lead profile fields.
  - custom_fields   `[{name, value}]` for custom merge tags referenced
                    in the HeyReach sequence template — common slot for
                    AI-generated personalized content from upstream
                    `llm_models`.

================================================================================
4. KEY NOTES
================================================================================

- HeyReach is LinkedIn-first: `linkedin_url` is required (unlike
  the email-based outreach actions).
- `custom_fields` is the slot for AI-generated per-lead content
  from upstream `llm_models` steps — each `name` must match a merge
  tag in the HeyReach sequence template.

================================================================================
5. WHERE IT FITS IN A WORKFLOW
================================================================================

Pattern: linkedin_url discovery -> enrich_person_linkedin_profile ->
llm_models -> heyreach_add_leads_to_campaign.

================================================================================
6. WHEN TO USE
================================================================================

Use heyreach_add_leads_to_campaign to enroll leads in HeyReach
LinkedIn campaigns.

================================================================================
7. WHEN NOT TO USE
================================================================================

Need email-based outreach (Instantly, Lemlist, Smartlead, La Growth Machine,
Reply)
  -> instantly_add_to_campaign, lemlist_add_lead_to_campaign,
     smartleads_add_to_campaign,
     la_growth_machine_add_to_audience,
     reply_add_and_push_to_campaign
     (https://floqer.com/docs/action-detail/<action_id>.txt)

Need AI-generated outreach content
  -> llm_models (upstream of this action; pass the generated content
     via `custom_fields`)
     (https://floqer.com/docs/action-detail/llm_models.txt)

================================================================================

This file is maintained manually. Last updated: 2026-05-01.
Full interactive reference: https://floqer.com/docs/reference
Action catalog: https://floqer.com/docs/action-catalog.txt