API Documentation

Keep the following in mind while using the functions provided by this library:

  • You should only use the connection from a context manager so that any startup or shutdown routine can be executed.
  • Date and datetime objects are timezone-naive but should still match the timezone used by HubSpot (UTC as at this writing).
  • When HubSpot fails to process a request made by any of the functions in this library, hubspot-connection will raise an exception that sub-classes hubspot.connection.exc.HubspotException.

Contacts API

The following methods from the Contacts API are currently supported:

hubspot.contacts.lists.get_all_contacts(connection, property_names=())

Get all the contacts in the portal.

Parameters:property_names – The names of the properties to be retrieved for each contact
Returns:An iterator with Contact instances
Raises hubspot.connection.exc.HubspotException:
 

If property_names is empty, no specific properties are requested to HubSpot. Otherwise, values are passed as is to HubSpot.

This function is a generator and requests are sent on demand. This is, the first request to HubSpot is deferred until the first contact in the result is used, and from there on subsequent requests may be sent as the iterator is consumed.

Generally speaking, the contacts returned, their order and their properties are determined by HubSpot, with the following exceptions:

  • Property values in each contact are type-cast to an appropriate, built-in datatype.
  • Duplicated contacts (i.e., multiple contacts with the same VID) are discarded.

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/get_contacts

hubspot.contacts.lists.get_all_contacts_by_last_update(connection, property_names=(), cutoff_datetime=None)

Get all the contacts in the portal, starting with the most recently updated ones.

Parameters:
  • property_names – The names of the properties to be retrieved for each contact
  • cutoff_datetime (datetime.datetime) – The minimum datetime for the last update to any contact returned
Returns:

An iterator with Contact instances

Raises hubspot.connection.exc.HubspotException:
 

If cutoff_datetime is set, only contacts that were last updated at that time or later are returned. If unset, all the contacts are returned and sorted by their last update (most recent first).

Apart from the special considerations given to the contacts’ last update date, this behaves exactly like get_all_contacts(). But because this uses a different HubSpot API end-point, the output may be slightly different; for instance, as at this writing, one known difference is that this end-point also returns contacts for whom there are no registered email addresses.

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/get_recently_updated_contacts

hubspot.contacts.save_contacts(contacts, connection)

Request the creation and/or update of the contacts.

Parameters:

contacts (iterable) – The contacts to be created/updated

Returns:

None

Raises:

For each contact, only its email address and properties are passed to HubSpot. Any other datum (e.g., the VID) is ignored.

As at this writing, this end-point does not process the requested changes immediately. Instead, it partially validates the input and, if it’s all correct, the requested changes are queued.

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/batch_create_or_update

Entities

class hubspot.contacts.Contact(*values_by_field_order, **values_by_field_name)

Bases: pyrecord.Record

A HubSpot contact.

vid

An int instance for the contact’s identifier on HubSpot.

email_address

The contact’s email address as a unicode string or None if unknown.

properties

A dictionary with the values associated to the contact.

related_contact_vids = ()

The VIDs for each of the contacts related to the current one.

Contact Lists API

Note

Only static lists are supported at this moment.

The following methods from the Contact Lists API are currently supported:

hubspot.contacts.lists.get_all_contact_lists(connection)

Get the meta-information for all the contact lists in the portal.

Returns:An iterator with ContactList instances
Raises hubspot.connection.exc.HubspotException:
 

This function is a generator and requests are sent on demand. This is, the first request to HubSpot is deferred until the first list in the result is used, and from there on subsequent requests may be sent as the iterator is consumed.

End-point documentation: http://developers.hubspot.com/docs/methods/lists/get_lists

hubspot.contacts.lists.create_static_contact_list(contact_list_name, connection)

Create a static contact list named contact_list_name.

Parameters:contact_list_name (basestring) –
Return ContactList:
 The resulting list as created by HubSpot
Raises hubspot.connection.exc.HubspotException:
 
hubspot.contacts.lists.delete_contact_list(contact_list_id, connection)

Delete the contact list identified by contact_list_id.

Parameters:contact_list_id (int) – The identifier of the contact list to be removed
Returns:None
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/lists/delete_list

hubspot.contacts.lists.get_all_contacts_from_list(connection, contact_list, property_names=())

Get all the contacts in contact_list.

Parameters:
  • contact_list (ContactList) – The list whose contacts should be retrieved
  • property_names – The names of the properties to be retrieved for each contact
Returns:

An iterator with Contact instances

Raises hubspot.connection.exc.HubspotException:
 

Other than the contacts being limited to contact_list, this function behaves exactly like get_all_contacts(). But because this uses a different HubSpot API end-point, the output may be slightly different.

End-point documentation: http://developers.hubspot.com/docs/methods/lists/get_list_contacts

hubspot.contacts.lists.get_all_contacts_from_list_by_added_date(contact_list, connection, property_names=(), cutoff_datetime=None)

Get all the contacts in contact_list, starting with the most recently added ones.

Parameters:
  • contact_list (ContactList) – The list whose contacts should be retrieved
  • property_names – The names of the properties to be retrieved for each contact
Returns:

An iterator with Contact instances

Raises hubspot.connection.exc.HubspotException:
 

If cutoff_datetime is set, only contacts that were added at that time or later are returned. If unset, all the contacts in the list are returned and sorted by the time they were added (most recent first).

Apart from the special considerations given to the time the contact was added to the list, this function behaves exactly like get_all_contacts_from_list(). But because this uses a different HubSpot API end-point, the output may be slightly different.

End-point documentation: http://developers.hubspot.com/docs/methods/lists/get_list_contacts_recent

hubspot.contacts.lists.add_contacts_to_list(contact_list, contacts, connection)

Add contacts to contact_list.

Parameters:
  • contact_list (ContactList) – The list to which contacts must be added
  • contacts (iterator) – The contacts to add to contact_list
Returns:

The VIDs corresponding to the contacts that were successfully added to the list

Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/lists/add_contact_to_list

hubspot.contacts.lists.remove_contacts_from_list(contact_list, contacts, connection)

Remove contacts from contact_list.

Parameters:
  • contact_list (ContactList) – The list from which contacts must be removed
  • contacts (iterator) – The contacts to remove from contact_list
Returns:

The VIDs corresponding to the contacts that were successfully removed from the list

Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/lists/remove_contact_from_list

Entities

class hubspot.contacts.lists.ContactList

A HubSpot contact list.

id
name
is_dynamic

Whether the list is dynamic.

Contact Properties API

The following methods from the Contact Properties API are currently supported:

Properties

hubspot.contacts.properties.get_all_properties(connection)

Get the meta-information for all the properties in the portal.

Return type:list of Property specialization instances
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/get_properties

hubspot.contacts.properties.create_property(property_, connection)

Create property_.

Parameters:property (Property) – The property to be created
Returns:Property specialization instance as created by HubSpot
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/create_property

hubspot.contacts.properties.delete_property(property_name, connection)

Delete the property named property_name.

Parameters:property_name (basestring) – The name of the property to be deleted
Returns:None
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/delete_property

Supported Datatypes

class hubspot.contacts.properties.Property

Base class for a HubSpot property.

The following attributes correspond to the same data associated to a particular property on HubSpot.

name
label
description
group_name
field_widget

HubSpot usually refers to this as the “field type”, even though it isn’t strictly do to with data types. Instead, this attribute refers to the type of widget to be used when displaying/capturing the property value (e.g., a date picker for a DateProperty).

class hubspot.contacts.properties.BooleanProperty
Bases:Property
true_label

The user-friendly string to refer to property value True when presented on HubSpot. By default, this is "Yes".

false_label

The user-friendly string to refer to property value False when presented on HubSpot. By default, this is "No".

class hubspot.contacts.properties.DateProperty
Bases:Property
class hubspot.contacts.properties.DatetimeProperty
Bases:Property
class hubspot.contacts.properties.EnumerationProperty
Bases:Property

The definition of an enum(eration) property.

options

A mapping with all the possible values for the enumeration.

The mapping keys are the property values and the mapping values are the user-friendly labels for each property value. For example:

{'gbp': 'Pound Sterling', 'eur': 'Euro', 'usd': 'US Dollar'}
class hubspot.contacts.properties.NumberProperty
Bases:Property
class hubspot.contacts.properties.StringProperty
Bases:Property

Property Groups

hubspot.contacts.property_groups.get_all_property_groups(connection)

Get the meta-information for all the property groups in the portal.

Return type:list of PropertyGroup instances
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/get_groups

hubspot.contacts.property_groups.create_property_group(property_group, connection)

Create property_group.

Parameters:property (Property) – The property group to be created
Returns:PropertyGroup instance as created by HubSpot
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/create_group

hubspot.contacts.property_groups.delete_property_group(property_group_name, connection)

Delete the property group named property_group_name.

Parameters:property_group_name (PropertyGroup) – The name of the property group to be deleted
Returns:None
Raises hubspot.connection.exc.HubspotException:
 

End-point documentation: http://developers.hubspot.com/docs/methods/contacts/delete_group

Supported Datatypes

class hubspot.contacts.property_groups.PropertyGroup(*values_by_field_order, **values_by_field_name)

Bases: pyrecord.Record