Connect Flatchr to AI Agents: Automate Hiring and Pipeline Operations

You want to connect Flatchr to an AI agent so your system can autonomously parse resumes, migrate candidates through hiring pipelines, and trigger recruiter tasks based on real-time talent data. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Flatchr integration from scratch.

Giving a Large Language Model (LLM) read and write access to your Applicant Tracking System (ATS) 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 Flatchr to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Flatchr to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

Building an AI agent is a straightforward exercise in prompting and state management. Giving that agent reliable access to external ATS APIs is where projects stall. If you decide to build a custom connector, you own the entire API lifecycle. You must write the JSON schemas for the LLM to understand the endpoints, handle the authentication token lifecycle, normalize pagination, and deal with rate limiting.

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

The Engineering Reality of the Flatchr 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 HR systems, this approach collapses.

Flatchr'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 Multipart Form Data Problem

Applicant tracking systems are fundamentally document-centric. When an agent wants to create a new candidate profile, it cannot simply pass a flat JSON object. The Flatchr flatchr_applicants_create_custom endpoint supports vacancy details, names, comments, and answers to custom questions, but often expects payload structures that mimic public careers-site multipart forms.

Standard LLMs natively output JSON. They do not know how to construct multipart/form-data boundaries or stream binary file buffers. If you expose raw HTTP requests to the LLM, it will confidently hallucinate a JSON string for a PDF file, resulting in an immediate 400 Bad Request. Truto's Proxy API abstracts this encoding layer, allowing the LLM to pass standard JSON while Truto handles the protocol-level translation upstream.

Strict Pipeline State Transitions

Moving an applicant through a hiring pipeline (flatchr_applicants_move) requires precise relational data. An agent cannot simply update a status field to "Interviewing". It must provide the exact internal IDs for the vacancy and the specific column or stage in the Kanban board.

If you expose a raw PUT request to the LLM, the model will attempt to use semantic strings. The API will reject this. By wrapping the Flatchr API in defined tools, we force the LLM to first query the pipeline layout to retrieve valid IDs, preventing state transition failures.

Rate Limiting and the IETF Specification

AI agents are notoriously aggressive. An autonomous agent tasked with auditing 500 candidate profiles will rapidly execute sequential or parallel GET requests. It will hit Flatchr's rate limits instantly.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Flatchr API returns an HTTP 429 (Too Many Requests), Truto passes that exact error back to your caller. However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification (ratelimit-limit, ratelimit-remaining, ratelimit-reset).

You are strictly responsible for implementing retry and backoff logic in your application layer. Truto will not absorb these errors for you. You must design your agent loop to read the ratelimit-reset header and sleep execution accordingly.

Why a Unified Tool Layer Matters for Agent Safety

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

Direct API tools (one custom-coded tool per raw Flatchr endpoint) look convenient, but they push provider quirks directly into the LLM's context window. The model has to remember exactly how Flatchr paginates its applicant search, how to format query parameters for active vacancies, and how to structure metadata additions. Every one of those quirks is a hallucination waiting to happen.

Truto operates on a concept of Resources and Methods. Every integration is a comprehensive JSON object mapping the underlying API into REST-based CRUD proxy operations.

By leveraging Truto's /tools endpoint, you collapse these quirks behind a unified schema. Your agent sees cleanly typed tools like flatchr_applicants_search and create_a_flatchr_task. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only chooses from stable function names with deterministic JSON schemas.
2. Strict input validation. Invalid arguments generated by the LLM are rejected by the framework before they hit the Truto Proxy API, failing fast and saving valuable network calls.
3. Automatic Context Retrieval. Truto dynamically fetches the description and schema for all Methods defined on the Resources, ensuring that any custom fields configured in your Flatchr instance are accurately presented to the agent.

Hero Tools for Flatchr Automation

Truto provides all the resources defined on a Flatchr integration as tools for your LLM frameworks to use. Instead of building these from scratch, your agent queries the /tools endpoint and receives the following high-leverage operations.

Here are the critical tools you need to automate hiring pipelines.

flatchr_vacancies_list_active

This tool retrieves all currently open and active job requisitions within the organization. It is essential for mapping incoming candidates to valid roles and filtering out closed positions.

"Fetch all active vacancies in Flatchr and identify the vacancy ID for the Senior Frontend Engineer position."

flatchr_applicants_search

This tool allows the agent to query the candidate database using specific parameters. It handles the pagination and query structuring required by Flatchr to find specific applicants by email, name, or metadata.

"Search Flatchr for an applicant with the email address jane.doe@example.com and return their current pipeline stage."

flatchr_applicants_create_custom

This is the primary ingestion tool. It allows the agent to create a candidate profile as if they applied through the public careers-site multipart form. It supports linking the candidate to a specific vacancy, inputting their name, adding a comment, and populating custom question answers.

"Create a new applicant profile for John Smith under the Backend Developer vacancy. Add a comment that he was referred by the engineering team, and populate the expected salary question with '$120,000'."

flatchr_applicants_move

This tool executes pipeline transitions. It requires the agent to specify the exact identifiers for the candidate and the destination pipeline column, ensuring strict state management.

"Move the applicant Jane Doe from the 'Initial Review' column to the 'Technical Interview' column for the Data Scientist vacancy."

create_a_flatchr_task

Recruitment is a collaborative effort. This tool allows the agent to generate tasks within Flatchr and assign them to specific recruiters or hiring managers, ensuring follow-ups are not missed.

"Create a task in Flatchr assigned to the hiring manager to review the technical assessment for John Smith by Friday."

flatchr_candidates_add_meta

This tool appends structured metadata to a candidate profile, such as tags for specific skills or background check status. Note that this requires the Premium CV Library option in Flatchr, and uses an email address as the candidate reference.

"Add metadata to jane.doe@example.com tagging her profile with 'ReactJS' and 'Seniority: High'."

For the complete inventory of available tools, including message management, contract types, and comment deletion, review the Flatchr integration page.

Building Multi-Step Workflows

To build a truly autonomous system, you need to chain these tools together in an agentic loop. We will use TypeScript, the Truto /tools endpoint, and the LangChain SDK (specifically the truto-langchainjs-toolset) to demonstrate how this is architected.

Step 1: Fetching the Tools

The Truto LLM SDK uses the https://api.truto.one/integrated-account/<id>/tools endpoint to register tools dynamically. You can filter the tools you want to expose to the LLM to restrict its capabilities (e.g., read-only vs. write).

import { TrutoToolManager } from "truto-langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
// Initialize the Truto Tool Manager with your Integrated Account ID
const toolManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "flatchr_account_id_123",
});
 
// Fetch all tools, optionally filtering for specific methods
const tools = await toolManager.getTools({
  methods: ["read", "write", "custom"]
});

Step 2: Handling Rate Limits

Because Truto acts as a transparent proxy, it enforces the upstream reality of the Flatchr API. If your agent executes tools in a tight loop and hits the rate limit, Flatchr returns a 429 Too Many Requests. Truto normalizes this into IETF headers. You must build resilience into your execution layer.

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto API
    participant Flatchr as Flatchr API
    
    Agent->>Truto: Execute flatchr_applicants_search
    Truto->>Flatchr: Upstream GET Request
    Flatchr-->>Truto: 429 Too Many Requests
    Truto-->>Agent: HTTP 429 (ratelimit-reset: 30)
    Note over Agent: Agent catches 429<br>Reads header, sleeps 30s
    Agent->>Truto: Retry flatchr_applicants_search
    Truto->>Flatchr: Upstream GET Request
    Flatchr-->>Truto: 200 OK
    Truto-->>Agent: Tool execution successful

To handle this in your agent framework, you must wrap your executor or instruct your agent via system prompts to interpret API failures and retry intelligently based on the error metadata.

Step 3: Binding Tools and Executing

Once the tools are fetched, you bind them to your LLM and define the agent loop.

const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
}).bindTools(tools);
 
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a highly capable talent operations assistant. You have access to Flatchr tools. If a tool fails with a rate limit error, inform the user or pause execution. Always verify vacancy IDs before creating applicants."],
  ["placeholder", "{chat_history}"],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);
 
const agent = await createOpenAIToolsAgent({
  llm,
  tools,
  prompt,
});
 
const agentExecutor = new AgentExecutor({
  agent,
  tools,
  maxIterations: 10,
});
 
const result = await agentExecutor.invoke({
  input: "Find all active vacancies. Then, search if Jane Doe is an applicant. If she is, move her to the 'Offer Extended' pipeline stage for the frontend role."
});
 
console.log(result.output);

Workflows in Action

Abstract code is helpful, but seeing exactly how the LLM chains these tools in real-world scenarios clarifies the architecture. Here are two concrete personas using the system.

Scenario 1: Automated Sourcing & Resume Ingestion

A Talent Acquisition Manager relies on the agent to parse inbound emails from external job boards and automatically inject them into Flatchr.

"I just received a referral email for Alex Chen. He is applying for the Data Engineer role. Create a custom applicant profile for him in the correct active vacancy, note that he is an internal referral, and tag his profile with 'Python' and 'SQL'."

Step-by-step Tool Execution:

1. The agent calls flatchr_vacancies_list_active to find the exact ID for the "Data Engineer" vacancy.
2. The agent extracts Alex's details from context and calls flatchr_applicants_create_custom, passing the vacancy ID, Alex's name, and the referral comment.
3. The agent extracts Alex's email and calls flatchr_candidates_add_meta to attach the 'Python' and 'SQL' metadata tags.

Outcome: The hiring manager sees a fully populated candidate profile in the correct pipeline stage, heavily tagged and ready for review, without manual data entry.

Scenario 2: Pipeline Cleanup and SLA Enforcement

A Talent Operations Administrator uses the agent to enforce Service Level Agreements (SLAs) for candidate feedback, ensuring no applicant is left languishing in the pipeline.

"Search all active applicants. Find anyone who has been in the 'Technical Interview' stage for more than 5 days. For each candidate found, create a task assigned to the hiring manager asking them to submit their scorecard immediately."

Step-by-step Tool Execution:

1. The agent calls flatchr_applicants_search filtering by the 'Technical Interview' column ID (which it may have retrieved via a prior metadata tool call) and checking the timestamp of their last move.
2. For each candidate meeting the criteria, the agent iterates and calls create_a_flatchr_task, referencing the candidate ID and the hiring manager's Flatchr member ID.

Outcome: The Operations Administrator gets a natural language summary that 4 tasks have been generated. The hiring managers receive automated nudges inside Flatchr.

Orchestrating Autonomous Talent Systems

Connecting Flatchr to an AI agent is not about creating a chatbot that can answer HR questions. It is about building an orchestration layer that independently executes rote pipeline mechanics.

By leveraging Truto's /tools endpoint, you remove the burden of API maintenance from your engineering team. You do not have to write manual serializers for multipart form data, you do not have to maintain OAuth flows for every HR recruiter, and you do not have to write custom logic for every Flatchr endpoint. You simply fetch the schemas, bind them to your LLM, handle the standardized rate limits, and let the agent orchestrate the logic.

Build the autonomous workflows your talent team is actually asking for, without burning engineering sprints on point-to-point integration code.