Connect Lusha to AI Agents: Automate lead search and sales intel

You want to connect Lusha to an AI agent so your system can autonomously prospect leads, enrich firmographic data, and score buying signals based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Lusha integration from scratch.

Giving a Large Language Model (LLM) read and write access to your Lusha instance requires strict operational boundaries. You cannot afford an agent hallucinating API payloads that accidentally burn through your entire monthly credit balance in minutes. If your team uses ChatGPT, check out our guide on connecting Lusha to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Lusha to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them safely to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Lusha, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex sales intelligence workflows. For a broader look at this design pattern, read our guide on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. Direct API tools (one tool per raw Lusha endpoint) push provider quirks into the LLM's context window. The model has to remember Lusha's exact pagination cursors, how to structure nested filter arrays, and the difference between legacy V2 and modern V3 endpoints. Every one of those quirks is a hallucination waiting to happen.

A unified tool layer abstracts Lusha's complexity behind deterministic schemas. Your agent sees lusha_contacts_search_and_enrich, list_all_lusha_contacts, and lusha_companies_enrich. That gives you concrete safety wins:

1. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments (like missing required prospecting filters) are rejected before they hit Lusha, so a broken tool call fails fast instead of burning an API request.
2. Normalized auth and pagination. The agent never has to think about API keys or cursor logic. Truto handles the proxying, authentication, and query parameter processing automatically.
3. Smaller attack surface. The LLM only chooses from stable function names and never invents undocumented JSON payloads.

The Engineering Reality of the Lusha API

Giving an LLM access to external data sounds simple in a prototype. In production against a specialized data provider like Lusha, standard REST assumptions collapse. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The API Credit Economy

Unlike standard CRUD APIs where requests are virtually free until you hit a rate limit, Lusha operates on a strict credit economy. Calling a search endpoint that returns non-PII previews is often free or low-cost, but calling an enrichment endpoint that reveals emails and phone numbers deducts credits per matched signal.

If you hand an AI agent a generic enrich_contact tool without safeguards, a looping agent might try to enrich 10,000 leads to find a specific job title, draining thousands of dollars in credits. You have to restrict the agent to preview endpoints for searching, and only allow enrichment on highly qualified subsets.

Asynchronous Enrichment Jobs

Not all Lusha enrichment happens in real-time. Certain endpoints, like the bulk contact enrichment process, return an asynchronous job ID rather than immediate data. The caller is expected to parse a retryAfter value and poll a separate endpoint (get_single_lusha_contact_enrich_job_by_id) until the status changes from processing to complete.

Standard LLMs are terrible at handling asynchronous polling loops. They often ignore retryAfter directives and aggressively call the endpoint in a tight loop, leading to rate limits. Your tool layer must either abstract this polling away from the agent, or provide explicitly constrained tools that force the agent to wait.

Strict Filter Dependencies

Lusha's prospecting endpoints require highly specific filter taxonomies. You cannot simply pass {"location": "New York"}. You often have to query a filter endpoint first (list_all_lusha_contact_prospecting_filters) to get the exact accepted taxonomy for regions, seniorities, or departments, and some filters require a minimum string length (e.g., 2-256 characters) to prevent database-crushing wildcard queries. If an agent guesses a filter format, Lusha will return a 400 Bad Request.

Available AI Tools for Lusha

Truto provides heavily typed, schema-validated tools for Lusha via the /tools endpoint. Here are the highest-leverage tools for building autonomous sales intelligence agents.

lusha_contacts_search_and_enrich

Finds up to 100 Lusha contacts by exact identifier (LinkedIn URL, email, or full name plus company) and reveals their full data in one call. This combines search and enrichment to avoid asynchronous polling when you already know exactly who you are looking for.

Contextual usage notes: This tool deducts credits for the search and per revealed field. Only give this to an agent when it has a high-confidence target list.

"I have a list of 5 executives from Acme Corp. Use their LinkedIn URLs to find and enrich their profiles, returning their direct phone numbers and verified emails."

list_all_lusha_contacts

Prospects Lusha contacts by contact and company filters (title, seniority, department, location). Returns non-PII previews (names, job titles, companies, locations) and indicators of what data can be revealed.

Contextual usage notes: This is your primary discovery tool. Because it only returns previews, it is much safer for the agent to use in broad searches without burning heavy enrichment credits.

"Search for VP of Sales candidates located in Austin, Texas working at companies in the SaaS industry. Return the list of preview profiles."

lusha_companies_enrich

Enriches up to 100 Lusha companies by ID to reveal firmographics, technologies used, funding rounds, social links, and open jobs.

Contextual usage notes: Premium fields (competitors, intent, parent companies) must be explicitly requested. Credits are charged per company revealed, plus additional costs per premium field.

"Take this list of 10 target account IDs and enrich their company profiles. Extract their current technology stack and latest funding rounds."

lusha_contacts_signal_score

Scores up to 100 contacts by their active buying signals on a scale from 0 to 1. This uses Lusha's intent engine to determine if a contact is actively researching solutions in your space.

Contextual usage notes: Incredibly powerful for account prioritization. The agent can use this tool to filter a massive list of prospects down to only those showing immediate buying intent before spending credits on full enrichment.

"Evaluate these 50 contacts from our CRM and score their active buying signals. Sort the output so I can see the highest intent contacts first."

list_all_lusha_account_usage

Retrieves a snapshot of your Lusha account usage, including credit balances, rate limits, and plan details.

Contextual usage notes: Essential for autonomous agents. You should instruct your agent to call this tool before running large enrichment batches to ensure it has enough credits to complete the job.

"Check our current Lusha credit balance. If we have more than 500 credits remaining, proceed with the bulk enrichment job."

get_single_lusha_contact_enrich_job_by_id

Polls an asynchronous Lusha contacts enrichment job. Returns the job status, contacts processed, and credits charged.

Contextual usage notes: When the agent triggers a large bulk enrich job, it receives a jobId and a retryAfter integer. The agent must use this tool to check the status, pausing execution until the job completes.

"Check the status of enrichment job ID 'job_89234'. If it is still processing, wait and tell me how many seconds are left before the next retry."

For a complete list of all Lusha endpoints and their JSON schemas, visit the Lusha integration page.

Workflows in Action

AI agents shine when chaining multiple Lusha tools together to execute complex, multi-step sales operations. Here are real-world examples of how agents orchestrate these tools.

Scenario 1: Autonomous High-Intent Prospecting

User Prompt:

"Check our Lusha credit balance. If we have enough credits, prospect for Directors of IT in London at companies with over 500 employees. Score their buying intent, and fully enrich the profiles of the top 3 highest-scoring contacts."

Agent Execution Steps:

1. Calls list_all_lusha_account_usage to verify the credit balance is sufficient for prospecting and enrichment.
2. Calls list_all_lusha_contacts using filters for "Director of IT", "London", and "500+ employees" to pull non-PII previews.
3. Extracts the IDs from the previews and calls lusha_contacts_signal_score to evaluate active buying intent.
4. Sorts the results internally, selects the top 3 IDs, and calls lusha_contacts_search_and_enrich to spend credits revealing their verified emails and phone numbers.

What the user gets: A highly curated, ready-to-contact list of the three best IT Director prospects in London showing active buying intent, while ensuring the account budget was protected.

Scenario 2: Account-Based Marketing (ABM) Expansion

User Prompt:

"Take our list of top 5 current customers. Enrich their company profiles to find out what technologies they use. Then, find 10 lookalike companies with similar firmographics and score their current intent signals."

Agent Execution Steps:

1. Calls lusha_companies_enrich passing the 5 customer domains to pull full firmographics and technology stacks.
2. Analyzes the returned tech stacks and firmographics to establish an Ideal Customer Profile (ICP).
3. Calls lusha_companies_lookalikes using the 5 domains as seed companies to generate a list of similar businesses.
4. Extracts the IDs of the 10 best lookalikes and calls lusha_companies_signal_score to check if they are currently researching relevant topics.

What the user gets: A strategic ABM expansion list featuring net-new target accounts that mirror your best customers, complete with real-time intent data to prioritize outreach.

Building Multi-Step Workflows

To build these workflows, you need to fetch the tools from Truto and bind them to your agent. This approach works with any modern AI framework - whether you use LangChain, CrewAI, or the Vercel AI SDK.

Truto provides a generic TrutoToolManager via the truto-langchainjs-toolset SDK, which parses the proxy API definitions and registers them as native tools.

Fetching and Binding Tools

Here is how you inject Lusha tools into a LangChain agent:

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runLushaAgent() {
  // 1. Initialize the Truto Tool Manager with your Integrated Account ID
  const toolManager = new TrutoToolManager({
    integratedAccountId: process.env.LUSHA_INTEGRATED_ACCOUNT_ID,
    trutoApiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch the dynamically generated tools for Lusha
  const tools = await toolManager.getTools();
 
  // 3. Initialize the LLM (e.g., GPT-4o)
  const llm = new ChatOpenAI({
    model: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Create the agent prompt
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite sales operations assistant. You manage lead enrichment and prospecting via Lusha. Always check credit balances before bulk enriching."],
    ["placeholder", "{chat_history}"],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Bind tools and create the executor
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
  });
 
  // 6. Execute the workflow
  const result = await agentExecutor.invoke({
    input: "Check our Lusha credit balance. If we have over 100 credits, prospect for CTOs in Chicago and enrich the top result.",
  });
 
  console.log(result.output);
}

Handling Lusha Rate Limits

Autonomous agents operate at machine speed. When executing multi-step workflows, your agent will eventually hit Lusha's API rate limits.

Crucial Architectural Note: Truto does not automatically retry, throttle, or absorb rate limit errors. When the upstream Lusha API returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset).

The caller (your agent framework or integration code) is strictly responsible for implementing retry and backoff logic.

sequenceDiagram
  participant Agent as AI Agent
  participant Truto as Truto Proxy
  participant Lusha as Lusha API
  
  Agent->>Truto: Call lusha_contacts_enrich (Batch 1)
  Truto->>Lusha: POST /v3/contacts/enrich
  Lusha-->>Truto: 200 OK
  Truto-->>Agent: 200 OK<br>ratelimit-remaining: 0
  
  Agent->>Truto: Call lusha_contacts_enrich (Batch 2)
  Truto->>Lusha: POST /v3/contacts/enrich
  Lusha-->>Truto: 429 Too Many Requests
  Truto-->>Agent: 429 Error<br>ratelimit-reset: 60
  
  Note over Agent: Agent intercepts 429.<br>Reads ratelimit-reset header.<br>Pauses execution for 60s.
  
  Agent->>Truto: Retry lusha_contacts_enrich (Batch 2)
  Truto->>Lusha: POST /v3/contacts/enrich
  Lusha-->>Truto: 200 OK
  Truto-->>Agent: 200 OK

To handle this in Node.js when intercepting tool calls, you must inspect the error headers. If you receive a 429, extract the ratelimit-reset header (which defines the time in seconds until the quota refreshes) and pause the agent's execution loop before allowing it to retry the tool call.

Abstracting the Integration Layer

Building an AI agent that can autonomously navigate Lusha's credit economy, asynchronous enrichment polling, and strict filter dependencies is a serious engineering task. If you hand-roll the integration, you own the schemas, the rate limit handling, the pagination normalization, and the OAuth/API key lifecycle.

By routing your agent through a unified tool layer, you remove integration code from your repository. Truto provides heavily typed, LLM-ready functions that keep your agent focused on reasoning rather than parsing undocumented JSON responses. Your agent executes sales operations reliably, respects API constraints, and scales seamlessly.