HubSpot Python SDK

Install the HubSpot Python SDK using pip to interact with HubSpot APIs.

Requirements

• Python 3.7+
• pip

pip install --upgrade hubspot-api-client

Initialize the HubSpot client using an access token. You can provide the token during instantiation or set it on the instance later. Access tokens can be obtained via a Private App or OAuth2.

Note on Hapikey: hapikey is no longer supported as of version 5.1.0. Use Private Apps or OAuth2 instead.

from hubspot import HubSpot

# Initialize with access token
api_client = HubSpot(access_token='your_access_token')

# Or initialize without and set it later
api_client = HubSpot()
api_client.access_token = 'your_access_token'

You can configure HTTP retries by passing an instance of urllib3.util.retry.Retry to the HubSpot client constructor.

Internal Error Retry (e.g., 500, 502, 504):

from hubspot import HubSpot
from urllib3.util.retry import Retry

retry = Retry(
    total=3,
    backoff_factor=0.3,
    status_forcelist=(500, 502, 504),
)
api_client = HubSpot(retry=retry)

Rate Limit Retry (e.g., 429):

retry = Retry(
    total=5,
    status_forcelist=(429,),
)
api_client = HubSpot(retry=retry)

The Client provides access to various HubSpot API domains through properties. Each property returns a discovery object that allows you to interact with that specific functional area of the HubSpot API.

Available modules include:

• crm: CRM API (Contacts, Companies, Deals, etc.)
• oauth: OAuth API
• automation: Automation API
• cms: CMS API
• communication_preferences: Communication Preferences API
• conversations: Conversations API
• events: Events API
• files: Files API
• marketing: Marketing API
• settings: Settings API
• webhooks: Webhooks API

from hubspot import Client

client = Client(access_token='your_access_token')

# Access the CRM module
crm_module = client.crm

# Access the Files module
files_module = client.files

Use the files.files_api.upload method to upload files. The options parameter must be a JSON-encoded string containing configuration like access (e.g., 'PRIVATE') and overwrite.

import hubspot
import json
from pprint import pprint
from hubspot.crm.contacts import ApiException

client = hubspot.Client.create(access_token="your_access_token")

options = json.dumps(
    {'access': 'PRIVATE',
     "overwrite": False}
)

try:
    response = client.files.files_api.upload(
        file="/file/path/file.jpeg",
        file_name="name_in_hubspot",
        folder_path="folder_in_hubspot",
        options=options,
    )
    pprint(response)
except ApiException as e:
    print("Exception when calling basic_api->get_page: %s\n" % e)

Use the oauth.tokens_api.create method to exchange an authorization code for access tokens.

from hubspot.oauth import ApiException

try:
    tokens = api_client.oauth.tokens_api.create(
        grant_type="authorization_code",
        redirect_uri='http://localhost',
        client_id='client_id',
        client_secret='client_secret',
        code='code'
    )
except ApiException as e:
    print("Exception when calling create_token method: %s\n" % e)

If the SDK does not yet have a wrapper for a specific endpoint, you can use the api_request method to make direct calls. This method uses the client's existing configuration (like access tokens).

# GET request example
response = client.api_request({"path": "/crm/v3/objects/contacts"})

# POST request example
response = client.api_request(
    {
        "path": "/crm/v3/objects/contacts",
        "method": "POST",
        "body": {
            "properties": {
                "email": "some_email@some.com",
                "lastname": "some_last_name"
            },
        }
    }
)

Most response objects in the SDK provide a to_dict() method to convert the object into a standard Python dictionary.

contacts = api_client.crm.contacts.basic_api.get_page()
for contact in contacts.results:
    print(contact.to_dict())

The Client class is the primary entrypoint for the HubSpot SDK. You can initialize it by providing either an api_key or an access_token. You can also pass a retry object (from urllib3.util.retry.Retry) to configure request retries and other configuration via **kwargs.

from hubspot import Client

# Using an access token (recommended for OAuth)
client = Client(access_token='your_access_token')

# Using an API key
client = Client(api_key='your_api_key')

# Using the create classmethod
client = Client.create(access_token='your_access_token')

You can dynamically update the authentication credentials of an existing Client instance using the access_token or api_key properties.

from hubspot import Client

client = Client(api_key='old_key')

# Update to use an access token instead
client.access_token = 'new_access_token'

# Or update the API key
client.api_key = 'new_api_key'