{"id":2536,"library":"hubspot-api-client","title":"HubSpot API Client","description":"The `hubspot-api-client` is the official Python SDK for interacting with the HubSpot API (v3). It provides an easy-to-use interface to manage CRM objects, marketing events, files, and more. While the library follows semantic versioning, the underlying HubSpot API itself releases new major versions twice a year (March and September) using a date-based versioning scheme (e.g., /2026-03/), each supported for a minimum of 18 months.","status":"active","version":"12.0.0","language":"en","source_language":"en","source_url":"https://github.com/HubSpot/hubspot-api-python","tags":["HubSpot","CRM","API Client","Marketing Automation"],"install":[{"cmd":"pip install hubspot-api-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false}],"imports":[{"note":"The primary client class `HubSpot` is imported directly from the top-level `hubspot` package, not `hubspot_api_client`.","wrong":"import hubspot_api_client","symbol":"HubSpot","correct":"from hubspot import HubSpot"},{"note":"As of v12.0.0-beta.1, `BatchInputSimplePublicObjectInputForCreate` was renamed to `BatchInputSimplePublicObjectBatchInputForCreate` for CRM objects. `SimplePublicObjectInputForCreate` remains for single object creation.","wrong":"from hubspot.crm.contacts import BatchInputSimplePublicObjectInputForCreate","symbol":"SimplePublicObjectInputForCreate","correct":"from hubspot.crm.contacts import SimplePublicObjectInputForCreate"}],"quickstart":{"code":"import os\nfrom hubspot import HubSpot\nfrom hubspot.crm.contacts import SimplePublicObjectInputForCreate\nfrom hubspot.crm.contacts.exceptions import ApiException\n\n# Get your private app access token from environment variables for security\n# In HubSpot, go to Settings -> Integrations -> Private Apps to create one.\nACCESS_TOKEN = os.environ.get('HUBSPOT_PRIVATE_APP_TOKEN', 'YOUR_PRIVATE_APP_TOKEN')\n\nif not ACCESS_TOKEN or ACCESS_TOKEN == 'YOUR_PRIVATE_APP_TOKEN':\n    print(\"Warning: HubSpot private app token not set. Please set HUBSPOT_PRIVATE_APP_TOKEN environment variable or replace 'YOUR_PRIVATE_APP_TOKEN'.\")\n    exit(1)\n\napi_client = HubSpot(access_token=ACCESS_TOKEN)\n\ntry:\n    simple_public_object_input_for_create = SimplePublicObjectInputForCreate(\n        properties={\"email\": \"example@example.com\", \"firstname\": \"Test\", \"lastname\": \"User\"}\n    )\n    api_response = api_client.crm.contacts.basic_api.create(\n        simple_public_object_input_for_create=simple_public_object_input_for_create\n    )\n    print(\"Contact created:\")\n    print(api_response.to_dict())\nexcept ApiException as e:\n    print(f\"Exception when creating contact: {e}\")\n    # Common error: scopes not set for the private app. Check your private app permissions.\n\n# Example of getting a contact by email\ntry:\n    contact_by_email = api_client.crm.contacts.basic_api.get_by_email(\"example@example.com\")\n    print(\"Contact found by email:\")\n    print(contact_by_email.to_dict())\nexcept ApiException as e:\n    print(f\"Exception when getting contact by email: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the HubSpot client using a private app access token and create a new contact. Ensure your private app has the necessary 'crm.objects.contacts.write' scope."},"warnings":[{"fix":"Migrate to Private App tokens (recommended for internal tools) or OAuth2 for authentication. Obtain a Private App token from HubSpot Settings -> Integrations -> Private Apps, or configure OAuth2 flow.","message":"The `hapikey` (API Key) authentication method is deprecated and no longer supported for many HubSpot API clients after `v5.1.0` of the library, and was explicitly removed from various modules in `v8.1.0`. New integrations and updated code should use Private App tokens or OAuth2 access tokens.","severity":"breaking","affected_versions":">=5.1.0 (underlying API deprecation), >=8.1.0 (client library removal in modules)"},{"fix":"Update model imports and usage to `BatchInputSimplePublicObjectBatchInputForCreate`. Consult the specific API client (e.g., `crm.contacts.basic_api`) for the correct methods for creating, updating, or archiving objects, as these may have been moved or renamed within their respective sub-APIs.","message":"In `v12.0.0-beta.1` and `v12.0.0`, several breaking changes were introduced to CRM object management. The model `BatchInputSimplePublicObjectInputForCreate` was renamed to `BatchInputSimplePublicObjectBatchInputForCreate` across CRM modules (contacts, companies, deals, etc.). Additionally, generic `archive()`, `create()`, and `update()` methods were removed from some CRM object clients.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"Update method calls in your code. Use `files.files_api.delete()` instead of `archive_gdpr()`, and `files.folders_api.update_properties_recursively()` for recursive property updates. Use the new `files.folders_api.update_properties()` for non-recursive updates.","message":"In `v12.0.0`, breaking changes were introduced to the Files API. The method `archive_gdpr()` in `files.files_api` was renamed to `delete()`. In `files.folders_api`, `update_properties()` was renamed to `update_properties_recursively()`, and a new `update_properties()` method was added.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"If encountering `AttributeError: 'Discovery' object has no attribute 'default_api'` for OAuth token creation, try using `api_client.auth.oauth.basic_api.create_token` instead.","message":"Older documentation or examples might refer to `api_client.auth.oauth.default_api.create_token`. However, the `Discovery` object for OAuth may not have a `default_api` attribute, leading to `AttributeError`. The correct attribute to use is often `basic_api`.","severity":"gotcha","affected_versions":"Potentially all versions, depending on documentation source vs. actual client implementation."},{"fix":"When referring to HubSpot API documentation or examples, verify the versioning scheme. The client library handles this automatically, but manual API calls or debugging might require understanding the date-based URLs. New major client library versions typically align with the latest HubSpot API versions.","message":"HubSpot's underlying APIs are transitioning to a date-based versioning system (e.g., `/2026-03/` instead of `/v3/`). While the `hubspot-api-client` aims to abstract this, developers working directly with API paths or older examples should be aware of this shift for consistency and future compatibility.","severity":"gotcha","affected_versions":"All versions (impacts how underlying HubSpot API endpoints are structured)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}