Base API URL

Authentication

Header parameters

Merge SDKs

Syncing data

Query parameters

Rate limits

Sync frequency

Testing via Postman

Supported integration fields

Use cases

HR, Payroll, and Directory

Welcome to the Merge HR, Payroll, and Directory (HRIS) API reference documentation! You can use this API to integrate with Merge and pull data from or push data to integrations that your users have authorized.


Base API URL

All API endpoints in the reference documentation are relative to the following base URL:

https://api.merge.dev/api/hris/v1

If you are using our EU tenant, all API endpoints in the reference documentation are relative to the following base URL:

https://api-eu.merge.dev/api/hris/v1

Authentication

When making requests to Merge’s Unified API, you will need to include proper authentication parameters in the headers for every request to Merge’s API to identify yourself as an authorized user.
Header parameters

AuthorizationString
Token-based authentication with required prefix "Bearer".

X-Account-TokenString
Token identifying the end user. This is only required for requests for data specific to a Linked Account.

curl --location 'https://api.merge.dev/api/hris/v1/employees' \

--header 'Accept: application/json' \

--header 'Authorization: Bearer {{production-key}}' \

--header 'X-Account-Token: {{account-token}}'


Merge SDKs

Streamlined way to use Merge APIs, starting with reducing the boilerplate code you have to write. You can find the installation and usage instructions for all of our available SDK's here.

Syncing data

To pull data from Merge into your app, we recommend a combination of webhooks and polling. See our syncing data guide for more information.
Query parameters
GET
/{endpoint}?modified_after={timestamp}

Only pull data that has been changed or created since your last sync began.

For example, you can ask for modified_after=2021-03-30T20:44:18, and only pull items that are new or changed.


GET
/{endpoint}?expand={model_name}

If you expand fields on a Common Model, you will receive data for entire related objects rather than just the IDs of those objects. Do this to avoid making multiple API calls to retrieve each related object.

For example, if you are querying for candidates and also want details about associated applications, you can expand=applications, and Merge will return the actual application objects instead of just the application_ids.

Rate limits
API requests to Merge's Unified API are rate limited to the following per linked account (as identified by the account_token attached to the request):
  • Launch: 100 / minute
  • Professional: 400 / minute
  • Enterprise: 600 / minute
For example, if you have 10 customers, the rate limits above would apply to each one separately. Some endpoints may have different rate limits as specified throughout the API reference.
Sync frequency
Sync frequency is the rate at which Merge initiates requests to fetch data from third-parties. Actual time to complete a sync can vary depending on the third-party. You can view your sync frequency in the integrations section of your Merge dashboard. Contact us for more information.
Highest
Automatic
Data syncs at the highest frequency supported by Merge.
Daily
Automatic
Data syncs every 24 hours.
Monthly
Manual
Quarterly
Manual
Control when you sync data either in your Merge dashboard or via API. Resyncs are limited based on your allocated amount of sync credits.

Testing via Postman

Use Merge's public Postman workspace to get started fast.

Learn best practices for testing in our guide.

Supported integration fields
View fields
See which fields are supported for each integration and compare coverage across platforms.

Look through use cases featuring HR, Payroll, and Directory to understand how your product works with Merge.
Auto-provision and de-provision
HRIS
Automatically assign employee permissions, such as software seats, billing controls, or corporate cards, based on their department, team, or other factors. Revoke access if those parameters change.
Analyze payroll runs
HRIS
Look and analyze the payroll runs of given employees to get granular information per paycheck
Analyze compensation
HRIS
Analyze current compensation of employees based on demographics, pay rate, and potential field custom fields, such as equity