---
title: "Connect Humi by Employment Hero to ChatGPT: Manage Payroll & Staff"
slug: connect-humi-by-employment-hero-to-chatgpt-manage-payroll-staff
date: 2026-10-01
author: Roopendra Talekar
categories: ["AI & Agents"]
excerpt: "Learn how to connect Humi by Employment Hero to ChatGPT using a managed MCP server. Automate payroll entries, audit employee data, and query time-off balances."
tldr: "Connect Humi by Employment Hero to ChatGPT via Truto's managed MCP server to automate HR workflows. This guide covers bypassing Humi's JSON:API quirks, safely handling destructive payroll endpoints, and configuring secure AI agent access."
canonical: https://truto.one/blog/connect-humi-by-employment-hero-to-chatgpt-manage-payroll-staff/
---

# Connect Humi by Employment Hero to ChatGPT: Manage Payroll & Staff


If you need to connect Humi by Employment Hero to ChatGPT to automate payroll logging, audit employee directories, or track time-off balances, you need a [Model Context Protocol (MCP) server](https://truto.one/blog/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between ChatGPT's JSON-RPC tool calls and Humi's specific REST architecture.

If your team uses Claude, check out our guide on [connecting Humi by Employment Hero to Claude](https://truto.one/connect-humi-by-employment-hero-to-claude-track-time-off-records/) or explore our broader architectural overview on [connecting Humi by Employment Hero to AI Agents](https://truto.one/connect-humi-by-employment-hero-to-ai-agents-sync-hr-work-logs/).

Giving a Large Language Model (LLM) read and write access to a core [Human Resources Information System (HRIS)](https://truto.one/blog/the-2026-hris-unified-api-buying-guide-cheat-sheet-for-pms/) like Humi is a high-stakes engineering challenge. You must handle complex, nested JSON:API payload structures, navigate highly destructive default parameters on payroll endpoints, and map human concepts (like "Holiday Pay") to company-specific UUIDs before the LLM can write data.

This guide breaks down exactly how to use Truto to generate a secure, managed [MCP server for Humi](https://truto.one/blog/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/), connect it natively to ChatGPT, and execute complex HR workflows using natural language.

::cta{buttonText="Talk to us" buttonUrl="/book-a-demo/"}
Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds.
:::

## The Engineering Reality of the Humi API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, implementing it against Humi's highly specific API is exceptionally painful. 

If you decide to build a custom MCP server for Humi by Employment Hero, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with this platform:

### 1. Strict JSON:API Compliance and the `include` Pattern
Humi adheres strictly to the JSON:API specification. Responses do not come back as simple flat objects. Instead, they are returned as documents containing `data`, `jsonapi`, and `meta` objects. 

If an LLM asks "Who is this employee's manager and what is their salary?", standard endpoints will not return this data by default. Your MCP server must know to inject the `include=salaries,custom_attributes` query parameter. When it does, the relational data is not nested inside the employee object. It is returned in a top-level `included` array alongside a `data.relationships` mapping. You either have to teach the LLM how to parse JSON:API reference mappings, or write custom middleware in your MCP server to flatten this response before handing it to ChatGPT.

### 2. Destructive Defaults on Payroll Endpoints
When writing to the Humi Partners API, specifically the Employee Time Worked endpoint, Humi defaults the `reset` parameter to `true`. 

According to Humi's documentation, passing `true` (or omitting the parameter entirely) "will destroy all previous time worked entries on open payrolls" for that employee. If you expose this raw endpoint to an LLM without strict schema validation or custom overrides, a simple prompt like "Log 8 hours for John today" will wipe out John's entire week of previously logged hours. Your MCP server must actively intercept this and default `reset` to `false` unless explicit replacement is requested.

### 3. Company-Specific IDs for Standard Types
When dealing with additional incomes (like Holiday Pay, Overtime, or Bonuses), Humi returns the same standard list of human-readable names for every company. However, the UUIDs for these income types are unique to each specific company instance.

An LLM cannot simply inject `type: "holiday_pay"` into a payroll POST request. It must first call the Additional Incomes Index, map the machine-readable string to the company-specific UUID, and then construct the payroll payload. This requires your MCP server to orchestrate multi-step tool calling effectively.

### 4. Opaque Errors on Closed Beta Endpoints
Humi labels several of its core Partner APIs as closed betas. If your authentication token is invalid, revoked, or if the specific Humi account has not been granted beta access to that specific endpoint, Humi does not return a helpful error message. It returns a 401 Unauthorized with a completely empty body. Your MCP server must be prepared to catch empty 401s and translate them into actionable errors for the LLM, otherwise the agent will infinitely retry a blank response.

## Rate Limits and Upstream Behavior

When connecting AI agents to Humi, rate limiting is a primary concern. LLMs execute loops, retries, and rapid sequential requests that easily trip standard API quotas.

**Factual note on rate limits:** Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Humi API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. 

What Truto *does* do is normalize the upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) following the IETF specification. The caller - whether that is your custom code or the ChatGPT framework - is entirely responsible for detecting the 429 and implementing appropriate retry and exponential backoff logic. Truto will not absorb these errors for you.

## Generating a Humi MCP Server via Truto

Truto's MCP server feature turns any connected Humi instance into an MCP-compatible JSON-RPC endpoint. Rather than hand-coding tool definitions for Humi's JSON:API endpoints, Truto derives them dynamically from existing integration resource definitions and documentation schemas.

Each MCP server is scoped to a single integrated account. The server URL contains a cryptographic token that encodes the account, the exposed tools, and the expiration parameters. 

You can generate this server via the Truto UI or programmatically via the API.

### Method 1: Via the Truto UI

If you are setting this up manually for an internal ChatGPT Workspace:

1. Navigate to the **Integrated Accounts** page in the Truto dashboard.
2. Select your connected Humi by Employment Hero account.
3. Click the **MCP Servers** tab.
4. Click **Create MCP Server**.
5. Select your desired configuration (e.g., restrict to `read` methods only, or filter by specific tags like `payroll`).
6. Copy the generated MCP server URL (it will look like `https://api.truto.one/mcp/<token>`).

### Method 2: Via the Truto API

If you are provisioning AI capabilities for your [own B2B SaaS customers](https://truto.one/blog/how-to-architect-a-multi-tenant-mcp-server-for-enterprise-b2b-saas/), you will generate this URL programmatically. 

Make a `POST` request to `/integrated-account/:id/mcp`. You can pass a configuration object to strictly limit what the LLM is allowed to do.

```bash
curl -X POST https://api.truto.one/integrated-account/<YOUR_INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Humi Payroll Agent MCP",
    "config": {
      "methods": ["read", "create"],
      "tags": ["employees", "payroll", "time_off"]
    }
  }'
```

The API validates that the Humi integration has available tools matching your filters, generates a secure, hashed token stored at the edge, and returns the URL:

```json
{
  "id": "abc-123",
  "name": "Humi Payroll Agent MCP",
  "config": { "methods": ["read", "create"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}
```

Treat this URL as a highly sensitive secret. Possession of the URL grants execution rights to the configured tools against that specific Humi account.

## Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, you must register it with ChatGPT. 

### Method A: Via the ChatGPT UI

For users on ChatGPT Pro, Plus, Business, Enterprise, or Education tiers:

1. Open ChatGPT and navigate to **Settings -> Apps -> Advanced settings**.
2. Toggle on **Developer mode**.
3. Under **MCP servers / Custom connectors**, click to add a new server.
4. Enter a name (e.g., "Humi HRIS").
5. Paste the Truto MCP URL into the **Server URL** field.
6. Click **Save**.

ChatGPT will immediately perform an MCP handshake, calling the `initialize` and `tools/list` JSON-RPC methods, and populate the available Humi tools into its context window.

### Method B: Via Config File (Custom Agents / Local Dev)

If you are building a custom wrapper around OpenAI's API, or using a local framework that supports standard MCP configurations (like Cursor or Claude Desktop), you configure the server using a Server-Sent Events (SSE) client transport.

Add the following to your agent's MCP configuration JSON:

```json
{
  "mcpServers": {
    "humi_hris": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}
```

## Humi by Employment Hero: Hero Tools

When the MCP server initializes, Truto dynamically generates descriptive snake_case tool names based on Humi's API definitions. 

Here are the highest-leverage tools exposed to your LLM for HR and Payroll operations. *(Note: Truto combines query and body parameters into a single flat input namespace for the LLM, handling the routing automatically).* 

### list_all_humi_by_employment_hero_employees

Retrieves a paginated list of employees. Because Humi uses company-specific UUIDs for almost all write operations, this tool is the required first step for any agent workflow targeting a specific person.

**Context note:** This returns a standard JSON:API array. Deleted employees are filtered out by the upstream API. It supports pagination via `limit` and `next_cursor`.

> "Get a list of all active employees in the engineering department and give me their names, employment types, and internal Humi IDs."

### get_single_humi_by_employment_hero_employee_by_id

Retrieves deep relational data for a single employee using their UUID. 

**Context note:** This is where the JSON:API `include` pattern is handled. The agent can pass `include=salaries` or `include=custom_attributes` to get relational data. The response will include a `data.relationships` mapping and a top-level `included` array containing the salary records (rate, frequency, effective dates).

> "Look up the employee profile for ID 8f72a4b1 and include their current salary records and manager reporting structure."

### list_all_humi_by_employment_hero_time_off_requests

Queries company-wide approved leave that overlaps with a specific date range. 

**Context note:** This requires `date_range_start` and `date_range_end` formatted as `YYYY-MM-DD`. Pending and denied requests are silently excluded by Humi. This is critical for capacity planning workflows.

> "Check the company time-off requests to see who is on approved leave between October 1st and October 15th."

### list_all_humi_by_employment_hero_additional_incomes

Fetches the mapping of machine-readable income types to their company-specific UUIDs.

**Context note:** As mentioned in the Engineering Reality section, the LLM *must* call this tool before attempting to log custom payroll entries, so it can map strings like `holiday_pay` to the correct UUID for the `create_a_humi_by_employment_hero_employee_time_worked` tool.

> "List the available additional income types for this company so we can find the exact ID for overtime pay."

### create_a_humi_by_employment_hero_employee_time_worked

Records time worked or additional income on Humi's open payrolls.

**Context note:** **DANGER.** As documented by Humi, this endpoint defaults to destroying all previous entries if not handled correctly. Instruct your agent to *always* pass `reset: false` unless a complete replacement is intended.

> "Log 4 hours of overtime for employee ID 8f72a4b1 using the overtime income ID. Ensure you set reset to false so we don't delete their standard hours for the week."

---

*To view the complete schema definitions and the full inventory of available Humi tools (including webhooks and document management), visit the [Humi by Employment Hero integration page](https://truto.one/integrations/detail/humi).* 

## Workflows in Action

With the MCP server connected to ChatGPT, complex HR scenarios that used to require custom scripts can now be executed conversationally. Here is how the LLM orchestrates multi-step workflows across the Humi API.

### Scenario 1: Auditing Salary and Reporting Structures

HR teams frequently need to audit reporting lines and compensation bands. 

> "Find the employee record for Sarah Jenkins. Tell me who she reports to, and list out her active salary history."

**Execution Steps:**
1.  ChatGPT calls `list_all_humi_by_employment_hero_employees` to search the directory and locate the UUID for "Sarah Jenkins".
2.  ChatGPT calls `get_single_humi_by_employment_hero_employee_by_id`, passing Sarah's UUID and the parameter `include=salaries`.
3.  ChatGPT parses the JSON:API response. It reads `reports_to_id` from the main attributes, cross-references it with the directory, and parses the `included` array to extract the salary rate, frequency, and effective dates.

**Result:** The user receives a clean, conversational summary of Sarah's reporting line and her complete compensation history without ever logging into the HRIS.

### Scenario 2: Safe Payroll Data Entry

Logging custom income types requires precise data mapping and careful state management to avoid destroying existing payroll data.

> "Log a $500 holiday bonus for Marcus Thorne. Make sure you don't overwrite his existing logged hours for this open payroll."

**Execution Steps:**
1.  ChatGPT calls `list_all_humi_by_employment_hero_employees` to find the UUID for Marcus Thorne.
2.  ChatGPT calls `list_all_humi_by_employment_hero_additional_incomes` to fetch the company's specific mapping table.
3.  ChatGPT identifies the UUID corresponding to the `holiday_pay` or `bonus` attribute.
4.  ChatGPT calls `create_a_humi_by_employment_hero_employee_time_worked`, passing Marcus's UUID, the bonus UUID as the rate ID, the amount, and critically, explicitly passing `reset: false`.

```mermaid
sequenceDiagram
    participant ChatGPT as ChatGPT
    participant MCP as Truto MCP Server
    participant Humi as Humi API
    
    ChatGPT->>MCP: Call list_incomes
    MCP->>Humi: GET /additional_incomes
    Humi-->>MCP: [{"id": "uuid-1", "name": "bonus"}]
    MCP-->>ChatGPT: Parsed JSON array
    
    ChatGPT->>MCP: Call create_time_worked<br>(reset: false)
    MCP->>Humi: POST /employee_time_worked
    Humi-->>MCP: 202 Accepted
    MCP-->>ChatGPT: Success confirmation
```

**Result:** The bonus is successfully appended to Marcus's open payroll without triggering Humi's destructive default behavior.

### Scenario 3: Sprint Capacity Planning

Engineering managers need to know resource availability before committing to sprint deliverables.

> "Check our approved time off. Who is out of the office between November 1st and November 14th?"

**Execution Steps:**
1.  ChatGPT formulates the date objects for the start and end of the period.
2.  ChatGPT calls `list_all_humi_by_employment_hero_time_off_requests`, passing `date_range_start` and `date_range_end`.
3.  If the response contains more than 25 records, ChatGPT observes the `next_cursor` value and loops the call, passing the dates and the cursor back unaltered.
4.  ChatGPT maps the returned `employee_id` fields to human names (calling the employee list if it doesn't already have them in context) and calculates total overlapping days.

**Result:** The manager receives a bulleted list of team members on leave, specifying exact dates and total hours absent during the sprint window.

## Security and Access Control

Giving an AI agent access to an HRIS requires strict governance. Truto provides multiple layers of security configured at the MCP token level:

*   **Method Filtering:** You can restrict a server to safe operations. By passing `methods: ["read"]` during server creation, Truto will enforce at the generation level that no `create`, `update`, or `delete` tools are ever exposed to the LLM.
*   **Tag Filtering:** You can group tools by functional area. By passing `tags: ["time_off"]`, the LLM will only see tools related to leave management, blocking access to sensitive endpoints like payroll or salaries.
*   **Time-To-Live (`expires_at`):** You can generate short-lived MCP servers by passing an ISO datetime. Truto schedules a durable cleanup alarm that automatically revokes and deletes the server credentials at the exact specified time.
*   **Secondary Auth (`require_api_token_auth`):** By default, the MCP URL is a bearer token. If you enable this flag, the calling client (the agent framework) must *also* provide a valid Truto API token in the Authorization header, adding a second layer of identity verification.

## Final Thoughts

Integrating AI with Humi by Employment Hero unlocks massive operational efficiency, but the specific mechanics of the Humi API - strict JSON:API compliance, destructive payroll defaults, and opaque beta errors - make direct LLM integration risky.

Using Truto's managed MCP servers, you can instantly translate Humi's API into a safe, normalized, and highly-filtered JSON-RPC interface that ChatGPT and Claude understand natively. You maintain complete control over what the AI can see and do, without maintaining a single line of integration infrastructure.

::cta{buttonText="Talk to us" buttonUrl="/book-a-demo/"}
Stop wrestling with JSON:API parsing and destructive defaults. Let Truto generate secure MCP servers for your HR stack today.
:::