canonical: https://jentic.com/apis/iris.co.uk/iris # IRIS HR API The IRIS HR API (formerly Cascade HR) provides programmatic access to core people-data records inside an IRIS HR tenant: employees, jobs, hierarchy nodes, bank details, contracts, salaries, absences, and more. The 34 endpoints cover read and write operations for employee lifecycle data, hierarchical organisational structure, and supporting records, all secured by OAuth 2.0 bearer tokens. JSON request and response bodies make it suitable for HRIS integrations, payroll feeds, and reporting pipelines. ## For AI agents Read and write employee records, jobs, organisational hierarchy, and bank details inside an IRIS HR tenant for HRIS integrations and payroll feeds. Authenticated via OAuth 2.0 bearer tokens. ## Scope Does not handle payroll calculations, time-tracking, or recruiting workflows - use for IRIS HR people-data and hierarchy management only. ## Capabilities - List, create, retrieve, and update employee records in an IRIS HR tenant - Manage jobs and assignments tied to employees, including title, role, and dates - Navigate the organisational hierarchy and resolve the path from any node to the root - Maintain bank details for payroll feeds, with create and update operations - Drive HRIS-to-payroll synchronisations from a single people-data source - Surface employee data into BI tools and downstream HR workflows ## Use cases ### HRIS-to-Payroll Synchronisation Finance teams sync IRIS HR's authoritative employee, job, and bank-detail records into a payroll engine on a fixed cadence. Pulling /employees, /jobs, and /bankdetails on a schedule gives payroll a clean, up-to-date snapshot, avoiding manual exports and re-keying. Typical integration takes a few days for delta handling and error recovery. Example prompt: Call GET /employees, /jobs, and /bankdetails since the last sync timestamp and upsert the records into the payroll system. ### New-Hire Onboarding Automation When a candidate is marked as hired in an ATS, an automation creates the matching employee record in IRIS HR via POST /employees, attaches the job through POST /jobs, and stores bank details. This eliminates the double-entry that typically delays first-day access and payroll setup. Integration is on the order of a week including ATS-side mapping. Example prompt: POST /employees with the new hire's profile, then POST /jobs with start date and title, and POST /bankdetails with payroll information. ### Org Chart and Hierarchy Reporting BI dashboards and people analytics tools build live org charts by walking the IRIS hierarchy via GET /hierarchy, then resolving each node's full path with GET `/hierarchy/{id}/path.` Combined with /employees, this supports headcount-by-team views and span-of-control analysis without exporting CSVs. Example prompt: Walk GET /hierarchy and call `/hierarchy/{id}/path` for each node to build a tree, then join with /employees to produce a headcount-by-team report. ### Agent HR Lookups via Jentic An AI assistant supporting HR ops can answer questions like 'how many employees report into the London office?' by calling IRIS HR through Jentic. The agent searches by intent, Jentic returns the matching operation with its OAuth-protected schema, and the bearer token is injected from the vault at execution. Example prompt: Use Jentic to search for 'list employees in IRIS HR', load the GET /employees operation, and execute it with a hierarchy filter for the London node. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/employees` | List all employees | | POST | `/employees` | Create a new employee | | GET | `/employees/{id}` | Retrieve a specific employee by ID | | PUT | `/employees/{id}` | Update an employee by ID | | GET | `/jobs` | List jobs | | POST | `/jobs` | Create a new job | | GET | `/hierarchy` | List all hierarchy nodes | | GET | `/hierarchy/{id}/path` | Get the path from a hierarchy node to the root | ## Key resources - **Employees** — Create, read, and update employee records and their core people data - **Jobs** — Manage employee jobs, titles, and assignment dates - **Hierarchy** — List hierarchy nodes and resolve hierarchical paths from a node to the root - **Bank Details** — Maintain bank-detail records used by payroll feeds ## Why Jentic - **Setup:** Wiring IRIS HR by hand means implementing the OAuth 2.0 client-credentials flow against api.iris.co.uk, refreshing the bearer token before it expires, and applying it to every call under `/hr/v2.` Through Jentic you install once, import IRIS HR from the API Directory, store the client credentials once, and your agent calls it. - **Permission scoping:** IRIS HR puts the employee id in the URL path (`/employees/{id}`), so a rule can pin your agent to reading and updating specific records: you choose the operations it may call, so creating employees or jobs via POST is not included unless you add it. - **Credential handling:** Your IRIS HR OAuth client credentials are stored once, encrypted, by your own Jentic One instance, which performs the token exchange and applies the bearer to the Authorization header at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list employees in IRIS HR', and Jentic returns the matching operation with its input schema, so the agent runs the right call without scanning the IRIS docs. ## Related APIs - **BambooHR API** — Mid-market HRIS API for employee records, time off, and benefits. - **Gusto API** — U.S.-focused HR and payroll API combining people data with run-payroll endpoints. - **Workday API** — Enterprise HCM API with deep configuration and global payroll coverage. - **Greenhouse API** — ATS API used to feed candidate-to-hire records into IRIS HR. ## FAQ ### What authentication does the IRIS HR API use? IRIS HR uses OAuth 2.0 with bearer tokens on every request. Through Jentic, the OAuth client credentials and refreshed token are stored encrypted in the vault and the bearer is injected at execution time. ### Can I create new employees through the IRIS HR API? Yes. POST /employees creates a new employee record, and POST /jobs attaches a job to the employee. PUT `/employees/{id}` updates an existing record by ID. ### How do I read the organisation's hierarchy? Use GET /hierarchy to list all nodes and GET `/hierarchy/{id}/path` to retrieve the full path from any node back to the root, which gives you each level of the organisational tree. ### What are the rate limits for the IRIS HR API? IRIS does not publish hard per-minute rate limits in the spec; throughput is governed by tenant size and plan. Bulk syncs should run during off-peak hours and use delta filtering rather than full re-fetches. ### How do I list employees through Jentic? Search Jentic for 'list employees in IRIS HR', load the GET /employees operation, and execute it. Jentic exchanges the OAuth credentials for a bearer token and applies it to the request. ### Does IRIS HR expose bank details for payroll feeds? Yes. The /bankdetails resource exposes list and create operations so that payroll engines can read or update employee bank information without going through the IRIS HR UI. ### Can I limit what my agent is allowed to do with the IRIS HR API? Yes. Because you run Jentic One yourself, your own rules decide which IRIS HR operations and credentials the agent may use. Since IRIS HR carries the employee id in the URL path, such as `/employees/{id}`, you can pin the agent to reading and updating specific records with GET and PUT while leaving out creation, so POST /employees and POST /jobs are unavailable unless you explicitly add them. The stored OAuth credentials are applied only to the calls you have allowed, so the agent cannot reach operations or bank-detail writes you have not enabled.