HR, Payroll, and Directory Unified API Reference

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

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

https://api-ap.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".

View guide

X-Account-TokenString

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

View guide

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.

Popular SDKs

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.