canonical: https://jentic.com/apis/merge.dev/merge

# Merge HRIS

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.

## For AI 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.

## Scope

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.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: Call POST `/hris/v1/passthrough` with method 'GET' and path '/v1/custom-reports' for the linked account, then return the provider response

## Key endpoints

| 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 |

## Key resources

- **Employees** — Normalised employee records with employment, manager, team, and location links
- **Payroll** — Payroll runs, employee payroll runs, pay groups, and bank info
- **Time off** — Time-off requests and balances
- **Timesheet entries** — Hours logged per employee
- **Org structure** — Companies, groups, and locations
- **Linked accounts** — Customer connections with link tokens, sync status, scopes, and field mappings

## AI readiness

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.

- **Score:** 50 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 48 / 100
  - Developer Experience & Jentic Compatibility: 56 / 100
  - AI-Readiness & Agent Experience: 32 / 100
  - Agent Usability: 92 / 100
  - Security: 60 / 100
  - AI Discoverability: 51 / 100
- **View full report:** https://jentic.com/apis/merge.dev/merge/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **Finch API** — Unified employment API for HRIS and payroll data
- **Kombo API** — Unified HR and ATS API with a European integration focus
- **Apideck HRIS API** — Unified HRIS API for employees, departments, and payrolls
- **BambooHR API** — Direct API for the BambooHR HR system

## FAQ

### 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.