Connect Humi by Employment Hero to AI Agents: Sync HR & Work Logs

You want to connect Humi by Employment Hero to an AI agent so your system can independently read employee directories, sync approved time off, generate payroll reports, and log hours worked 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 HRIS API wrapper from scratch.

Giving a Large Language Model (LLM) read and write access to your Humi instance is an engineering liability if done poorly. You either spend weeks building, hosting, and maintaining custom REST connectors to normalize complex JSON:API structures, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Humi by Employment Hero to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Humi by Employment Hero 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 Humi by Employment Hero, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex HR and payroll workflows safely. For a broader 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 Humi API

Giving an LLM access to external HR data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in a tool decorator. Against complex, heavily structured HR platforms like Humi by Employment Hero, this approach breaks down quickly in production.

Humi's API introduces several specific integration challenges. If you hardcode these interactions into your agent's system prompt, you will spend your sprints writing defensive string-parsing code instead of improving your model's reasoning capabilities.

The JSON:API Specification Trap

Humi by Employment Hero strictly adheres to the JSON:API specification. Standard LLMs are trained to expect flat, intuitive JSON objects. When an agent wants to fetch an employee and their salary data, it naturally expects a payload where the salary is a nested object inside the employee record.

Humi does not structure data this way. The API returns a highly structured JSON:API document. If you want salary data or custom fields, you must append include=salaries,custom_attributes to your query. Humi then returns a payload with a data.relationships map and a separate, top-level included array containing the actual salary records. Your agent has to understand how to map the IDs from the relationships object to the entities in the included array. LLMs are notoriously bad at resolving JSON:API references across large payloads, leading to frequent hallucinations where salaries are attributed to the wrong employee.

Destructive Defaults on Payroll Writes

Agent safety is the primary concern when executing API writes. Humi's Employee Time Worked endpoint contains a highly destructive default behavior. When recording time worked on open payrolls, the endpoint accepts a reset boolean parameter.

Humi defaults this parameter to true.

If your agent calls this endpoint and forgets to explicitly set reset=false, the API will silently destroy all previous time worked entries on the open payroll for that employee before inserting the new one. Providing raw access to this endpoint guarantees that a slightly ambiguous prompt will eventually wipe out an entire week of logged hours.

Silent Failures on Invalid Tokens

Humi labels endpoints like the Employee Index as a closed beta. When your OAuth token expires, or if the token lacks the exact scopes required for these beta endpoints, Humi does not return a descriptive JSON error payload indicating an invalid grant or missing scope. Instead, it returns a hard 401 Unauthorized with an empty body.

If your agent receives an empty string instead of a structured error, it cannot reason about why the request failed. It will often hallucinate that the directory is simply empty, or it will attempt to parse the empty string as JSON and crash the tool execution loop.

Hero Tools for Humi by Employment Hero

To prevent the LLM from wrestling with JSON:API references and destructive defaults, you must restrict its access to explicitly defined, schema-bound tools. By routing requests through Truto's Proxy API layer, your agent interacts with a flat, predictable JSON schema. Truto handles the underlying authentication and query parameter processing automatically.

Here are the critical tools to expose to your agent for Humi by Employment Hero workflows.

list_all_humi_by_employment_hero_employees

This tool retrieves a paginated list of employees from the Humi company behind the connected token. It strips away the JSON:API boilerplate and presents flat objects containing essential attributes like legal names, emails, departments, and employment types. It automatically handles the limit and next_cursor logic.

"Fetch a list of all active employees in the engineering department and return their work email addresses."

get_single_humi_by_employment_hero_employee_by_id

When you need deep context on a specific individual, this tool retrieves a single employee by their UUID. Crucially, the tool schema is pre-configured to handle the include relationships. When invoked, it maps the top-level included array back into the employee record, presenting the LLM with a unified view of the employee, their manager (reports_to_id), and their salary history.

"Look up the employee record for ID 123e4567-e89b-12d3-a456-426614174000 and tell me who they report to."

list_all_humi_by_employment_hero_time_off_requests

This tool queries company-wide approved time off within a specific date range. Humi requires exact YYYY-MM-DD formatting and expects nested dateRange [start] queries. This tool flattens those requirements into simple start and end string arguments. It only returns approved requests, preventing the agent from acting on pending or denied leave.

"Generate a list of all approved employee time off requests that overlap with the first week of December."

list_all_humi_by_employment_hero_employee_time_off_requests

Similar to the company-wide tool, this focuses on a single employee's approved leave. It requires the employee's UUID and the date boundaries. This is vital for capacity planning workflows where the agent needs to verify an individual's availability before assigning project tasks.

"Check if employee ID 550e8400-e29b-41d4-a716-446655440000 has any approved time off during the upcoming sprint from October 1st to October 14th."

list_all_humi_by_employment_hero_additional_incomes

Before you can write custom payroll data (like bonuses or holiday pay), you must know the exact additional_income ID for that specific company. Humi uses standard names (e.g., holiday_pay), but the internal IDs differ per company. This tool fetches the machine-readable names and their corresponding UUIDs, allowing the agent to dynamically resolve IDs before writing to payroll.

"Retrieve the list of additional income types for this company and find the specific ID associated with 'holiday_pay'."

create_a_humi_by_employment_hero_employee_time_worked

This tool allows the agent to log hours into open payrolls. To protect your data, the schema definition for this tool strictly requires the reset parameter and enforces a default of false at the schema level, ensuring the LLM cannot accidentally overwrite existing time entries unless explicitly commanded to do so.

"Record 4 hours of overtime for employee ID 993e4567-e89b-12d3-a456-426614174000. Ensure you do not overwrite their existing time entries for this payroll cycle."

To view the complete inventory of available Humi tools, required parameters, and strict JSON schemas, visit the Humi by Employment Hero integration page.

Workflows in Action

Exposing tools to an LLM is only useful if the model can chain them together to solve actual business problems. Here is how an AI agent uses these specific tools to execute complex, multi-step operations autonomously.

Automating End-of-Month Time Off Audits

IT and HR admins frequently waste hours reconciling time off calendars with external project management systems. An agent can automate this reconciliation.

"Generate a capacity report for the engineering department for the month of November. Find all employees in engineering, check their approved time off for November, and summarize how many days each person will be out of the office."

1. list_all_humi_by_employment_hero_employees: The agent calls this tool, iterating through the paginated results to identify all users where the department attribute matches "engineering".
2. list_all_humi_by_employment_hero_time_off_requests: The agent calls this tool using 2024-11-01 as the start date and 2024-11-30 as the end date.
3. Data Processing: The agent cross-references the employee IDs from step 1 with the approved requests from step 2, summing the total_amount_days attribute for each matching record.
4. Final Output: The agent returns a clean markdown table summarizing the upcoming capacity reduction per engineer, ready to be posted into a Slack channel or Notion doc.

Logging Holiday Pay to Open Payrolls

When a manager approves ad-hoc holiday pay via an internal system, manually keying that data into Humi is prone to error. An agent can handle the end-to-end data entry safely.

"Log 8 hours of holiday pay for John Doe. Find his employee ID, look up the correct income type ID for holiday pay, and add the time worked to his current open payroll without deleting his regular hours."

1. list_all_humi_by_employment_hero_employees: The agent searches the directory to locate the UUID for "John Doe".
2. list_all_humi_by_employment_hero_additional_incomes: The agent queries the company's payroll configuration to find the specific UUID mapping to the holiday_pay machine-readable name.
3. create_a_humi_by_employment_hero_employee_time_worked: The agent submits the payload using John Doe's UUID, the holiday pay UUID, the 8-hour value, and explicitly sets reset: false to preserve his existing time entries.
4. Final Output: The agent returns a confirmation message detailing the successful 202 Accepted response and the resulting time worked record ID.

Building Multi-Step Workflows

To build these autonomous loops, you must programmatically fetch the Humi tool schemas from Truto and bind them to your LLM framework. This approach is completely framework-agnostic. Whether you use LangChain, LangGraph, the Vercel AI SDK, or CrewAI, the underlying mechanics rely on standard function calling.

The architecture looks like this:

graph TD
    Agent["AI Agent (LangChain/Vercel)"]
    TrutoTools["Truto /tools API"]
    TrutoProxy["Truto Proxy API"]
    Humi["Humi by Employment Hero API"]

    Agent -->|"1. Fetch schemas on boot"| TrutoTools
    TrutoTools -.->|"Returns JSON Schema"| Agent
    Agent -->|"2. LLM decides to call tool"| TrutoProxy
    TrutoProxy -->|"3. Injects Auth & Normalizes"| Humi
    Humi -.->|"4. Returns raw JSON:API"| TrutoProxy
    TrutoProxy -.->|"5. Flattens data"| Agent

Fetching and Binding Tools

Using the Truto SDK, you dynamically retrieve the tools associated with a specific user's connected Humi account. This ensures the LLM only attempts to use tools that the underlying API token has scopes for.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
async function runHumiAgent(prompt: string, integratedAccountId: string) {
  // 1. Initialize the Truto Tool Manager with your API key
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch the tools dynamically for the connected Humi account
  // You can optionally filter by methods (e.g., read-only tools)
  const tools = await toolManager.getTools(integratedAccountId);
 
  // 3. Initialize your LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Bind the tools to the model
  const promptTemplate = ChatPromptTemplate.fromMessages([
    ["system", "You are an autonomous HR operations assistant. You have access to Humi by Employment Hero. Always verify employee IDs before making payroll writes. Never overwrite existing time entries unless explicitly told to."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt: promptTemplate,
  });
 
  // 5. Execute the agent loop
  const agentExecutor = new AgentExecutor({
    agent,
    tools,
  });
 
  try {
    const result = await agentExecutor.invoke({
      input: prompt,
    });
    console.log("Agent Output:", result.output);
  } catch (error) {
    handleAgentError(error);
  }
}

Handling API Rate Limits

When deploying AI agents to production, you must build robust error handling. LLMs can execute commands extremely fast. If an agent loops through hundreds of employees calling get_single_humi_by_employment_hero_employee_by_id, it will inevitably hit Humi's rate limits.

Truto does not silently absorb rate limits or apply automated backoff on your behalf. When the upstream Humi API returns an HTTP 429 Too Many Requests error, Truto immediately passes that 429 directly back to your caller.

However, Truto standardizes the rate limit information so you don't have to parse vendor-specific headers. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

You are responsible for implementing the retry and backoff logic in your execution loop. Your system should catch the 429 error, read the ratelimit-reset header to know exactly how many seconds to pause the agent, and resume execution once the window resets. This prevents the agent from infinitely spinning and consuming token context while waiting for the API to recover.

Strategic Wrap-Up

Connecting AI agents to Humi by Employment Hero requires precision. The underlying API enforces strict JSON:API structural rules and contains endpoints with destructive defaults that are hazardous to autonomous loops.

By leveraging Truto's /tools endpoint, you abstract away the complexities of token management, pagination, and relationship mapping. You provide your LLM with a stable, schema-bound interface that isolates it from API quirks, drastically reducing hallucination rates and preventing catastrophic data overwrites. Whether you are automating time-off audits or writing custom payroll data, a unified tool layer is the only viable path to safe, production-grade agentic workflows.