LeadIQ connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your LeadIQ credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment.

   Dashboard setup steps

   Register your LeadIQ API key with Scalekit so it stores it securely and injects it into every request. LeadIQ uses API key authentication — there is no redirect URI or OAuth flow.

   1. Get your LeadIQ API key

      • Sign in to LeadIQ and go to Settings → API Keys.
      • Copy the Secret API key value, or click Generate new API key to create one dedicated to this integration.

      

      Store the key securely

      LeadIQ API keys have full account access. Store the key in a secrets manager and never hard-code it in your application source code.

   2. Create a connection in Scalekit

      • In Scalekit dashboard, go to AgentKit → Connections → Create Connection. Find LeadIQ and click Create.
      • Note the Connection name — you will use this as connection_name in your code (e.g., leadiq).
      • Click Save.

   3. Add a connected account

      Connected accounts link a specific user identifier in your system to their LeadIQ API key. Add them via the dashboard for testing, or via the Scalekit API in production.

      Via dashboard (for testing)

      • Open the connection you created and click the Connected Accounts tab → Add account.
      • Fill in:
        • Your User’s ID — a unique identifier for this user in your system (e.g., user_123)
        • API Key — the LeadIQ API key from step 1
      • Click Create Account.

      Via API (for production)

      Node.js

      import { Scalekit } from '@scalekit-sdk/node';
      
      const scalekit = new Scalekit(
        process.env.SCALEKIT_ENV_URL,
        process.env.SCALEKIT_CLIENT_ID,
        process.env.SCALEKIT_CLIENT_SECRET,
      );
      
      // Never hard-code credentials — read from secure storage or user input
      const leadiqApiKey = getUserLeadIQApiKey(); // retrieve from your secure store
      
      await scalekit.actions.upsertConnectedAccount({
        connectionName: 'leadiq',
        identifier: 'user_123',
        credentials: {
          username: leadiqApiKey,
        },
      });

      Python

      import os
      from scalekit import ScalekitClient
      
      scalekit_client = ScalekitClient(
          env_url=os.environ["SCALEKIT_ENV_URL"],
          client_id=os.environ["SCALEKIT_CLIENT_ID"],
          client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
      )
      
      # Never hard-code credentials — read from secure storage or user input
      leadiq_api_key = get_user_leadiq_api_key()  # retrieve from your secure store
      
      scalekit_client.actions.upsert_connected_account(
          connection_name="leadiq",
          identifier="user_123",
          credentials={"username": leadiq_api_key},
      )

      Production usage tip

      In production, call upsert_connected_account (Python) / upsertConnectedAccount (Node.js) when a user connects their LeadIQ account — for example, on an integrations settings page in your app.

What you can do

Connect this agent connector to let your agent:

• Search contacts — look up verified work emails, direct dials, and mobile numbers by LinkedIn URL, email, or name
• Preview before consuming credits — check whether LeadIQ has a work email or phone for a person without spending credits
• Enrich companies — fetch firmographics including industry, employee count, and location by domain or name
• Advanced prospecting — filter contacts by title, seniority, industry, company size, and location; get results flat or grouped by company
• Manage prospect lists — create lists, add contacts, and retrieve saved prospects (requires Prospector plan)
• Monitor quota — check API credit usage, plan limits, and subscription status before making credit-consuming calls

Common workflows

No OAuth flow needed

LeadIQ uses API key auth — there is no authorization link or redirect flow. Once you call upsertConnectedAccount (Node.js) / upsert_connected_account (Python) with your API key, your users can make requests immediately.

Check credit quota before searching

Always check available credits before calling tools that consume them (leadiq_search_people, leadiq_flat_advanced_search, leadiq_grouped_advanced_search).

Node.js

const usage = await actions.executeTool({
  toolName: 'leadiq_get_usage',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {},
});
console.log(usage.data?.usage);

Python

usage = actions.execute_tool(
    tool_name="leadiq_get_usage",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={},
)
print(usage.data)

Preview contact availability before consuming credits

Use leadiq_search_people_preview to check whether LeadIQ has a work email or phone for a person before calling leadiq_search_people. The preview call does not consume credits.

Node.js

const preview = await actions.executeTool({
  toolName: 'leadiq_search_people_preview',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    linkedin_url: 'https://www.linkedin.com/in/janedoe',
  },
});

if (preview.data?.data?.searchPeoplePreview?.hasEmail) {
  // Safe to call leadiq_search_people — credits will be consumed
}

Python

preview = actions.execute_tool(
    tool_name="leadiq_search_people_preview",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={"linkedin_url": "https://www.linkedin.com/in/janedoe"},
)

result = preview.data.get("data", {}).get("searchPeoplePreview", {})
if result.get("hasEmail"):
    # Safe to call leadiq_search_people — credits will be consumed
    pass

Look up a contact by LinkedIn URL, email, or name

Node.js

// By LinkedIn URL (most precise)
const contact = await actions.executeTool({
  toolName: 'leadiq_search_people',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    linkedin_url: 'https://www.linkedin.com/in/janedoe',
    limit: 1,
  },
});

// By name + company
const byName = await actions.executeTool({
  toolName: 'leadiq_search_people',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    first_name: 'Jane',
    last_name: 'Doe',
    company_name: 'Acme Corp',
    limit: 5,
  },
});

Python

# By LinkedIn URL (most precise)
contact = actions.execute_tool(
    tool_name="leadiq_search_people",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "limit": 1,
    },
)

# By name + company
by_name = actions.execute_tool(
    tool_name="leadiq_search_people",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={
        "first_name": "Jane",
        "last_name": "Doe",
        "company_name": "Acme Corp",
        "limit": 5,
    },
)

Enrich a company by domain or name

Node.js

const company = await actions.executeTool({
  toolName: 'leadiq_search_company',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    domain: 'acme.com',
  },
});
console.log(company.data?.data?.searchCompany);

Python

company = actions.execute_tool(
    tool_name="leadiq_search_company",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={"domain": "acme.com"},
)
print(company.data)

Advanced people search with industry and seniority filters

Pass filter objects as Python dicts or JavaScript objects — not JSON-encoded strings.

Node.js

const results = await actions.executeTool({
  toolName: 'leadiq_flat_advanced_search',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    company_filter: {
      industries: ['Software Development'],
      sizes: [{ min: 50, max: 500 }],
    },
    contact_filter: {
      seniorities: ['VP', 'Director'],
    },
    limit: 10,
  },
});
const people = results.data?.data?.flatAdvancedSearch?.people ?? [];

Python

results = actions.execute_tool(
    tool_name="leadiq_flat_advanced_search",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={
        "company_filter": {
            "industries": ["Software Development"],
            "sizes": [{"min": 50, "max": 500}],
        },
        "contact_filter": {
            "seniorities": ["VP", "Director"],
        },
        "limit": 10,
    },
)
people = results.data.get("data", {}).get("flatAdvancedSearch", {}).get("people", [])

Advanced search grouped by company (account-based prospecting)

Returns results organized by company, each with a list of matching contacts. Useful for account-based outreach.

Node.js

const grouped = await actions.executeTool({
  toolName: 'leadiq_grouped_advanced_search',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    company_filter: {
      industries: ['Financial Services'],
      sizes: [{ min: 200, max: 5000 }],
    },
    contact_filter: {
      seniorities: ['Executive', 'VP'],
    },
    limit: 5,            // number of companies
    limit_per_company: 3, // contacts per company
  },
});
const companies = grouped.data?.data?.groupedAdvancedSearch?.companies ?? [];

Python

grouped = actions.execute_tool(
    tool_name="leadiq_grouped_advanced_search",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={
        "company_filter": {
            "industries": ["Financial Services"],
            "sizes": [{"min": 200, "max": 5000}],
        },
        "contact_filter": {
            "seniorities": ["Executive", "VP"],
        },
        "limit": 5,             # number of companies
        "limit_per_company": 3, # contacts per company
    },
)
companies = (
    grouped.data.get("data", {})
    .get("groupedAdvancedSearch", {})
    .get("companies", [])
)

Report incorrect contact data

Help improve LeadIQ data quality by reporting bounced emails or wrong phone numbers.

Node.js

await actions.executeTool({
  toolName: 'leadiq_submit_person_feedback',
  connectionName: 'leadiq',
  identifier: 'user_123',
  toolInput: {
    value: 'jane.doe@acme.com',
    status: 'Invalid',
    type: 'WorkEmail',
    invalid_reason: 'EmailBounceCode550',
  },
});

Python

actions.execute_tool(
    tool_name="leadiq_submit_person_feedback",
    connection_name="leadiq",
    identifier="user_123",
    tool_input={
        "value": "jane.doe@acme.com",
        "status": "Invalid",
        "type": "WorkEmail",
        "invalid_reason": "EmailBounceCode550",
    },
)

Prospect list tools require a paid plan

The leadiq_get_lists, leadiq_get_list, leadiq_create_list, and leadiq_add_prospect_to_list tools require a LeadIQ Prospector plan. On Freemium accounts these tools return a 401 from the prospector service.

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

leadiq_add_prospect_to_list # Add a contact to an existing LeadIQ prospect list. Provide first name, last name, and any known contact details. Use Get Prospect Lists to find the list ID. 13 params ▾

Add a contact to an existing LeadIQ prospect list. Provide first name, last name, and any known contact details. Use Get Prospect Lists to find the list ID.

Name Type Required Description

first_name string required First name of the prospect

last_name string required Last name of the prospect

list_id string required ID of the prospect list to add the contact to

company string optional Current company name of the prospect

company_domain string optional Website domain of the prospect's company

company_industry string optional Industry of the prospect's company

linkedin_url string optional LinkedIn profile URL of the prospect

mobile_phone string optional Mobile phone number of the prospect

notes string optional Internal notes about this prospect

seniority string optional Seniority level of the prospect

title string optional Job title of the prospect

work_email string optional Work email address of the prospect

work_phone string optional Work phone number of the prospect

leadiq_create_list # Create a new prospect list in LeadIQ to organize contacts for outreach campaigns. Returns the created list ID for use with Add Prospect to List. 2 params ▾

Create a new prospect list in LeadIQ to organize contacts for outreach campaigns. Returns the created list ID for use with Add Prospect to List.

Name Type Required Description

name string required Name of the prospect list

description string optional Optional description of the prospect list

leadiq_flat_advanced_search # Search across LeadIQ's full contact database using advanced filters for title, seniority, company, industry, location, and more. Returns a flat list of matching contacts. Consumes credits per result. 6 params ▾

Search across LeadIQ's full contact database using advanced filters for title, seniority, company, industry, location, and more. Returns a flat list of matching contacts. Consumes credits per result.

Name Type Required Description

company_excluded_filter object optional Exclude contacts at companies matching these criteria

company_filter object optional Filter by company attributes including name, domain, industry, size, and location

contact_excluded_filter object optional Exclude contacts matching these criteria

contact_filter object optional Filter contacts by title, seniority, role, location, and more

limit integer optional Maximum number of contacts to return (default 10)

skip integer optional Number of results to skip for pagination (default 0)

leadiq_get_account # Retrieve the current LeadIQ account details including active plans, product subscriptions, billing status, and credit usage (available and used). Use this to check remaining search credits before making enrichment calls. 0 params ▾

Retrieve the current LeadIQ account details including active plans, product subscriptions, billing status, and credit usage (available and used). Use this to check remaining search credits before making enrichment calls.

leadiq_get_list # Retrieve a specific prospect list by ID, including its contacts with name, title, company, email, and LinkedIn URL. Use Get Prospect Lists first to find the list ID. 3 params ▾

Retrieve a specific prospect list by ID, including its contacts with name, title, company, email, and LinkedIn URL. Use Get Prospect Lists first to find the list ID.

Name Type Required Description

id string required ID of the prospect list to retrieve

prospects_cursor string optional Pagination cursor from a previous response to get the next batch of prospects

prospects_limit integer optional Maximum number of prospects to return from the list (default 25)

leadiq_get_lists # Retrieve all prospect lists in the LeadIQ account. Returns list metadata including name, status, and timestamps. Use the returned list IDs with Get Prospect List to fetch contacts. 2 params ▾

Retrieve all prospect lists in the LeadIQ account. Returns list metadata including name, status, and timestamps. Use the returned list IDs with Get Prospect List to fetch contacts.

Name Type Required Description

cursor string optional Pagination cursor from a previous response's nextCursor field

limit integer optional Maximum number of lists to return per page

leadiq_get_prospect # Retrieve a single prospect record by ID, including full contact details: emails, phones, LinkedIn, title, company, and location. 1 param ▾

Retrieve a single prospect record by ID, including full contact details: emails, phones, LinkedIn, title, company, and location.

Name Type Required Description

id string required ID of the prospect to retrieve

leadiq_get_usage # Retrieve API credit usage for the current billing period — plan credit counts, usage caps, trial usage, and subscription status. Use this to monitor quota before making credit-consuming calls. 0 params ▾

Retrieve API credit usage for the current billing period — plan credit counts, usage caps, trial usage, and subscription status. Use this to monitor quota before making credit-consuming calls.

leadiq_grouped_advanced_search # Search LeadIQ's contact database with advanced filters and get results grouped by company. Each result contains a company record with its top matching contacts. Useful for account-based prospecting. Consumes credits per contact returned. 7 params ▾

Search LeadIQ's contact database with advanced filters and get results grouped by company. Each result contains a company record with its top matching contacts. Useful for account-based prospecting. Consumes credits per contact returned.

Name Type Required Description

company_excluded_filter object optional Exclude companies matching these criteria

company_filter object optional Filter by company name, domain, industry, size, location, and more

contact_excluded_filter object optional Exclude contacts matching these criteria

contact_filter object optional Filter contacts by title, seniority, role, location, and more

limit integer optional Maximum number of companies to return (default 10)

limit_per_company integer optional Maximum number of contacts to return per company (default 5)

skip integer optional Number of companies to skip for pagination (default 0)

leadiq_search_company # Search for a company by name, domain, or LinkedIn URL. Returns firmographic data including employee count, industry, headquarters location, and funding information. 5 params ▾

Search for a company by name, domain, or LinkedIn URL. Returns firmographic data including employee count, industry, headquarters location, and funding information.

Name Type Required Description

domain string optional Company website domain

linkedin_id string optional LinkedIn company numeric ID

linkedin_url string optional LinkedIn company page URL

name string optional Company name to search for

strict boolean optional Enable strict matching — only return exact name or domain matches

leadiq_search_people # Search for a person by LinkedIn URL, email, or name + company. At least one of: linkedin_url, email, or first_name+last_name must be provided. Returns verified work emails, direct dials, and current job details. Consumes LeadIQ credits per result. 10 params ▾

Search for a person by LinkedIn URL, email, or name + company. At least one of: linkedin_url, email, or first_name+last_name must be provided. Returns verified work emails, direct dials, and current job details. Consumes LeadIQ credits per result.

Name Type Required Description

company_domain string optional Domain of the person's current company

company_name string optional Current company name of the person

contains_work_contact_info boolean optional Only return results that have at least one work email or work phone

email string optional Known email address of the person

first_name string optional First name of the person to search for

full_name string optional Full name of the person (alternative to first_name + last_name)

last_name string optional Last name of the person to search for

limit integer optional Maximum number of results to return (default 10, max 25)

linkedin_url string optional LinkedIn profile URL of the person

skip integer optional Number of results to skip for pagination (default 0)

leadiq_search_people_preview # Check whether LeadIQ has a work email or phone number for a person without consuming credits. Use this before calling Search People to avoid wasting credits on contacts with no data. 7 params ▾

Check whether LeadIQ has a work email or phone number for a person without consuming credits. Use this before calling Search People to avoid wasting credits on contacts with no data.

Name Type Required Description

company_domain string optional Domain of the person's current company

company_name string optional Current company name of the person

email string optional Known email address of the person

first_name string optional First name of the person

full_name string optional Full name of the person

last_name string optional Last name of the person

linkedin_url string optional LinkedIn profile URL of the person

leadiq_submit_person_feedback # Report incorrect or outdated contact data back to LeadIQ to improve data quality. Mark an email or phone as correct or invalid, and optionally provide a correction or bounce reason. 9 params ▾

Report incorrect or outdated contact data back to LeadIQ to improve data quality. Mark an email or phone as correct or invalid, and optionally provide a correction or bounce reason.

Name Type Required Description

value string required The contact info value being reported (email address or phone number)

company_domain string optional Company domain for additional context

company_name string optional Company name for additional context

invalid_reason string optional Specific bounce or invalidity reason code (for invalid emails)

linkedin_url string optional LinkedIn URL of the person the feedback is about

person_id string optional LeadIQ person ID associated with the contact info

status string optional Whether the contact info is correct or invalid

title string optional Job title of the person at the time the contact info was used

type string optional Type of contact information being reported