Install & Compatibility
Where this runs
tested against v4.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.748s · 75.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 0.680s · 75MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Merge
✓ from merge import Merge
Merge (legacy clients)
✓ from merge import Merge
✗ import MergeATSClient
Legacy, category-specific SDKs (e.g., MergeATSClient, MergeHRISClient) are deprecated. Use the unified 'mergepythonclient' and import 'Merge' directly.
Resource models (e.g., ActivityRequest)
✓ from merge.resources.ats import ActivityRequest
This quickstart demonstrates how to instantiate the Merge client using API key and account token, and perform a sample API call to create an activity in the ATS category and list employees from the HRIS category. Ensure `MERGE_API_KEY` and `MERGE_ACCOUNT_TOKEN` environment variables are set or replace placeholders. This SDK provides both synchronous and asynchronous clients for various API categories.
import os
from merge import Merge
from merge.resources.ats import ActivityRequest
# Instantiate the client with your API Key and Account Token
# For production, securely manage your credentials (e.g., environment variables)
client = Merge(
api_key=os.environ.get('MERGE_API_KEY', 'YOUR_API_KEY'),
account_token=os.environ.get('MERGE_ACCOUNT_TOKEN', 'YOUR_ACCOUNT_TOKEN')
)
try:
# Example: Create an activity in the ATS category
# Note: Replace with actual model data as required by your API call
activity_data = ActivityRequest(
subject="Initial Interview",
activity_type="Interview",
candidate_id="<YOUR_CANDIDATE_ID>", # Replace with a valid candidate ID
# Add other required fields for ActivityRequest
)
response = client.ats.activities.create(
model=activity_data,
remote_user_id="<YOUR_REMOTE_USER_ID>" # Replace with a valid remote user ID
)
print("Activity created successfully:")
print(response.to_dict())
# Example: List employees from HRIS category (pagination example)
# For real use, iterate through pages if 'next' is present
employees_page = client.hris.employees.list(page_size=1)
print("\nFirst employee page:")
if employees_page.results:
for employee in employees_page.results:
print(employee.first_name, employee.last_name)
else:
print("No employees found.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingLegacy SDKs (e.g., MergeATSClient, MergeHRISClient) were deprecated in August 2023 and stopped receiving updates/bug fixes after February 2024. Projects using these older, category-specific clients must migrate to the unified 'mergepythonclient' (v2 SDK) for continued support and new features.fixMigrate to the `mergepythonclient` (v2 SDK) by installing `pip install MergePythonClient` and updating imports and API call patterns according to the official migration guide. New client instantiation is `from merge import Merge`.
affects: <2.0.0 (legacy SDKs)
gotchaWhen using older, generated SDKs for Merge (like `MergeATSClient`), importing all APIs or models (e.g., `from MergeATSClient.apis import *`) might lead to a `RecursionError` with large OpenAPI documents.fixPrefer specific imports (e.g., `from MergeATSClient.api.default_api import DefaultApi`) or increase Python's recursion limit (`sys.setrecursionlimit(1500)`) before importing, though migrating to the unified `mergepythonclient` is the recommended long-term solution.
affects: Legacy Merge SDKs (<2.0.0, e.g., MergeATSClient, MergeHRISClient)
gotchaThe first usage of a newly instantiated Merge client may experience additional latency due to internal initialization processes.fixConsider pre-initializing the client if latency on the very first call is critical, or accept that the initial request might take slightly longer.
affects: 2.x.x
gotchaAPI requests can fail due to 'CREDENTIAL_REFRESH_FAILED' if the linked account's credentials need to be refreshed, or 'DISABLED_MODEL_WRITE' if attempting to write to a model that has been disabled.fixFor credential issues, navigate to https://app.merge.dev/logs to view logs for the linked account. For disabled models, go to https://app.merge.dev/organization/common-models to re-enable the model.
affects: 2.x.x
gotchaRequests may encounter 'INCORRECT_FIELD_TYPE' errors or warnings if field values are not in the expected format. While warnings indicate Merge could convert the type, it's best to send correct types to avoid data alteration.fixEnsure all values passed into request fields conform to the expected data type as specified in the Merge API documentation.
affects: 2.x.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'merge'
The `mergepythonclient` library is either not installed in your Python environment or you are trying to import it incorrectly. The package name for installation is `MergePythonClient`, but the top-level module to import is `merge`.
fixFirst, ensure the library is installed: `pip install MergePythonClient`. Then, update your import statement to `from merge import Merge`.
ModuleNotFoundError: No module named 'MergeATSClient'
You are attempting to use an older, deprecated category-specific Merge SDK (e.g., for ATS, HRIS) instead of the unified `mergepythonclient` (v2 SDK).
fixMigrate to the unified `mergepythonclient` by installing `pip install MergePythonClient` and updating your import from `import MergeATSClient` (or similar) to `from merge import Merge`.
CREDENTIAL_REFRESH_FAILED
This error indicates that the credentials for your linked Merge account have failed to refresh, preventing successful API requests.
fixNavigate to `https://app.merge.dev/logs` to view logs for the linked account and diagnose the specific credential issue. You may need to re-link or refresh credentials for the integration.
INCORRECT_FIELD_TYPE
The value provided for a field in your API request is in an incorrect format or data type, and Merge was unable to convert it, leading to the common model not being created.
fixReview the Merge API documentation for the specific endpoint and ensure that all values passed into your request fields conform to the expected data types. Correct any type mismatches (e.g., sending a string when an integer is expected).
Upgrade
Version history
4.1.0latest on PyPI · released Jul 24, 2026
Audit
Dependencies
No dependency data recorded yet.