Official vendor OpenAPI document · agent-readyHR recruitingEmployee Managementbearer65 EndpointsREST
For Agents
Read employees, employments, payroll runs, benefits, time-off balances, and org structure from a customer's connected HR system through one normalised model, create time-off requests and timesheet entries, and pass through to provider endpoints the model does not cover.
Use for: List all active employees in the customer's HR system, Find all employees who report to this manager, Check how much vacation balance an employee has left, I need to submit a time-off request for next Friday
Not supported: Does not run payroll, pay employees, or post job openings and track applicants. Use for reading and syncing normalised HR, payroll, and time-off data from connected HR systems only.
The Merge HRIS API returns normalised employee, employment, payroll, benefits, and time-off data from whichever HR or payroll system a customer connects, through one common model. It lists employees with filters such as employment_status, manager_id, team_id, and modified_after, along with companies, groups, locations, pay groups, payroll runs, bank info, and dependents, and it can create time-off requests and timesheet entries in the connected system. Each call targets one linked account through the X-Account-Token header, and a passthrough operation reaches provider endpoints the common model does not cover, with US, EU, and APAC regional hosts available.
Install Jentic One Beta
Connect the HRIS to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the HRIS, 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%2Fmerge.dev%2Fmerge" | 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%2Fmerge.dev%2Fmerge" | 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 HRIS API.
List employees across a connected HR system, filtered by employment_status, manager_id, team_id, work_email, or modified_after
Read payroll runs and each employee's payroll run details from the linked payroll provider
Check time-off balances and create a time-off request for an employee in the connected system
Log hours by creating timesheet entries, after reading the meta endpoint for the fields the provider supports
Read the org structure: companies, groups and group types, locations, and pay groups
Call a provider endpoint the common model does not cover through the passthrough or async passthrough operations
Create a link token to start a customer's connection flow and check sync status for a linked account
Use Cases
Patterns agents use HRIS API for, with concrete tasks.
★ HR assistant agent through Jentic
An internal HR assistant answers employee questions from the company's own HR system. Through Jentic it finds the Merge HRIS operations it needs, reads an employee's time-off balances, and files a time-off request when asked. The Merge bearer key stays in your own Jentic One instance, and your rules decide whether the agent may only read balances or may also create requests.
Call GET /hris/v1/employees with work_email 'sam@example.com' to find the employee id, call GET /hris/v1/time-off-balances for that employee, then POST /hris/v1/time-off with a model containing the employee, request_type 'VACATION', start_time, and end_time
Incremental employee directory sync
Products that need a customer's employee directory keep it in sync without building one integration per HR vendor. The employees list accepts modified_after with cursor pagination, so a nightly job pulls only changed records, and include_deleted_data surfaces removed employees. One linked account is addressed per call through the X-Account-Token header.
Call GET /hris/v1/employees with modified_after '2026-11-08T00:00:00Z' and page_size 100, follow the cursor until exhausted, and return the employee ids and employment_status values
Payroll and benefits reporting
Finance and benefits tools read payroll runs, per-employee payroll run details, employer benefits, and employee benefit enrolments from the connected provider in one normalised shape, so the same report works whether the customer runs one payroll system or another.
Call GET /hris/v1/payroll-runs to find the most recent run, then GET /hris/v1/employee-payroll-runs filtered to that payroll run, and total the gross pay
Reaching provider-specific data with passthrough
When a field or endpoint is not in the common model, the passthrough operation sends a request with a required method and path straight to the underlying provider using the linked account's connection, and async passthrough handles long-running calls with a receipt to poll later.
Call POST /hris/v1/passthrough with method 'GET' and path '/v1/custom-reports' for the linked account, then return the provider response
Key Endpoints
65 endpoints — the merge hris api returns normalised employee, employment, payroll, benefits, and time-off data from whichever hr or payroll system a customer connects, through one common model.
METHOD
PATH
DESCRIPTION
GET
/hris/v1/employees
List employees
GET
/hris/v1/employees/{id}
Retrieve an employee
GET
/hris/v1/time-off-balances
List time-off balances
POST
/hris/v1/time-off
Create a time-off request
GET
/hris/v1/payroll-runs
List payroll runs
POST
/hris/v1/timesheet-entries
Create a timesheet entry
POST
/hris/v1/passthrough
Pass a request through to the provider
POST
/hris/v1/link-token
Create a link token
GET
/hris/v1/employees
List employees
GET
/hris/v1/employees/{id}
Retrieve an employee
GET
/hris/v1/time-off-balances
List time-off balances
POST
/hris/v1/time-off
Create a time-off request
GET
/hris/v1/payroll-runs
List payroll runs
POST
/hris/v1/timesheet-entries
Create a timesheet entry
POST
/hris/v1/passthrough
Pass a request through to the provider
POST
/hris/v1/link-token
Create a link token
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
H
HRIS
- Foundational (D+)50/100
48
Foundational Compliance56
Developer Experience & Jentic Compatibility32
AI-Readiness & Agent Experience92
Agent Usability60
Security51
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.2
Show dimension breakdown
48
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: D+Signals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
0%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
56
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: CSignals: 4
0%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
25%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
32
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
39%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
38%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
52%
Summary Coverage
Coverage of summaries across operations/tags/info.
92
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
92%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
60
Security
Trust, risk posture, and security compliance.
Grade: B-Signals: 1
60%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
51
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: C-Signals: 1
51%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring Merge HRIS by hand means sending your bearer key, adding the right X-Account-Token per customer, picking the US, EU, or APAC host, and reading meta endpoints before writes because supported fields vary by provider. Through Jentic you install once, import Merge HRIS from the API Directory, store the key once, and your agent calls it.
Permission scoping
Merge identifies the customer's linked account through the X-Account-Token header rather than the URL path, so rules bound which operations your agent may call, not which linked account it reads. You choose the operations it may call, so writes and destructive ones like account deletion, key regeneration, or passthrough are not included unless you add them.
Credential isolation
Your Merge API key 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.
Intent-based discovery
Agents search Jentic by intent such as 'list employees from the HR system' or 'check time-off balance', and Jentic returns the matching Merge HRIS operation with its input schema, including filters like employment_status and modified_after, so the agent calls the right endpoint directly.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using HRIS API through Jentic.
What authentication does the Merge HRIS API use?
Per its OpenAPI spec, every Merge HRIS operation uses HTTP bearer auth: your Merge API key goes in the Authorization header with the Bearer prefix. Most data operations, 55 of them, also require an X-Account-Token header identifying the customer's linked account, while organisation-level calls such as creating a link token or regenerating a key do not. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.
Can I create time-off requests with the Merge HRIS API?
Yes. POST /hris/v1/time-off with a model object that can carry employee, approver, status, units, amount, request_type, start_time, and end_time writes a request to the connected HR system. Check GET /hris/v1/time-off/meta/post first, since supported fields vary by provider. Status values include REQUESTED, APPROVED, and DECLINED.
What are the rate limits for the Merge HRIS API?
The OpenAPI spec does not specify numeric rate limits for Merge itself. It does note that a sync can show RATE_LIMITED when the underlying provider's own limits pause it. Check https://docs.merge.dev for Merge's current limits.
Is there a Merge HRIS MCP server?
You don't need an MCP server to give your agent Merge HRIS. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent discovers the employee, payroll, and time-off operations it needs on demand without loading another server's tool definitions into its context.
How do I list a customer's employees through Jentic?
Search Jentic for 'list employees from the HR system', load the GET /hris/v1/employees operation, and execute it with the linked account's X-Account-Token plus filters such as employment_status or modified_after. Follow the cursor for more pages. To run it on your own infrastructure, install Jentic One from its GitHub repo.
Can I limit what my agent is allowed to do with the Merge HRIS API?
Yes. Write a rule that allows only the employees, time-off-balances, and time-off list reads, so the agent can answer leave questions but cannot create time-off requests, use passthrough, or delete a linked account. Every call it makes is logged for review.
Does the Merge HRIS API have EU or APAC endpoints?
Yes. The spec lists three hosts: api.merge.dev for the US, api-eu.merge.dev for the EU, and api-ap.merge.dev for APAC, each under the /api path. Use the host that matches the region your Merge organisation was created in.
GET STARTED