Integrations
Connect and manage workspace integrations — Apollo, Instantly and HubSpot — and import their lead lists into CampaignStack.
Tools (10)
Section titled “Tools (10)”list_integrations
Section titled “list_integrations”Full name: campaignstack_list_integrations
List connected integrations for a workspace (apollo, instantly, clay, hubspot). Returns provider, connection status, and last-tested timestamp. Call this when the user asks what is connected, or before calling a provider-parameterized tool to confirm the integration exists. API keys and webhook secrets are never returned; only a boolean indicating they are set. It does not test the connection right now, the status is from the last attempt. Use campaignstack_connect_apollo, campaignstack_connect_instantly or campaignstack_connect_hubspot to add one.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
connect_apollo
Section titled “connect_apollo”Full name: campaignstack_connect_apollo
Connect an Apollo.io account by providing an API key. Call this when the user gives you an Apollo API key and asks to connect it. Validates the key and stores the integration. Returns success: true when valid, success: false (integrationId still created) when the key fails validation. Refused over a connected-app (chat) connection: point the user at CampaignStack Settings, Integrations instead; an API key can still call this directly. Use campaignstack_list_external_lead_lists with provider “apollo” to browse contact lists after.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | Yes | — | (min length: 10) |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
connect_instantly
Section titled “connect_instantly”Full name: campaignstack_connect_instantly
Connect an Instantly.ai account by providing an API key. Call this when the user gives you that key and asks to connect it. Validates it and stores the integration: success: true when valid, success: false when it fails (integrationId still created). Refused over a connected-app (chat) connection: point the user at CampaignStack Settings, Integrations instead.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | Yes | — | (min length: 10) |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
connect_hubspot
Section titled “connect_hubspot”Full name: campaignstack_connect_hubspot
Connect a HubSpot portal by providing a Private App access token (pat-na1- or pat-eu1- prefix). Call this when the user gives you that token and asks to connect it. Validates the token against the HubSpot CRM API (read ping + write-scope probe) and stores the integration. The private app must have crm.objects.contacts.read and crm.objects.contacts.write scopes; crm.objects.companies.read/write and crm.schemas.contacts.write are optional (company association + source tag). Returns success: true when the token is valid. On failure, errorCode is one of invalid_format, invalid_token, missing_scopes (errorDetail names the scopes), rate_limited, validation, unreachable. Note on missing_scopes: HubSpot reports subscription-tier gating with the same error, naming a scope the portal can never be granted (the Leads object needs Sales Hub Professional/Enterprise). If a scope is ticked in the private app UI but still reported missing, the portal tier is the cause, not the scope set. The token is never echoed back. Refused over a connected-app (chat) connection: point the user at CampaignStack Settings, Integrations instead; an API key can still call this. HubSpot is in beta: not every path is verified against a live portal yet.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | Yes | — | (min length: 10) |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
disconnect_integration
Section titled “disconnect_integration”Full name: campaignstack_disconnect_integration
Disconnect (remove) an integration by provider. Permanently deletes the integration record and its stored credentials. Call this when the user asks to remove or disconnect a provider. It does not undo anything the provider already did with data already sent to it, a lead already added to a sequence or list stays there; it only removes CampaignStack’s stored connection. Valid providers: apollo, instantly, clay, hubspot. Use campaignstack_list_integrations to see which integrations are connected.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | apollo | instantly | clay | hubspot | Yes | — | Integration provider to disconnect |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
list_external_lead_lists
Section titled “list_external_lead_lists”Full name: campaignstack_list_external_lead_lists
List an external provider’s lead lists (provider-parameterized: apollo, instantly, hubspot or clay). Call this when the user needs a real list id, not a name. Not sequences: campaignstack_list_external_sequences covers those. Apollo lists are account labels with cached contact counts; clay lists are the Clay tables the user registered on the Integrations page (no webhook URLs returned). Use the id as sourceId with campaignstack_import_external_leads, or as listId with campaignstack_add_lead_to_external_list (instantly, hubspot and clay only).
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | apollo | instantly | hubspot | clay | Yes | — | Integration provider whose lead lists to list. |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
add_lead_to_external_list
Section titled “add_lead_to_external_list”Full name: campaignstack_add_lead_to_external_list
Add one lead to an external provider’s lead list (provider-parameterized: instantly, hubspot or clay). Call this after campaignstack_list_external_lead_lists has given you a real list id and the user confirms sending this lead there. For clay the target is a registered Clay table: the push goes to the table’s webhook source fire-and-forget (no provider lead id comes back, a campaignstack_dedupe_key field rides along for table-side dedup) and leads with only a LinkedIn URL qualify. Otherwise the lead is created by email on the provider side. Neither starts any outreach, unlike campaignstack_add_lead_to_sequence: the contact just becomes available in the provider (e.g. to attach to a campaign later). Duplicate adds to the same list are idempotent successes (status already_present). Set skipIfInWorkspace to skip leads that already exist anywhere in the provider workspace. Free: no CampaignStack credits. Returns status: added, already_present, skipped_no_email (lead has no email), or error (e.g. INTEGRATION_NOT_CONNECTED, LEAD_NOT_FOUND). Use campaignstack_list_external_lead_lists for list ids. For CampaignStack’s OWN lead lists use campaignstack_add_leads_to_list instead (inside a workflow, the integration:add_to_list node also accepts provider campaignstack).
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | instantly | hubspot | clay | Yes | — | Integration provider that owns the lead list. |
leadId | string | Yes | — | (min length: 1) |
leadSource | global | private | No | — | Lead source table (default: global). Private leads are workspace-scoped CSV imports. |
listId | string | Yes | — | Provider-side lead list id (from campaignstack_list_external_lead_lists). (min length: 1) |
skipIfInWorkspace | boolean | No | — | Skip the lead if its email already exists anywhere in the provider workspace, in any campaign or list. |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
import_external_leads
Section titled “import_external_leads”Full name: campaignstack_import_external_leads
Import every lead of an external provider source into CampaignStack. Call this when the user asks to bring a whole provider list, campaign or portal in. Provenance differs by provider: apollo and instantly (data vendors) land in the shared lead pool; hubspot (the tenant’s own CRM) lands in workspace-scoped private leads. sourceKind picks between a provider lead list (apollo, instantly, hubspot), a provider campaign (instantly only), or the whole portal (hubspot only, sourceId “portal”); ids come from campaignstack_list_external_lead_lists / campaignstack_list_external_sequences. Leads are deduplicated by email and LinkedIn URL, available fields (title, company, phone, location) are mapped, and an optional campaignId lands the leads in that campaign’s default lead list. Long imports keep running server-side; poll campaignstack_get_external_import_progress for status. Not the reverse: campaignstack_add_lead_to_external_list pushes a lead OUT to a provider. Free: no CampaignStack credits.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | apollo | instantly | hubspot | Yes | — | Integration provider to import from. |
sourceKind | list | campaign | portal | Yes | — | Whether sourceId is a provider lead list (apollo, instantly, hubspot), a provider campaign (instantly only), or the whole portal (hubspot only: every contact). |
sourceId | string | Yes | — | Provider-side source id (from campaignstack_list_external_lead_lists or campaignstack_list_external_sequences). Pass “portal” for sourceKind portal. (min length: 1) |
sourceName | string | No | — | Display name for progress tracking. |
campaignId | string | No | — | Optional CampaignStack campaign whose default lead list receives the imported leads. |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
get_external_import_progress
Section titled “get_external_import_progress”Full name: campaignstack_get_external_import_progress
Read the progress of a campaignstack_import_external_leads run: processed / imported counts, status (in_progress, completed, failed) and error message. Call this after starting an import, or when the user asks whether one finished. Returns null when no import was ever started for that provider source; it does not start one itself, use campaignstack_import_external_leads for that.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
provider | apollo | instantly | hubspot | Yes | — | Integration provider of the import. |
sourceId | string | Yes | — | Provider-side source id the import was started with. (min length: 1) |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |
sync_lead_to_hubspot
Section titled “sync_lead_to_hubspot”Full name: campaignstack_sync_lead_to_hubspot
Sync a single lead into the workspace’s connected HubSpot portal (same behavior as the integration:crm_sync workflow node). Call this when the user asks to push one lead into HubSpot now. Many leads: wire the integration:crm_sync node into a workflow instead of looping this tool. Upserts the contact by email (idempotent), optionally associates the lead’s company (when a real domain resolves), and optionally logs an outreach note on the contact’s timeline. lifecycleStage is NEVER sent unless explicitly provided (downgrade risk on existing CRM contacts). Leads without an email cannot be synced (errorCode no_email). Requires a connected HubSpot integration, so use campaignstack_connect_hubspot first. On success returns the HubSpot contactId (plus companyId/noteId when those steps ran) and a degraded[] list for steps that fell back gracefully (e.g. company_upsert, source_property, note). This path is in beta: it is unit-tested but not yet confirmed inside a real portal’s UI, so tell the user to spot-check the first synced contact in HubSpot.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
leadId | string | Yes | — | (min length: 1) |
leadSource | global | private | No | — | Lead source table (defaults to trying global, then private) |
syncCompany | boolean | No | — | Associate the lead’s company when a real domain resolves (default true) |
lifecycleStage | string | No | — | HubSpot lifecyclestage to set (e.g. ‘lead’). NEVER sent unless provided: sending it can downgrade an existing customer contact |
note | object | No | — | Optional outreach note to log on the contact’s HubSpot timeline |
workspaceId | string | No | — | Workspace ID. REQUIRED for a user key (csu_), which spans every workspace you belong to; omitted for a workspace key (cs_), which is bound to one and ignores this argument. campaignstack_whoami reports which kind of key you are holding and, for a user key, the workspaces it can reach. |