--- title: Humi by Employment Hero API Integration on Truto slug: humi category: HRIS canonical: "https://truto.one/integrations/detail/humi/" --- # Humi by Employment Hero API Integration on Truto **Category:** HRIS **Status:** Beta ## Unified APIs ### Unified HRIS API - **Employee Compensations** — Represent the compensation configuration for an Employee - **Employees** — Represents an employee in HRIS - **Employments** — Employments represent a job position at a company. - **Timeoff Requests** — Represent the time off requests for an Employee ## MCP-ready AI tools Truto exposes 6 tools for Humi by Employment Hero that AI agents can call directly. - **list_all_humi_by_employment_hero_employees** — List the employees of the Humi company behind the connected token (Humi Partners API, Employee Index). Each record is a JSON:API resource: id, type (employees) and attributes (first/last name, legal names, email, phones, department, position, office, employment_type, start_date, end_date, created_at, updated_at). Deleted employees are not returned. Oldest created_at first; at most 25 per page (use limit and next_cursor). For one employee with manager, salaries or custom fields, use employees.get. Humi labels this API a closed beta; an invalid or revoked token gets a 401 with an empty body. - **get_single_humi_by_employment_hero_employee_by_id** — Get one employee by their Humi employee id, a uuid (Humi Partners API, Employee Show). Returns the whole JSON:API document, not only the record: data (id, type, attributes including reports_to_id, the id of the employee this one reports to), jsonapi and meta. Set include to salaries, custom_attributes or both (comma-separated) to also get data.relationships and a top-level included array: salary records (name, rate, frequency, is_primary, effective_at, ends_at) and custom field values (name, value, type, field_group). Deleted employees are not returned. - **list_all_humi_by_employment_hero_time_off_requests** — List APPROVED time off requests company-wide that overlap a date range (Humi Partners API, Time Off Index). Required: date_range_start and date_range_end (YYYY-MM-DD), sent as dateRange[start] and dateRange[end]. A request matches when its start_at, end_at or any day between falls in the range. Pending and denied requests are never returned. Records: id, type (timeOffRequest), attributes (employee_id, type, start_at, end_at, status, description, total_amount_days, total_amount_hours, created_at, updated_at). Newest updated_at first; at most 25 per page. Re-send both dates with next_cursor. - **list_all_humi_by_employment_hero_employee_time_off_requests** — List one employee's APPROVED time off requests that overlap a date range (Humi Partners API, Time Off Show). Required: employee_id (Humi employee uuid), date_range_start and date_range_end (YYYY-MM-DD, sent as dateRange[start] and dateRange[end]). Same matching rule, records (id, type, attributes with employee_id, start_at, end_at, status, day and hour totals, timestamps), order (newest updated_at first) and paging (at most 25 per page) as time_off_requests.list. Re-send all three inputs with next_cursor. - **list_all_humi_by_employment_hero_additional_incomes** — List the company's payroll additional income types (Humi Partners API, Additional Incomes Index). Humi returns the same standard list for every company, but the ids are company-specific: use them as the additional income ids in employee_time_worked.create. Records: id, type (additionalIncome), attributes.name (machine-readable, e.g. holiday_pay) and attributes.displayName. Takes no query parameters; not paginated. - **create_a_humi_by_employment_hero_employee_time_worked** — Record time worked for ONE employee on Humi's open payrolls (Humi Partners API, Employee Time Worked). WARNING: reset defaults to true, and Humi says true "will destroy all previous time worked entries on open payrolls". Send reset=false unless you mean to replace them; send an entry's id to update it. Additional income ids come from additional_incomes.list. Humi answers 202 Accepted with employee_id and time_worked (id, start_time, end_time, line_items with rate_id, name, hours, overtime_hours, amount). Amounts are calculated out-of-band (eventually consistent) and may not be final yet. ## How it works 1. **Link your customer's Humi by Employment Hero account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Humi by Employment Hero.** The Proxy API is a 1-to-1 mapping of the Humi by Employment Hero API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate HR-driven user provisioning for Canadian SMEs** — IT, identity, and asset management platforms can treat Humi as the source of truth for the employee roster, triggering account creation, license assignment, and offboarding based on start and end dates sourced from Humi. - **Push time-worked data into Humi payroll runs** — Time-tracking, scheduling, and POS platforms can eliminate manual payroll entry for Canadian customers by mapping internal hour types to Humi's additional income categories and writing finalized hours directly into open payrolls. - **Block scheduling conflicts with approved time off** — Shift scheduling and project management tools can pull approved, date-bound time-off requests from Humi to prevent assigning work to employees who are on vacation or leave. - **Build workforce cost models from compensation data** — FP&A and HR analytics platforms can sync employee salary arrays, pay frequencies, and manager relationships from Humi to generate real-time headcount cost projections and budget variance alerts. - **Unify Canadian HRIS data alongside global providers** — Products already using Truto's Unified HRIS API can add Humi coverage without writing Canada-specific logic, serving customers who standardized on Humi for CRA compliance, T4s, and bilingual workflows. ## What you can build - **Scheduled employee roster sync** — Paginate through Humi employees and hydrate individual records by UUID to maintain a current directory with departments, employment types, and manager relationships. - **Approved time-off calendar overlay** — Query Humi time-off requests by date range to surface only approved leave with precise day and hour totals inside your scheduling or planning UI. - **Automated payroll hours export** — At the end of each pay period, write employee time-worked entries (regular hours, overtime, and line-item amounts) into Humi's open payroll with safe append behavior. - **Additional income mapping configurator** — Let customers map your internal earning codes (holiday pay, bonuses, stat pay) to their Humi additional income IDs during onboarding so payroll pushes land in the right buckets. - **Compensation history and org chart ingestion** — Extract the salaries array with effective dates and reports_to relationships to power dynamic org charts, workforce planning, and compensation analytics. - **Lifecycle event triggers for onboarding and offboarding** — Detect new hires and terminations by polling employee start and end dates to kick off provisioning, equipment shipping, or access revocation workflows. ## FAQs ### What data can we read from Humi through Truto today? Through the available tools you can list and fetch employees, list time-off requests (globally or per employee), and list additional income types. These map to Truto's Unified HRIS resources for Employees, Employments, Employee Compensations, and Timeoff Requests. ### How does pagination work when syncing the employee directory? Humi's API returns a maximum of 25 records per page. Truto handles pagination for you when listing employees, so you receive a normalized stream without needing to manage page tokens or cursors. ### How do we safely push time-worked entries without wiping existing payroll data? Humi's time-worked endpoint defaults to reset=true, which clears all prior entries on the open payroll. When creating entries via Truto, explicitly set reset=false to append, or pass a specific entry ID to update an existing record. ### Can we filter time-off requests for capacity planning use cases? Yes. Time-off requests can be queried by date_range_start and date_range_end. Humi returns only approved requests that overlap the window, along with calculated total_amount_days and total_amount_hours, so you don't need to filter out pending or denied items client-side. ### How do we access nested data like salaries or manager relationships? The list endpoint returns a lightweight employee record. To get the salaries array (with pay rate, frequency, is_primary, and effective_at) and reports_to_id, fetch the individual employee by UUID using the get single employee tool. ### How do we map our internal earning codes to Humi's payroll? Before writing time-worked entries, list the customer's additional incomes from Humi to retrieve their company-specific IDs (e.g., holiday pay, overtime premiums). Store this mapping per customer and reference the correct IDs when posting line items. ## Related reading - [Connect Humi by Employment Hero to ChatGPT: Manage Payroll & Staff](https://truto.one/blog/connect-humi-by-employment-hero-to-chatgpt-manage-payroll-staff/) — 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. - [Connect Humi by Employment Hero to AI Agents: Sync HR & Work Logs](https://truto.one/blog/connect-humi-by-employment-hero-to-ai-agents-sync-hr-work-logs/) — Learn how to connect Humi by Employment Hero to AI agents. Fetch tools via Truto's API, bind them to LangChain or Vercel AI SDK, and automate HR workflows safely.