Connect LeadIQ to AI Agents: Build Targeted Lists and Enrich Leads

You want to connect LeadIQ to an AI agent so your system can autonomously build targeted account lists, enrich inbound leads, and identify key decision makers based on specific firmographic criteria. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom LeadIQ integration from scratch.

Giving a Large Language Model (LLM) read and write access to a B2B contact database like LeadIQ is an engineering headache. If you expose raw endpoints to an LLM, you risk the agent burning through API credits, hitting pagination limits, and hallucinating search parameters. If your team uses ChatGPT, check out our guide on connecting LeadIQ to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting LeadIQ to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for LeadIQ, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex prospecting workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the LeadIQ API

Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production against complex B2B data systems, this approach collapses.

LeadIQ's API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

1. Cost-Controlled Field Selection

When an LLM searches for a contact, its default behavior is to request the entire payload. In standard CRM APIs, this is fine. In LeadIQ, data costs money. The API explicitly omits high-value fields - like personal emails and direct phone numbers - unless explicitly requested. If you build raw tools, the LLM will constantly fail to find contact information because it doesn't know it must pass flags like with_personal_emails or with_phones. Truto's tool schemas explicitly define these parameters, allowing the agent to reason about when to spend credits for deeper enrichment versus when a basic work email is sufficient.

2. The 10,000 Record Pagination Trap

LeadIQ uses an offset-paginated structure (skip and limit). Standard LLMs are terrible at math and state management across long loops. More importantly, LeadIQ strictly caps offset pagination at 10,000 combined records. If an autonomous agent decides to "find all software companies in the US" and tries to page through the results, the API will throw errors once skip + limit exceeds 10,000. Your agent needs strictly typed tools that force targeted, filtered queries rather than open-ended database dumps.

3. Flat vs. Grouped Advanced Searches

LeadIQ differentiates between how it returns company data and how it returns people data. Company searches often return grouped results (GroupedAdvancedSearch), where the API returns the company entity but does not read or bill for the people within that group. Conversely, people searches (FlatAdvancedSearch) return individual contact objects but omit email/phone fields by default. If an agent does not understand this architectural difference, it will hallucinate nested fields that do not exist in the response payload.

Why a Unified Tool Layer Matters for Agent Safety

Direct API tools - mapping one tool per raw LeadIQ endpoint - look convenient but push provider quirks directly into the LLM's context window. The model has to remember that LeadIQ caps offsets at 10,000, that emails require specific boolean flags, and that company searches return grouped objects.

A unified tool layer abstracts these quirks into stable schemas. That gives you concrete safety wins:

1. Deterministic input validation: Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the LeadIQ API, so a broken tool call fails fast instead of generating a generic 400 Bad Request that confuses the agent.
2. Clean error boundaries: When LeadIQ returns an error, the unified API normalizes it. The agent receives a predictable error message indicating exactly which parameter failed, allowing it to self-correct and retry.
3. Framework agnosticism: You can hot-swap LangChain for Vercel AI SDK or CrewAI without rewriting your integration layer. The tools are fetched dynamically at runtime.

Hero Tools for LeadIQ AI Agents

Instead of exposing raw HTTP methods, Truto provides proxy tools with optimized descriptions and schemas. Here are the core LeadIQ operations your agent can execute autonomously.

lead_iq_people_search

Looks up a single person by specific identifiers. This is an identity lookup, not a broad search filter.

Contextual usage notes: The agent must provide an email, a LinkedIn URL, or a combination of a name and company identifier (company name or domain). By default, this returns a profile with a work email if LeadIQ has one. To control API costs, personal emails and phone numbers are excluded unless the agent explicitly sets with_personal_emails or with_phones to true. It returns at most one result, making it ideal for pinpoint enrichment.

"I have a prospect named Sarah Jenkins who works at Acme Corp. Use her name and company name to find her profile. Please include her direct phone number and personal email in the lookup."

lead_iq_companies_search

Looks up a single company by domain, LinkedIn URL, or exact name.

Contextual usage notes: Similar to the people search, this is a strict identity lookup intended to find a single matching record. It returns the first matching result or zero results on a miss. If the agent needs to find a list of companies based on industry or size, it should not use this tool; it should use list_all_lead_iq_companies instead.

"We just got an inbound lead from the domain techcorp.io. Look up this company to get their firmographic details, specifically their employee headcount and location."

list_all_lead_iq_companies

Executes an advanced search across companies based on filters like domain, name, employee count ranges, or country.

Contextual usage notes: This tool utilizes LeadIQ's GroupedAdvancedSearch. It returns only the company half of each grouped result. Crucially, the people within these companies are not read or billed by this method. The agent must handle skip and limit for pagination, keeping in mind the strict 10,000 record ceiling. This tool is best used for building target account lists.

"Find me a list of companies located in the United Kingdom that have an employee count between 500 and 1000. Return the first 50 results."

list_all_lead_iq_contacts

Executes a flat advanced search for people based on job title, seniority, company domain, or location.

Contextual usage notes: This tool utilizes FlatAdvancedSearch. It is strictly for discovery and list building. It never selects email or phone fields, regardless of the parameters passed. To get contact information for the people found in this list, the agent must subsequently use lead_iq_people_search on the specific profiles it wants to enrich.

"Search for contacts with the title 'VP of Engineering' or seniority level 'Executive' at companies located in New York. Limit the results to 20."

To view the complete inventory of available tools, query parameters, and JSON schemas, visit the LeadIQ integration page.

Workflows in Action

When you bind these tools to an LLM, the agent transitions from a simple chatbot to an autonomous revenue operations engine. Here is how specific prospecting scenarios play out in production.

Scenario 1: Targeted Account Sourcing and Decision Maker Enrichment

Sales development teams spend hours manually cross-referencing company sizes with job titles. An agent can automate this entirely.

"Build a target list of 10 companies in the United States with 100-250 employees. For each company, find their 'Director of IT' and get their verified work email and direct phone number."

1. The agent calls list_all_lead_iq_companies with parameters for country: US and employee_count: 100-250, limiting to 10 results.
2. The tool returns a list of 10 company domains.
3. The agent loops through the domains. For each domain, it calls list_all_lead_iq_contacts with company_domain: [domain] and title: Director of IT.
4. This returns basic contact profiles without contact info.
5. The agent then maps over those profiles and calls lead_iq_people_search using the name and company domain, explicitly setting with_phones: true to spend credits and retrieve the direct dials.
6. The agent compiles the final enriched list and returns it to the user.

Scenario 2: Enriching Incomplete Inbound Lead Data

Marketing pipelines often capture only a first name and a corporate email address. The agent must qualify the lead before routing it to sales.

"We received a form fill from 'Alex' at the email 'alex@stellarstartups.com'. Find out his full name, job title, and the size of his company. If the company is larger than 50 employees, flag it as qualified."

1. The agent extracts the domain stellarstartups.com from the email address.
2. The agent calls lead_iq_companies_search using domain: stellarstartups.com to retrieve firmographics. It notes the employee count.
3. The agent calls lead_iq_people_search using the exact email alex@stellarstartups.com.
4. The tool returns Alex's full profile, including his last name and exact job title.
5. The agent evaluates the employee count against the >50 threshold and generates a final JSON response with the enriched lead data and a qualified: true boolean.

Building Multi-Step Workflows

To execute the workflows above, you need an orchestration layer that fetches tools, binds them to the model, and handles the execution loop.

Truto provides a framework-agnostic /tools API. Whether you are using LangChain, LangGraph, or custom TypeScript loops, the integration architecture remains the same.

Fetching Tools and Binding to the Agent

First, retrieve the LeadIQ tools from your integrated account via the Truto API.

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 runLeadIQAgent() {
  // 1. Initialize the Truto Tool Manager with your tenant credentials
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch the tools specifically for your LeadIQ integration
  const leadIqAccountId = process.env.LEADIQ_INTEGRATED_ACCOUNT_ID;
  const tools = await toolManager.getTools(leadIqAccountId);
 
  // 3. Bind the tools to your LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
  
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an elite revenue operations agent. Use the provided tools to search LeadIQ for companies and contacts. Pay strict attention to pagination and field selection parameters."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
  });
 
  const result = await agentExecutor.invoke({
    input: "Find me 5 tech companies in Austin, TX, and list one VP at each."
  });
 
  console.log(result.output);
}

Handling Rate Limits and the 429 Reality

One of the most critical engineering realities of building AI agents is rate limiting. LLMs operate asynchronously and will execute tool calls as fast as the framework allows. LeadIQ, like all enterprise APIs, enforces strict rate limits.

Factual note on rate limits: Truto does not automatically retry, throttle, or apply exponential backoff on rate limit errors. When an upstream API like LeadIQ returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller.

However, Truto abstracts away the vendor-specific headers. It normalizes upstream rate limit information into standardized IETF headers: ratelimit-limit, ratelimit-remaining, and ratelimit-reset. The caller - your agent framework - is entirely responsible for reading these headers, sleeping the execution thread, and retrying.

Here is how an autonomous agent interacts with the Truto proxy layer during a rate limit event:

sequenceDiagram
    participant LLMAgent as LLM Agent
    participant ToolManager as Truto Tool Manager
    participant TrutoAPI as Truto Proxy Layer
    participant UpstreamAPI as LeadIQ API

    LLMAgent->>ToolManager: Execute "list_all_lead_iq_contacts"
    ToolManager->>TrutoAPI: POST /proxy/leadiq/contacts
    TrutoAPI->>UpstreamAPI: Forward request to LeadIQ
    UpstreamAPI-->>TrutoAPI: HTTP 429 Too Many Requests
    TrutoAPI-->>ToolManager: Pass HTTP 429 + Normalized Headers
    Note over ToolManager,TrutoAPI: ratelimit-reset: 1719820000<br>ratelimit-remaining: 0
    ToolManager-->>LLMAgent: Tool Execution Failed (Rate Limited)
    Note over LLMAgent: Agent catches 429 error<br>reads ratelimit-reset header
    LLMAgent->>LLMAgent: Sleep Thread until Reset Time
    LLMAgent->>ToolManager: Retry "list_all_lead_iq_contacts"
    ToolManager->>TrutoAPI: POST /proxy/leadiq/contacts
    TrutoAPI->>UpstreamAPI: Forward request to LeadIQ
    UpstreamAPI-->>TrutoAPI: HTTP 200 OK

If you do not catch tool execution errors in your LangChain setup, a single 429 will crash the entire agent loop. You must configure your agent executor to handle tool errors gracefully, parse the ratelimit-reset timestamp provided by Truto, and pause execution accordingly before trying again.

Moving Forward

Connecting an AI agent to LeadIQ is no longer a multi-week engineering project involving custom schemas, complex OAuth flows, and bespoke error handling. By leveraging a unified tool layer, you reduce the attack surface for LLM hallucination and provide your agent with strictly typed, cost-aware functions.

Whether you are building an internal Slack bot to help your SDRs prospect faster, or an external RAG pipeline that enriches user data on the fly, programmatic tool calling is the only architecture that scales safely.