{"id":5318,"library":"mergepythonclient","title":"Merge Python Client","description":"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.","status":"active","version":"2.6.3","language":"en","source_language":"en","source_url":"https://github.com/merge-api/merge-python-client","tags":["API Client","Unified API","HRIS","ATS","Accounting","CRM","Ticketing","File Storage"],"install":[{"cmd":"pip install MergePythonClient","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Merge","correct":"from merge import Merge"},{"note":"Legacy, category-specific SDKs (e.g., MergeATSClient, MergeHRISClient) are deprecated. Use the unified 'mergepythonclient' and import 'Merge' directly.","wrong":"import MergeATSClient","symbol":"Merge (legacy clients)","correct":"from merge import Merge"},{"symbol":"Resource models (e.g., ActivityRequest)","correct":"from merge.resources.ats import ActivityRequest"}],"quickstart":{"code":"import os\nfrom merge import Merge\nfrom merge.resources.ats import ActivityRequest\n\n# Instantiate the client with your API Key and Account Token\n# For production, securely manage your credentials (e.g., environment variables)\nclient = Merge(\n    api_key=os.environ.get('MERGE_API_KEY', 'YOUR_API_KEY'),\n    account_token=os.environ.get('MERGE_ACCOUNT_TOKEN', 'YOUR_ACCOUNT_TOKEN')\n)\n\ntry:\n    # Example: Create an activity in the ATS category\n    # Note: Replace with actual model data as required by your API call\n    activity_data = ActivityRequest(\n        subject=\"Initial Interview\",\n        activity_type=\"Interview\",\n        candidate_id=\"<YOUR_CANDIDATE_ID>\", # Replace with a valid candidate ID\n        # Add other required fields for ActivityRequest\n    )\n    \n    response = client.ats.activities.create(\n        model=activity_data,\n        remote_user_id=\"<YOUR_REMOTE_USER_ID>\" # Replace with a valid remote user ID\n    )\n    print(\"Activity created successfully:\")\n    print(response.to_dict())\n\n    # Example: List employees from HRIS category (pagination example)\n    # For real use, iterate through pages if 'next' is present\n    employees_page = client.hris.employees.list(page_size=1)\n    print(\"\\nFirst employee page:\")\n    if employees_page.results:\n        for employee in employees_page.results:\n            print(employee.first_name, employee.last_name)\n    else:\n        print(\"No employees found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<2.0.0 (legacy SDKs)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Legacy Merge SDKs (<2.0.0, e.g., MergeATSClient, MergeHRISClient)"},{"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.","message":"The first usage of a newly instantiated Merge client may experience additional latency due to internal initialization processes.","severity":"gotcha","affected_versions":"2.x.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"2.x.x"},{"fix":"Ensure all values passed into request fields conform to the expected data type as specified in the Merge API documentation.","message":"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.","severity":"gotcha","affected_versions":"2.x.x"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}