canonical: https://jentic.com/apis/humi.ca/humi # Humi Ca Humi Partners API The Humi Partners API gives third-party applications read access to employee and time-off data on a Humi HR account. It follows the JSON:API specification and is gated by per-token scopes so a partner integration only sees the data its customer authorised. The current surface covers listing employees, fetching a single employee record, and reading time-off entries either across the company or scoped to one employee. ## For AI agents Read Humi employee records and time-off entries through the partner API, scoped by the customer-issued token. ## Scope Does not run payroll, edit employee records, or manage benefits - use for read-only Humi employee and time-off retrieval only. ## Capabilities - List every employee on a Humi account that the partner token can see - Retrieve a single employee record by Humi employee ID - List all time-off entries across the company within the token's scope - List time-off entries for a specific employee by ID - Iterate through paginated employee and time-off results following JSON:API cursors ## Use cases ### Roster sync into a partner application Mirror the customer's Humi employee directory into a partner application - for example a benefits platform or learning system - so the customer does not have to maintain two rosters. The list endpoint returns paginated employee records following JSON:API conventions, which the partner walks once on connect and then refreshes on a schedule. Example prompt: Call GET `/v1/employees`, follow the JSON:API next-page links until exhausted, and upsert each record into the partner system keyed by Humi employee ID. ### Time-off-aware scheduling Read approved time-off from Humi so a downstream scheduling, payroll, or project management tool can avoid scheduling people who are out. The time-off endpoints support both a global view and per-employee filtering so the partner system can refresh efficiently when only one person's plans change. Example prompt: Call GET `/v1/timeoff/{employeeId}` for the employee, then exclude their unavailable dates from the scheduling tool's allocation grid. ### Compliance and headcount reporting Pull the Humi employee list as a periodic snapshot for compliance reporting or headcount dashboards that need an authoritative HR source. Because the API enforces partner-token scopes, only the data the customer has authorised flows out, which keeps audit boundaries tidy. Example prompt: Call GET `/v1/employees`, snapshot the result with a timestamp, and emit a row per employee into the reporting warehouse. ### Agent-driven Humi reads through Jentic An agent fielding HR questions like 'who is out next Friday?' uses Jentic to find the Humi time-off operation, loads the schema, and returns the answer. Jentic injects the customer-issued partner token from the vault so the agent never sees the raw credential. Example prompt: Through Jentic, search 'list Humi time-off', load the schema for GET `/v1/timeoff`, and execute it filtered to the requested date range. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v1/employees` | List employees on the account | | GET | `/v1/employees/{employeeId}` | Retrieve a single employee record | | GET | `/v1/timeoff` | List all time-off entries | | GET | `/v1/timeoff/{employeeId}` | List time-off entries for a single employee | ## Key resources - **Employees** — List employees and fetch single employee records - **Time-off** — List time-off entries either across the company or scoped to one employee ## Why Jentic - **Setup:** Wiring the Humi Partners API by hand means holding a partner bearer token, targeting partners.humi.ca, and paging employee and time-off reads per customer install yourself. Through Jentic you install once, import the Humi Partners API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** This API puts the employee id in the URL path (`/v1/employees/{employeeId}`, `/v1/timeoff/{employeeId}`), so a rule can pin your agent to one employee: it can read that employee's record and time-off and nothing else. Every operation here is read-only, so the agent cannot change any Humi data whatever you allow. - **Credential handling:** Your Humi partner token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list Humi employees' or 'list Humi time-off', and Jentic returns the matching partner operation with its input schema, including pagination and per-employee filters, so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **BambooHR** — Mid-market HRIS with broader read and write coverage of employee data - **Rippling** — All-in-one HR, IT, and finance platform with deeper API surface across modules - **Deel** — Global HR and contractor management with strong international payroll coverage - **Gusto** — US-focused payroll provider commonly paired with HR data sources for the pay run ## FAQ ### What authentication does the Humi Partners API use? Each customer issues a Humi partner token from their account, and the partner sends it as a Bearer header. Through Jentic the per-customer token sits in your encrypted Jentic One instance and is injected at execution time so the agent never holds the raw token. ### Can I write back to Humi through this API? No. The Humi Partners API is read-only - it covers listing employees, fetching a single employee, and reading time-off entries. Writes happen inside Humi's own UI or admin surfaces. ### What are the rate limits for the Humi Partners API? Humi applies per-token rate limits and recommends keeping calls under a few requests per second. Use JSON:API pagination rather than retry storms when walking the full employee list. ### How do I list time-off through Jentic? Search Jentic for 'list Humi time-off', load the schema for GET `/v1/timeoff`, and execute it. Jentic returns the parsed JSON:API resource collection with pagination cursors ready for the agent to iterate. ### Does the API expose payroll or pay-stub data? No. Pay-related fields are not exposed on the partner API. The current surface is limited to employee directory fields and time-off entries. ### Why are some employees missing from my list response? The partner token's scope is set by the customer when they install the integration. If specific employees are missing, the customer needs to broaden the integration's scope inside Humi before they appear in API responses. ### Can I limit what my agent is allowed to do with the Humi Partners API? Yes. Because you run Jentic One yourself, your own rules decide which Humi operations and credentials the agent may use. Since this API carries the employee ID in the URL path, such as GET `/v1/employees/{employeeId}` and GET `/v1/timeoff/{employeeId}`, you can pin the agent to a single employee so it reads only that person's record and time-off and nothing else. Every Humi Partners operation is read-only, so the agent can list and fetch employee and time-off data but cannot change anything in Humi whatever you permit.