Merge Python Client

2.6.3 · active · verified Mon Apr 13

The Merge Python library (SDK) provides convenient access to the Merge Unified APIs from Python. It allows developers to integrate with various categories such as ATS (Applicant Tracking System), HRIS (Human Resources Information System), CRM, Ticketing, Accounting, and File Storage. The library is actively maintained with regular updates and is currently at version 2.6.3.

Warnings

breaking Legacy 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.
Fix: Migrate 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`.
gotcha When 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.
Fix: Prefer 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.
gotcha The first usage of a newly instantiated Merge client may experience additional latency due to internal initialization processes.
Fix: Consider pre-initializing the client if latency on the very first call is critical, or accept that the initial request might take slightly longer.
gotcha API 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.
Fix: For 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.
gotcha Requests 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.
Fix: Ensure all values passed into request fields conform to the expected data type as specified in the Merge API documentation.

Install

pip install MergePythonClient Install stable version

Imports

Merge
```
from merge import Merge
```
Merge (legacy clients)
```
from merge import Merge
```
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

Quickstart

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}")

view raw JSON →