HubSpot API Client

12.0.0 · active · verified Fri Apr 10

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.

Warnings

breaking 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.
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.
breaking 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.
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.
breaking 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.
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.
gotcha 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`.
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.
gotcha 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.
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.

Install

pip install hubspot-api-client Install latest version

Imports

HubSpot
```
from hubspot import HubSpot
```
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
```
As of v12.0.0-beta.1, `BatchInputSimplePublicObjectInputForCreate` was renamed to `BatchInputSimplePublicObjectBatchInputForCreate` for CRM objects. `SimplePublicObjectInputForCreate` remains for single object creation.

Quickstart

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

view raw JSON →