Install & Compatibility
Where this runs
tested against v12.0.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.242s · 67.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.7s · import 0.250s · 68MB
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HubSpot
✓ from hubspot import HubSpot
✗ import hubspot_api_client
The primary client class `HubSpot` is imported directly from the top-level `hubspot` package, not `hubspot_api_client`.
SimplePublicObjectInputForCreate
✓ from hubspot.crm.contacts import SimplePublicObjectInputForCreate
✗ from hubspot.crm.contacts import BatchInputSimplePublicObjectInputForCreate
As of v12.0.0-beta.1, `BatchInputSimplePublicObjectInputForCreate` was renamed to `BatchInputSimplePublicObjectBatchInputForCreate` for CRM objects. `SimplePublicObjectInputForCreate` remains for single object creation.
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.
import os
from hubspot import HubSpot
from hubspot.crm.contacts import SimplePublicObjectInputForCreate
from hubspot.crm.contacts.exceptions import ApiException
# Get your private app access token from environment variables for security
# In HubSpot, go to Settings -> Integrations -> Private Apps to create one.
ACCESS_TOKEN = os.environ.get('HUBSPOT_PRIVATE_APP_TOKEN', 'YOUR_PRIVATE_APP_TOKEN')
if not ACCESS_TOKEN or ACCESS_TOKEN == 'YOUR_PRIVATE_APP_TOKEN':
print("Warning: HubSpot private app token not set. Please set HUBSPOT_PRIVATE_APP_TOKEN environment variable or replace 'YOUR_PRIVATE_APP_TOKEN'.")
exit(1)
api_client = HubSpot(access_token=ACCESS_TOKEN)
try:
simple_public_object_input_for_create = SimplePublicObjectInputForCreate(
properties={"email": "example@example.com", "firstname": "Test", "lastname": "User"}
)
api_response = api_client.crm.contacts.basic_api.create(
simple_public_object_input_for_create=simple_public_object_input_for_create
)
print("Contact created:")
print(api_response.to_dict())
except ApiException as e:
print(f"Exception when creating contact: {e}")
# Common error: scopes not set for the private app. Check your private app permissions.
# Example of getting a contact by email
try:
contact_by_email = api_client.crm.contacts.basic_api.get_by_email("example@example.com")
print("Contact found by email:")
print(contact_by_email.to_dict())
except ApiException as e:
print(f"Exception when getting contact by email: {e}")
Debug
Known issues
breakingThe `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.fixMigrate 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.
affects: >=5.1.0 (underlying API deprecation), >=8.1.0 (client library removal in modules)
breakingIn `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.fixUpdate 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.
affects: >=12.0.0
breakingIn `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.fixUpdate 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.
affects: >=12.0.0
gotchaOlder 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`.fixIf encountering `AttributeError: 'Discovery' object has no attribute 'default_api'` for OAuth token creation, try using `api_client.auth.oauth.basic_api.create_token` instead.
affects: Potentially all versions, depending on documentation source vs. actual client implementation.
gotchaHubSpot'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.fixWhen 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.
affects: All versions (impacts how underlying HubSpot API endpoints are structured)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'hubspot'
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`.
fixInstall the library using `pip install hubspot-api-client` and import it as `import hubspot` or specific modules like `from hubspot.crm.contacts import BasicApi`.
{"message":"This hapikey (...) does not have the permissions required for this action.","status":"error","correlationId":"...","category":"VALIDATION_ERROR"}
The API key (hapikey) or OAuth token provided is valid but lacks the necessary scopes or permissions to perform the requested operation.
fixVerify your API key or OAuth token's validity and ensure it has all the required scopes enabled in your HubSpot developer or app settings.
{"message":"Contact not found","status":"error","correlationId":"...","category":"NOT_FOUND"}
The HubSpot object (e.g., contact, company, deal) with the specified ID or unique identifier could not be found or does not exist.
fixEnsure the ID or unique identifier (e.g., email address, object ID) used in your request corresponds to an existing object in HubSpot.
{"message":"Property 'email' is required.","status":"error","correlationId":"...","category":"VALIDATION_ERROR"}
The request payload for creating or updating an object is missing one or more mandatory properties or data fields required by the HubSpot API.
fixReview 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.
AttributeError: 'NoneType' object has no attribute 'results'
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.
fixAdd checks for `None` or empty responses, and print the API response object (e.g., `print(response)`) to inspect its actual structure and available attributes.
Upgrade
Version history
12.0.0latest on PyPI · released May 7, 2025
Audit
Dependencies
pythonrequiredRequired Python version.