Skip to content
Truto
Back
AI & Agents

Connect Manatal to AI Agents: Automate Recruitment Notes and Resumes

Learn how to connect Manatal to AI agents using Truto's /tools endpoint. A technical guide to exposing ATS data, managing attachments, and automating recruitment workflows via LLM tool calling.

Uday Gajavalli Uday Gajavalli · · 10 min read
Connect Manatal to AI Agents: Automate Recruitment Notes and Resumes

You want to connect Manatal to an AI agent so your system can autonomously read candidate profiles, update recruitment pipelines, parse external documents, and draft interview notes 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 Applicant Tracking System (ATS) connector from scratch.

If your team uses ChatGPT, check out our guide on connecting Manatal to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Manatal to Claude. Building custom agents usually hits a wall at the API integration layer. We covered this architectural chokepoint extensively in our post on architecting AI agents, LangGraph, LangChain, and the SaaS integration bottleneck.

Giving a Large Language Model (LLM) read and write access to your Manatal instance is a severe engineering challenge. You either spend weeks building, hosting, and maintaining a custom ATS connector, or you use a managed infrastructure layer that handles the boilerplate and schema normalization for you. This guide breaks down exactly how to fetch AI-ready tools for Manatal, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex talent acquisition workflows autonomously.

The Engineering Reality of the Manatal API

Building AI agents is straightforward. Connecting them to external SaaS APIs in a production environment is notoriously difficult.

Giving an LLM access to external ATS data sounds simple in a local prototype. You write a Node.js function that makes a fetch request to the Manatal API and wrap it in an @tool decorator. In production, this approach collapses entirely. If you decide to build a custom integration for Manatal, you own the entire API lifecycle. Manatal's API introduces several specific integration challenges that break standard CRUD assumptions for LLMs.

The Candidate PK vs. ID Hierarchy

Manatal relies on strict internal database representations for nested relationships. While an overarching candidate profile might have a standard UUID identifier, many sub-resources - specifically notes - require a candidate_pk (a primary key integer). LLMs inherently struggle with relational database key mappings. If you ask an agent to "leave a note on John's profile," standard APIs require the agent to search for the user, extract the ID, and apply it to a POST request. With Manatal, if the LLM confuses the external ID string with the internal integer candidate_pk, the API will reject the payload with a 400 Bad Request. You must define strict JSON schemas that force the LLM to extract the exact property type required by the specific endpoint.

Handling Resumes and Binary Attachments via LLM

Large Language Models generate text. They do not hold binary file streams in memory. When an AI agent needs to upload a candidate's resume or a portfolio attachment to Manatal, you cannot expect the LLM to construct a multipart/form-data payload containing raw PDF bytes.

Manatal requires specific endpoints for resumes versus general attachments. To make this work agentically, you must abstract the file handling. The LLM must be provided a tool schema that accepts a file URL (e.g., resume_file or file strings), and the integration layer must retrieve the file from that URL, convert it to the required format, and stream it to Manatal. Truto abstracts this away, allowing the LLM to simply pass the URL as a string parameter.

Rate Limits and the 429 Reality

Recruitment workflows are inherently bursty. An agent might attempt to ingest 500 resumes from a career fair in a single loop, triggering rapid requests to create candidates, add resumes, and generate summary notes. Manatal enforces rate limits to protect its infrastructure.

Here is a critical architectural fact: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Manatal API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. It is entirely the responsibility of your AI agent's execution loop to catch the 429, read the ratelimit-reset header, and implement exponential backoff.

Exposing Manatal Tools to Your Agent

Truto maps Manatal's API endpoints into REST-based CRUD Proxy APIs. Every resource (like a candidate note or resume) has methods (Create, List, Delete) defined on it. Truto handles the authentication securely and provides a normalized description and schema for all of these methods. To learn more about how this works, see our post on LLM tool calling and function calling.

To give your AI agent access, you call the GET https://api.truto.one/integrated-account/<id>/tools endpoint. This returns a comprehensive JSON array of all available Manatal operations, complete with the OpenAPI-compliant schemas that LLMs require to structure their tool calls.

If you are using Node.js and LangChain, Truto provides the truto-langchainjs-toolset SDK to fetch these tools and bind them to your model dynamically.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
 
async function initializeManatalAgent() {
  // Initialize the Truto Tool Manager with your Manatal Integrated Account ID
  const toolManager = new TrutoToolManager({
    trutoToken: process.env.TRUTO_API_KEY,
    integratedAccountId: "acc_manatal_01H...", 
  });
 
  // Fetch all Manatal tools. We can filter for specific methods if needed.
  const tools = await toolManager.getTools();
 
  const model = new ChatOpenAI({ 
    modelName: "gpt-4o",
    temperature: 0 
  });
 
  // Bind the Manatal tools natively to the LLM
  const modelWithTools = model.bindTools(tools);
 
  return { modelWithTools, tools };
}

When the LLM decides to execute a tool, it outputs a structured JSON response matching the schema. The execution loop then passes that JSON back to Truto, which handles the exact HTTP request formatting required by Manatal.

Manatal Hero Tools

Truto provides comprehensive coverage of the Manatal API, translating it into dozens of discrete tools. When building recruitment AI agents, these are the highest-leverage tools to expose to your LLM.

Create a Manatal Candidate Note

This tool allows the agent to write a new note and attach it to a specific candidate profile. It is essential for automated interview debriefs or screening summaries. It requires the candidate_id and returns the new note's id, info, creator, and created_at timestamp.

"Summarize the following technical screening transcript into a bulleted list of strengths and weaknesses. Once complete, find the candidate with ID 8472 and add this summary as a new candidate note."

List All Manatal Candidate Notes

Before an agent can draft an email or prepare an interviewer for a call, it needs context. This tool allows the agent to retrieve all existing notes for a specific candidate using the candidate_pk. The response includes the id, info, creator, and created_at fields for every historical note.

"Retrieve all notes for candidate PK 592. Review the notes to see if any previous interviewer mentioned concerns about their system design experience. If so, summarize those specific concerns."

Delete a Manatal Candidate Note by ID

AI agents occasionally make mistakes, or recruitment teams need to scrub Personally Identifiable Information (PII) from historical records. This tool enables the agent to delete a specific note using the candidate_pk and the note's id. It returns a 204 status to confirm the deletion.

"I accidentally uploaded the wrong phone screen summary for candidate PK 381. Find the note created today that mentions 'Python developer', delete it, and confirm once it has been removed."

Create a Manatal Candidate Resume

This is the core file ingestion tool. It allows the agent to attach a resume to a candidate profile using the candidate_id. To bypass the complexity of binary file handling, the schema accepts a resume_file URL. The response returns the id, the final uploaded resume_file URL, and the created_at timestamp.

"We just sourced a new senior frontend engineer. Their ID is 9123. Take this public AWS S3 URL containing their latest resume PDF and attach it to their Manatal profile as their primary resume."

Create a Manatal Candidate Attachment

Separate from the primary resume, candidates often provide portfolios, code samples, or cover letters. This tool handles general file attachments. It requires the candidate_id and accepts a file URL. It returns the id, name, description, file URL, creator, and created_at fields.

"The candidate (ID 4412) submitted a link to their UX design portfolio. Upload this file URL as a candidate attachment named 'UX_Portfolio_2026.pdf' and add a description stating it was provided during the final interview stage."

For the complete inventory of available Manatal tools, exact schema definitions, and custom resource configurations, refer to the Manatal integration page.

Building Multi-Step Workflows

Agentic workflows are rarely single-step actions. If a recruiter asks the AI to update a candidate's status based on a technical assessment, the agent must first read the assessment, retrieve the candidate's existing notes to ensure it hasn't already been processed, draft the new note, and handle any potential API failures during the write process.

Because Truto passes HTTP 429 rate limit errors directly to your system, your agent's execution loop must be engineered to catch these errors and respect the normalized ratelimit-reset header.

Here is a conceptual architecture using standard JavaScript logic to handle multi-step agent execution with rate limit backoff:

import { ToolNode } from "@langchain/langgraph/prebuilt";
 
// Assuming modelWithTools is initialized
async function executeAgentLoop(prompt: string, modelWithTools, tools) {
  let messages = [["user", prompt]];
  
  while (true) {
    // 1. LLM decides what to do
    const aiMessage = await modelWithTools.invoke(messages);
    messages.push(aiMessage);
 
    // If no tool calls, the LLM is done thinking
    if (!aiMessage.tool_calls || aiMessage.tool_calls.length === 0) {
      break;
    }
 
    // 2. Execute the requested Manatal tools
    for (const toolCall of aiMessage.tool_calls) {
      const selectedTool = tools.find(t => t.name === toolCall.name);
      
      let success = false;
      let attempts = 0;
      let toolResult;
 
      while (!success && attempts < 3) {
        try {
          attempts++;
          // Execute the tool against Truto's proxy API
          toolResult = await selectedTool.invoke(toolCall.args);
          success = true;
        } catch (error) {
          // 3. Handle Rate Limits natively using Truto's normalized headers
          if (error.status === 429) {
            const resetHeader = error.headers['ratelimit-reset'];
            const resetTimeMs = resetHeader ? parseInt(resetHeader) * 1000 : 5000;
            
            console.log(`Rate limited by Manatal. Pausing for ${resetTimeMs}ms...`);
            await new Promise(resolve => setTimeout(resolve, resetTimeMs));
          } else {
            // Feed normal errors (e.g. 400 Bad Request) back to the LLM so it can correct its payload
            toolResult = `Error executing tool: ${error.message}. Please check your arguments and try again.`;
            success = true; // Break the retry loop and let the LLM fix it
          }
        }
      }
 
      // 4. Feed the tool result back into the context window
      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        name: toolCall.name,
        content: typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult)
      });
    }
  }
  
  return messages[messages.length - 1];
}

In this architecture, the agent framework (LangGraph, in this conceptual example) handles the routing. When the agent attempts to list 100 candidate notes and triggers Manatal's rate limit, Truto returns the 429. The loop catches it, reads the ratelimit-reset header, pauses the exact amount of time required by the ATS, and retries the tool execution seamlessly without failing the entire conversational thread.

Workflows in Action

When you abstract the API complexity behind Truto's tools, AI agents can execute sophisticated, domain-specific tasks that would normally require human recruiters to spend hours clicking through the Manatal UI. Here are two concrete examples of multi-step autonomous workflows.

Workflow 1: The Automated Interview Debrief

Recruiters frequently record screening calls and rely on AI transcripts to capture details. Manually moving transcript summaries into the ATS is tedious. An AI agent can handle the data entry autonomously.

"Take this raw transcript from my technical screen with candidate_pk 8472. Summarize their proficiency in React and Node.js. Check their existing notes to see if I already left a summary today. If I did, delete the old note and replace it with this new, comprehensive summary."

  1. list_all_manatal_candidate_notes: The agent queries Manatal for all notes attached to candidate_pk: 8472.
  2. Evaluate Logic: The LLM reads the response array. It identifies a note created today by the current user.
  3. delete_a_manatal_candidate_note_by_id: The agent executes a deletion using the identified note's id to clear the duplicate record.
  4. create_a_manatal_candidate_note: The agent formats the final markdown summary of the transcript and creates the new note on the profile.

The recruiter gets a perfectly formatted, up-to-date technical assessment logged directly into the ATS without opening a single new browser tab.

Workflow 2: Automated Portfolio and Resume Ingestion

When a candidate applies via a third-party form or an email thread, their documents often sit outside the ATS. Agents can extract these file URLs and orchestrate the uploads.

"I have a new applicant, candidate_id 9912. Here is the S3 URL for their resume, and here is a secondary Dropbox link for their design portfolio. Upload the resume as their primary document, and attach the portfolio as a general file named 'UX_Portfolio'."

  1. create_a_manatal_candidate_resume: The agent calls this tool, passing candidate_id: 9912 and mapping the S3 URL to the resume_file parameter. Truto handles the backend file stream to Manatal.
  2. create_a_manatal_candidate_attachment: Next, the agent targets the portfolio. It maps the Dropbox URL to the file parameter, assigns the name "UX_Portfolio", and attaches it to the same candidate_id.

The recruitment team receives a fully populated candidate profile with all primary and secondary documents accessible via the Manatal interface, entirely orchestrated by the LLM.

Strategic Wrap-Up

Connecting an AI agent to an Applicant Tracking System requires more than just knowing the API endpoints. You have to handle specific relational keys, manage binary file uploads via URL proxying, and engineer resilient rate limit handling. By leveraging Truto's /tools endpoint, you strip away the integration boilerplate. You stop maintaining custom ATS schema mappings and start focusing on writing the core logic and prompts that drive your agentic workflows forward.

More from our Blog