{"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":"python","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,"search_vec":"'/2026-03':67 '18':74 'api':2,7,19,47,78 'autom':81 'base':63 'client':3,8,79 'crm':31,77 'date':62 'date-bas':61 'e.g':66 'easi':25 'easy-to-us':24 'event':34 'file':35 'follow':41 'hubspot':1,6,18,46,76 'hubspot-api-cli':5 'interact':15 'interfac':28 'librari':40 'major':51 'manag':30 'march':56 'market':33,80 'minimum':72 'month':75 'new':50 'object':32 'offici':11 'provid':22 'python':12 'releas':49 'scheme':65 'sdk':13 'semant':42 'septemb':58 'support':69 'twice':53 'under':45 'use':27,59 'v3':20 'version':43,52,64 'year':55","created_at":"2026-04-11T01:32:15.393916+00:00","updated_at":"2026-04-16T18:56:10.249437+00:00","problems":[{"fix":"Install the library using `pip install hubspot-api-client` and import it as `import hubspot` or specific modules like `from hubspot.crm.contacts import BasicApi`.","cause":"The `hubspot-api-client` library is not installed, or you are trying to import it with an incorrect module name. The installed package name is `hubspot`.","error":"ModuleNotFoundError: No module named 'hubspot'"},{"fix":"Verify your API key or OAuth token's validity and ensure it has all the required scopes enabled in your HubSpot developer or app settings.","cause":"The API key (hapikey) or OAuth token provided is valid but lacks the necessary scopes or permissions to perform the requested operation.","error":"{\"message\":\"This hapikey (...) does not have the permissions required for this action.\",\"status\":\"error\",\"correlationId\":\"...\",\"category\":\"VALIDATION_ERROR\"}"},{"fix":"Ensure the ID or unique identifier (e.g., email address, object ID) used in your request corresponds to an existing object in HubSpot.","cause":"The HubSpot object (e.g., contact, company, deal) with the specified ID or unique identifier could not be found or does not exist.","error":"{\"message\":\"Contact not found\",\"status\":\"error\",\"correlationId\":\"...\",\"category\":\"NOT_FOUND\"}"},{"fix":"Review the HubSpot API documentation for the specific endpoint (e.g., creating a contact) to ensure all required properties, such as 'email' or 'firstname', are included in your request body.","cause":"The request payload for creating or updating an object is missing one or more mandatory properties or data fields required by the HubSpot API.","error":"{\"message\":\"Property 'email' is required.\",\"status\":\"error\",\"correlationId\":\"...\",\"category\":\"VALIDATION_ERROR\"}"},{"fix":"Add checks for `None` or empty responses, and print the API response object (e.g., `print(response)`) to inspect its actual structure and available attributes.","cause":"An API call might have returned `None` or an unexpected response object structure, and subsequent code attempted to access an attribute that does not exist on that `NoneType` object or the actual response object.","error":"AttributeError: 'NoneType' object has no attribute 'results'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"12.0.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.hubspot.com","github":"https://github.com/HubSpot/hubspot-api-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/hubspot-api-client/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["crm-productivity","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}