IRIS HR API
★ Only Publicly Available OpenAPI DocumentHR recruitingEmployee Managementoauth234 EndpointsREST
For 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.
Use for: Get a list of all employees in our IRIS HR tenant, Find an employee by ID and pull their job and bank details, Create a new employee record for a recent hire, Update an employee's job title and start date
Not supported: Does not handle payroll calculations, time-tracking, or recruiting workflows - use for IRIS HR people-data and hierarchy management only.
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.
Install Jentic One Beta
Connect the IRIS HR API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the IRIS HR API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Firis.co.uk%2Firis" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Firis.co.uk%2Firis" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with IRIS HR API.
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
Patterns agents use IRIS HR API for, with concrete tasks.
★ 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.
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.
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.
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.
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
34 endpoints — 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.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using IRIS HR API through Jentic.
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.
GET STARTED