Low-Level Connection for HubSpot API Clients

https://travis-ci.org/2degrees/hubspot-connection.png?branch=master https://coveralls.io/repos/2degrees/hubspot-connection/badge.png?branch=master
Sponsored by:2degrees Limited.

hubspot-connection provides a lightweight abstraction layer for making requests to the HubSpot API.

Here’s an example of how it can be used:

from hubspot.connection import APIKey
from hubspot.connection import PortalConnection

authentication_key = APIKey('HUBSPOT-API-KEY')
with PortalConnection(authentication_key, 'client') as connection:
    contacts_data = connection.send_get_request('/contacts/v1/contacts/statistics')
    print "Number of contacts: {}".format(contacts_data.get('contacts'))

This project is officially supported under Python 2.7, but may work with Python 2.6 and Python 3.



HubSpot supports two authentication methods: OAuth and a proprietary, token-based method referred to as “API Key”.

In order to authenticate you just need to instanciate either hubspot.connection.OAuthKey or hubspot.connection.APIKey with the apropriate value.


authentication_key = OAuthKey('HUBSPOT-OAUTH-KEY')

authentication_key = APIKey('HUBSPOT-API-KEY')

How to make requests to HubSpot

PortalConnection is meant to be used as a context manager which takes care of keeping the connection alive retrying a maximum of 3 times should there be any network-level timeout or socket errors.

A good example of a library using hubspot.connection can be seen here: hubspot-contacts.


hubspot-connection comes bundled with utilities designed to help you with testing.

The MockPortalConnection is initialized with zero or more so-called “api call simulators” (or simply “simulators”), which are passed by position. Simulators are callables that receive no arguments and return an iterable of successful or unsuccessful API calls.

Their role, is to tell the MockPortalConnection what API calls are excepted to be called, and that each will have exactly the expected:

  • URL path
  • Body deserialization
  • URL arguments
  • Method

If the response is expected to be successful, it’s body deserialization will be verified, if the response is expected to be unsuccessful, the exception will be checked, whether it’s the correct one. To represent API calls this library comes with SuccessfulAPICall and UnsuccessfulAPICall.

Should any unexpected API end-point get called, any of the expected end-points is not called or if they are in the wrong order, an AssertionError is raised.

Example of an API call:

# Example of a successful API call
api_call = SuccessfulAPICall(
    response_body_deserialization={'foo': 'bar'},

# Example of an unsuccessful API call
api_call = UnsuccessfulAPICall(
    exception=HubspotServerError('Foo is not implemented', 501),

Example of testing the deletion of a contact list:

from hubspot.connection.testing import MockPortalConnection
from hubspot.connection.testing import SuccessfulAPICall

def test_delete_contact_list():
    list_id = 1
    url_path = '/contacts/v1/lists/{}'.format(list_id)

    api_call = SuccessfulAPICall(

    expected_api_calls_simulator = lambda : [api_call]

    with MockPortalConnection(expected_api_calls_simulator) as connection
        delete_list(list_id, connection)

# Unit to be tested
def delete_contact_list(list_id, connection):



class hubspot.connection.APIKey

Representation of the HubSpot API Key


The HubSpot API Key (hapikey)

class hubspot.connection.OAuthKey

Representation of the HubSpot OAuth Key


The HubSpot OAuth Key (access_token)


class hubspot.connection.PortalConnection(authentication_key, change_source)

Connection to HubSpot

  • authentication_key – This can be either an APIKey or an OAuthKey instance
  • change_source (basestring) – The string passed to HubSpot as auditId in the query string

Send a DELETE request to HubSpot

Parameters:url_path (basestring) – The URL path to the endpoint
Returns:Decoded version of the JSON that HubSpot put in the body of the response.
send_get_request(url_path, query_string_args=None)

Send a GET request to HubSpot

  • url_path (basestring) – The URL path to the endpoint
  • query_string_args (dict) – The query string arguments

Decoded version of the JSON that HubSpot put in the body of the response.

send_post_request(url_path, body_deserialization)

Send a POST request to HubSpot

  • url_path (basestring) – The URL path to the endpoint
  • body_deserialization (dict) – The request’s body message deserialized

Decoded version of the JSON that HubSpot put in the body of the response.

send_put_request(url_path, body_deserialization)

Send a PUT request to HubSpot

  • url_path (basestring) – The URL path to the endpoint
  • body_deserialization – The request’s body message deserialized

Decoded version of the JSON that HubSpot put in the body of the response.


exception hubspot.connection.exc.HubspotAuthenticationError(msg, request_id)

HubSpot rejected your authentication key. This represents an HTTP response code of 401.

exception hubspot.connection.exc.HubspotClientError(msg, request_id)

HubSpot deemed the request invalid. This represents an HTTP response code of 40X, except 401

Parameters:request_id (unicode) –
exception hubspot.connection.exc.HubspotException

The base HubSpot error.

exception hubspot.connection.exc.HubspotServerError(msg, http_status_code)

HubSpot failed to process the request due to a problem at their end. This represents an HTTP response code of 50X.

Parameters:http_status_code (int) –

Testing utilities

class hubspot.connection.testing.MockPortalConnection(*api_calls_simulators)

Mock representation of a PortalConnection

class hubspot.connection.testing.APICall(*values_by_field_order, **values_by_field_name)

A basestring representing the complete URL to the request


A basestring representing the HTTP Method to the request


A dict representing the query string args


A representation of the request’s body

class hubspot.connection.testing.SuccessfulAPICall

A represention of the response’s body

class hubspot.connection.testing.UnsuccessfulAPICall

An exception representing the raised Exception


For questions directly related to hubspot-connection, please use our 2degrees-floss mailing list.

Please go to our development site at GitHub to get the latest code, create pull requests and raise issues.


Version 1.0 Release Candidate 1 (2014-06-23)

This is the first public release.

Version 1.0 Release Candidate 2 (2014-07-14)

  • Added content-type=’application/json’ for requests with body

Version 1.0 Release Candidate 3 (2014-09-15)

  • Made content-type mandatory only when content is expected

Version 1.0 Release Candidate 4 (2015-02-18)

  • Allowed for extra details in error responses from Hubspot