Connect Qualified to AI Agents: Automate Bulk Jobs and Outreach

You want to connect Qualified to an AI agent so your system can independently route leads, trigger GDPR deletion requests, ingest bulk updates, and manage chat sessions based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to write and maintain a custom Qualified integration from scratch.

Giving a Large Language Model (LLM) read and write access to your conversational marketing platform is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Qualified to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Qualified 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 Qualified, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex conversational marketing 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 Qualified 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 conversational marketing systems, this approach collapses.

Qualified'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.

The 30-Minute Data Hold-Back Trap

Most APIs return data immediately after an event occurs. Qualified implements a strict hold-back window for list operations on conversational objects. When an agent calls the list_all_qualified_sessions, list_all_qualified_conversations, or list_all_qualified_messages endpoints, the data will not appear in the response until exactly 30 minutes after the session ends.

If your agent attempts to query a list endpoint immediately after a web visitor disconnects, the API will return an empty array or a 400 error if you attempt to force a time bound inside that hold period. This causes LLMs to hallucinate, assuming the conversation never happened. To get real-time data, your agent must know to use the specific get_single_qualified_conversation_by_id endpoint, which bypasses the hold-back constraint entirely. Managing this logical branching inside a standard system prompt is highly error-prone.

Dynamic Custom Field Injection

LLMs are trained to expect flat, intuitive JSON objects. When an agent wants to create a lead, it naturally attempts to send a payload like {"email": "user@example.com", "job_title": "CTO"}.

Qualified handles standard fields normally, but custom fields are injected into a deeply nested fields object. Worse, the keys for this object are not predictable - you must query the list_all_qualified_lead_fields endpoint to map the human-readable label to the internal API name. If an agent tries to write a custom field using the wrong API name, the data is silently dropped or rejected. Your tool layer must normalize these field schemas so the LLM does not have to guess.

Asynchronous Bulk Job Orchestration

When syncing large cohorts of leads or companies (up to 500 records), you cannot execute individual POST requests without saturating rate limits. Qualified requires you to use the bulk jobs API. Submitting a bulk job returns an ID, not the processed data. The agent must understand how to poll the get_single_qualified_bulk_job_by_id endpoint, interpret the status field, and handle the processedRecords versus failedRecords counts. This requires stateful orchestration that basic REST tools cannot handle on their own.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how safe your production system will be.

Direct API tools (one tool per raw Qualified endpoint) look convenient, but they push provider quirks directly into the LLM's context window. A unified tool layer collapses these complexities behind a clean proxy schema.

Truto provides a set of tools for your LLM frameworks by offering a description and schema for all the Methods defined on the Resources for an integration. Truto handles all pagination, authentication, and query parameter processing via Proxy APIs. Every integration on Truto is essentially a comprehensive JSON object that represents how the underlying product's API behaves, mapping any API into a REST-based CRUD API.

When your agent calls the /integrated-account/:id/tools endpoint, it receives a normalized list of Proxy APIs with their descriptions and schemas, creating safe, deterministic tools.

Hero Tools for Qualified Agents

To build an effective agent, you need to expose the right primitive operations. Exposing the entire Qualified API is counterproductive - it increases the token payload and confuses the LLM. Focus on high-leverage tools.

Here are the critical tools to expose to your agent for conversational marketing automation.

list_all_qualified_leads

Retrieves a list of Qualified leads, ordered newest first. Crucially, this tool returns the mapped integration IDs (Salesforce, Pardot, Marketo, HubSpot) alongside the standard visitor data. This allows the agent to cross-reference visitors with your CRM data.

"Find all leads that were updated after midnight yesterday and extract their Salesforce Lead IDs so we can verify their routing status."

create_a_qualified_lead

Creates or updates a Qualified lead, matched automatically by email address. The tool schema enforces that only the provided fields are overwritten, leaving existing data untouched. This is vital for agents enriching leads over time without destroying previous context.

"The user just provided their job title in the chat. Update the Qualified lead for alex@acmecorp.com and set their title to Director of Engineering."

list_all_qualified_sessions

Retrieves website sessions ordered by when they ended. The tool schema clearly defines the ended_after and ended_before time bounds, allowing the agent to audit web traffic patterns and extract conversationIds for deeper analysis.

"Pull the list of website sessions from the last 24 hours. If any session has an associated conversationId, store it for the next step of my analysis."

list_all_qualified_conversations

Fetches engaged chat conversations. Because of the 30-minute hold-back quirk, this tool description explicitly instructs the LLM to only search for conversations that ended more than half an hour ago, preventing time-bound errors.

"Fetch all engaged chat conversations from yesterday afternoon and isolate the ones where the visitor requested a live meeting."

list_all_qualified_meetings

Lists meetings booked through Qualified, returning the status, attendees, and channel data. Unlike sessions, meetings take 24 hours to appear in list results. This tool allows the agent to run daily audits of meeting flow and sales rep capacity.

"Generate a report of all meetings booked through the website over the last three days, grouped by the assigned sales rep."

create_a_qualified_bulk_job

Submits an array of up to 500 lead or company records for asynchronous processing. This tool abstracts the batching logic, allowing the agent to process large CSV uploads or CRM syncs in a single operation.

"I have a list of 350 webinar attendees. Format them as Qualified leads and submit them to the bulk job queue for processing."

create_a_qualified_gdpr_deletion_request

Submits a batch of email addresses for permanent GDPR deletion. The tool schema strictly enforces email formatting, as the Qualified API will reject the entire batch if a single email is malformed. This gives the agent a safe way to handle compliance requests.

"A user requested that we delete their data. Submit a GDPR deletion request for privacy@example.com to the Qualified system."

For the complete inventory of available tools, query parameters, and schema definitions, review the Qualified integration page.

Workflows in Action

Individual tools are useful, but AI agents deliver real value when chaining these tools together into autonomous workflows. Here are three concrete examples of how an agent uses these tools in production.

Scenario 1: Post-Event Bulk Lead Routing

Marketing teams often return from trade shows with massive lists of leads that need to be ingested and scored based on website activity.

"Take this list of 400 emails from the conference. Create a bulk job to add them as leads in Qualified. Then, for any lead that successfully processes, check if they had a website session in the last 30 days."

1. The agent parses the provided data and constructs a batch payload.
2. It calls create_a_qualified_bulk_job to submit the 400 leads.
3. It periodically checks the job status (using get_single_qualified_bulk_job_by_id).
4. Once complete, it iterates over the processed emails and calls list_all_qualified_leads to get the internal visitorIds.
5. It calls list_all_qualified_sessions filtered by those IDs to find recent activity.

Outcome: The user receives a prioritized list of conference leads who are also active on the company website, ready for immediate sales outreach.

Scenario 2: Autonomous Conversation Auditing

Sales enablement teams need to review bot performance and human hand-offs to ensure SLAs are met.

"Review all engaged conversations from yesterday. Find any conversation where a human rep took over, and summarize the primary objection the visitor raised."

1. The agent calls list_all_qualified_rep_conversations filtered by yesterday's date.
2. For each returned conversation ID, it calls get_single_qualified_conversation_by_id to get the real-time, detailed data.
3. It calls list_all_qualified_conversation_messages to extract the actual chat transcripts.
4. The LLM analyzes the transcripts in memory to identify the visitor's objections.

Outcome: The user gets an aggregated report of sales objections categorized by frequency, directly extracted from raw chat logs.

Scenario 3: Automated GDPR Compliance Execution

Handling data deletion requests manually is tedious and carries high legal risk if missed across different SaaS platforms.

"We received a formal Right to be Forgotten request for user info@acmecorp.com. Execute the deletion in Qualified and verify it was submitted."

1. The agent calls create_a_qualified_gdpr_deletion_request with the target email.
2. It parses the success message from the API.
3. It executes a follow-up call to list_all_qualified_leads searching for that email to verify the record is being processed out of the system.

Outcome: The agent executes the compliance request and returns a verifiable audit log showing exactly when the deletion was triggered.

Building Multi-Step Workflows

To build these workflows, you need to bind Truto's dynamically generated tools to your agent framework. The following TypeScript example demonstrates how to fetch the tools from Truto, handle rate limit headers correctly, and execute a multi-step conversation audit using LangChain.

Handling Rate Limits

Factual note on rate limits: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When the upstream Qualified API returns an HTTP 429 (Too Many Requests), Truto passes that exact error to your caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your agent execution loop is fully responsible for reading these headers and implementing its own retry or backoff logic.

Here is how the architecture looks conceptually:

sequenceDiagram
    participant AgentLoop as Agent Execution Loop
    participant TrutoAPI as Truto Proxy API
    participant Qualified as Qualified API
    AgentLoop->>TrutoAPI: Execute tool (list_leads)
    TrutoAPI->>Qualified: GET /leads
    Qualified-->>TrutoAPI: HTTP 429 Too Many Requests
    TrutoAPI-->>AgentLoop: 429 Response + ratelimit-* headers
    Note over AgentLoop: Orchestrator pauses based on<br>ratelimit-reset header
    AgentLoop->>TrutoAPI: Retry request after backoff
    TrutoAPI->>Qualified: GET /leads
    Qualified-->>TrutoAPI: 200 OK
    TrutoAPI-->>AgentLoop: Normalized Lead Data

Implementation Code

Below is a framework-agnostic approach utilizing the @langchain/core library to bind the tools to an Anthropic model.

import { ChatAnthropic } from "@langchain/anthropic";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
 
// 1. Fetch AI-ready tools from Truto
async function getQualifiedTools(integratedAccountId: string) {
  const response = await fetch(`https://api.truto.one/integrated-account/${integratedAccountId}/tools`, {
    headers: {
      Authorization: `Bearer ${process.env.TRUTO_API_KEY}`
    }
  });
  
  if (!response.ok) {
    throw new Error(`Failed to fetch tools: ${response.statusText}`);
  }
  
  const { tools } = await response.json();
  
  // Convert Truto schemas to LangChain DynamicStructuredTools
  return tools.map((tool: any) => {
    return new DynamicStructuredTool({
      name: tool.name,
      description: tool.description,
      schema: z.any(), // In production, parse the JSON schema to Zod
      func: async (input) => {
        // 2. Execute the tool against Truto's proxy
        const res = await fetch(`https://api.truto.one/proxy/${tool.resource}/${tool.method}`, {
          method: tool.httpMethod,
          headers: {
            Authorization: `Bearer ${process.env.TRUTO_API_KEY}`,
            'Content-Type': 'application/json',
            'x-truto-integrated-account-id': integratedAccountId
          },
          body: ['POST', 'PUT', 'PATCH'].includes(tool.httpMethod) ? JSON.stringify(input) : undefined
        });
 
        // 3. Handle Rate Limits using standardized headers
        if (res.status === 429) {
          const resetTime = res.headers.get('ratelimit-reset');
          const waitTime = resetTime ? parseInt(resetTime) * 1000 - Date.now() : 5000;
          console.warn(`Rate limited. Waiting ${waitTime}ms before retry...`);
          // Return a specific error string so the LLM knows to wait or retry later
          return JSON.stringify({ 
              error: "Rate limit exceeded", 
              retry_after_ms: waitTime 
          });
        }
 
        return await res.text();
      }
    });
  });
}
 
// 4. Initialize the Agent
async function runAgent() {
  const tools = await getQualifiedTools("your-qualified-account-id");
  
  const llm = new ChatAnthropic({
    modelName: "claude-3-5-sonnet-latest",
    temperature: 0,
  });
 
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a conversational marketing operations agent. Execute tasks using the provided Qualified tools. Handle rate limits gracefully."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
  });
 
  const result = await agentExecutor.invoke({
    input: "Fetch all engaged chat conversations from yesterday and summarize the primary objections.",
  });
 
  console.log(result.output);
}

This architecture guarantees that the LLM is interacting with a highly structured, strongly typed interface. It never has to guess endpoint URLs, construct pagination cursors, or fumble with complex OAuth token refreshes.

The Path Forward

Giving AI agents access to your conversational marketing data is the fastest way to automate lead routing, compliance tasks, and conversation analysis. However, building point-to-point integrations for agents creates brittle systems that fail whenever an API changes or a custom field is altered.

By leveraging Truto's /tools endpoint, you abstract away the operational complexity of the Qualified API. Your agents get a clean, deterministic schema, and your engineering team avoids writing boilerplate integration code. You handle the agent's reasoning loop; Truto handles the SaaS connectivity.