Hubspot is a library for accessing HubSpot using REST API. It extends hubspot-api-client.

Current features of this library focus on retrieving CRM object data from HubSpot via API. For additional information, see Understanding the CRM.

When using date times with the Hubspot API, you must provide them as Unix-style epoch timestamps (with milliseconds), which can be obtained using the DateTime library's Convert Date with the argument result_format=epoch. The resulting timestamp string will be a float, but the API only accepts integers, so you must multiply the resulting timestamp by 1,000 and then round it to the nearest integar to include in API calls (i.e., the resulting integer sent to the API must have 13 digits as of March 18, 2022).

Robot framework example usage:

*** Settings ***
Library     DateTime
Library     RPA.Hubspot
Task Setup  Authorize Hubspot

*** Tasks ***
Search with date
    ${yesterday}=    Get current date    increment=-24h   result_format=epoch
    ${yesterday_hs_ts}=    Evaluate    round(${yesterday} * 1000)
    ${deals}=    Search for objects    DEALS
    ...    hs_lastmodifieddate    GTE    ${yesterday_hs_ts}

Python example usage

from robot.libraries.DateTime import get_current_date, subtract_time_from_date
from RPA.Hubspot import Hubspot
from RPA.Robocorp.Vault import Vault

secrets = Vault().get_secret("hubspot")

hs = Hubspot(hubspot_apikey=secrets["api_key"])
yesterday = round(
    subtract_time_from_date(get_current_date(), "24h", result_format="epoch") * 1000
)
deals = hs.search_for_objects("DEALS", "hs_lastmodifieddate", "GTE", yesterday)
print(deals)

When retrieving information, the library automatically batches requests that are provided as lists, see Get object keyword for an example, but when wishing to create or update many objects, the library provides a batching system.

In order to start a batch, you must first call the Create new batch keyword. This initializes a new batch to accept inputs. If a batch already exists when you call this keyword, it will be lost and a new blank one will be started.

Once the batch has been initialized, you can add inputs one at a time with Add input to batch or many at a time with Extend batch with inputs.

In order to finally send the batch to HubSpot, you must call Execute batch. The final keyword will return the created or updated objects from HubSpot. New object IDs can be obtained from the id property, see the SimplePublicObject reference.

Robot framework example:

*** Settings ***
Library         RPA.Hubspot
Library         RPA.Robocorp.Vault
Task Setup      Authorize Hubspot

*** Tasks ***
Create objects via batch
    Create new batch
    Add input to batch    name=Nokia    country=Finland
    Add input to batch    name=Google    country=USA
    ${new_companies}=    Execute batch
    Log    The first new company added has the new id ${{$new_companies[0].id}}

*** Keywords ***
Authorize Hubspot
    ${secrets}=    Get secret    hubspot
    Auth with api key    ${secrets}[API_KEY]

Python example:

NOTE: When executing a batch input in Python, you can directly import the BatchInputFactory class to use to create your batch input before executing the batch.

from RPA.Hubspot import Hubspot, BatchInputFactory, BatchMode
from RPA.Robocorp.Vault import RobocorpVault


vault = RobocorpVault()
secrets = vault.get_secret("hubspot")

hs = Hubspot(secrets["API_KEY"])

batch = BatchInputFactory(BatchMode.UPDATE, "company")
batch.extend_inputs(
    [
        {"name": "Nokia's New Name", "city": "Espoo"},
        {"name": "Alphabet", "city": "Mountain View"},
    ],
    ["1001", "1002"],
)
hs.batch_input = batch
updated_companies = hs.execute_batch()
print(
    "Companies have been updated:\\n" +
    "\\n".join([str(c) for c in updated_companies])
)

This library loads custom object schemas and pipelines into memory the first time when keywords using them are called. These cached versions are recalled unless the use_cache is set to False, where available.

All keywords that request a parameter of object_type can accept custom object type names as long as they are properly configured in HubSpot. The system will lookup the custom object ID using the provided name against the configured name or one of the configured labels (e.g., "singular" and "plural" types of the name).

This section describes the types of objects returned by this Library and their associated attributes. These attributes can be accessed via dot-notation as described in the Attribute Access section below.

Attribute Access

Keywords return native Python Hubspot objects, rather than common Robot Framework types. These types have sets of defined attributes allowing for dot-notation access of object properties. Properties (e.g., those configured in Hubspot settings for each object) will be accessible in a Python dictionary attached to the properties attribute of the returned object. See the Attribute Definitions section for details of that associated attributes for all types returned by this library.

Example usage retrieving the city property of a Company object:

Robot framework example:

*** Settings ***
Library         RPA.Hubspot
Library         RPA.Robocorp.Vault

Task Setup      Authorize Hubspot

*** Variables ***
${ACCOUNT_NOKIA}    6818764598

*** Tasks ***
Obtain city information from Hubspot
    ${account}=    Get object    COMPANY    ${ACCOUNT_NOKIA}
    Log    The city for account number ${ACCOUNT_NOKIA} is ${account.properties}[city]

*** Keywords ***
Authorize Hubspot
    ${secrets}=    Get secret    hubspot
    Auth with api key    ${secrets}[API_KEY]

Python example:

from RPA.Hubspot import Hubspot
from RPA.Robocorp.Vault import RobocorpVault

vault = RobocorpVault()
secrets = vault.get_secret("hubspot")

hs = Hubspot(secrets["API_KEY"])
nokia_account_id = "6818764598"
account = hs.get_object("COMPANY", nokia_account_id)
print(f"The city for account number {nokia_account_id} is {account.properties['city']}")

Attribute Definitions

This library can return various types of objects, whose attributes are only accessible via dot-notation. The below reference describes the attributes available on these objects.

SimplePublicObject

An object in HubSpot. The object itself does not describe what type it represents.

id : str
The HubSpot ID of the object.
properties : Dict[str, str]
A dictionary representing all returned properties associated to this object. Properties must be accessed as via standard dictionary subscription, e.g., properties["name"].
created_at : datetime
The timestamp when this object was created in HubSpot.
updated_at : datetime
The last modified timestamp for this object.
archived : bool
Whether this object is archived.
archived_at : datetime
The timestamp when this object was archived.

SimplePublicObjectWithAssociations

An object in HubSpot including associations to other objects. The object itself does not describe what type it represents.

id : str
The HubSpot ID of the object.
properties : Dict[str, str]
A dictionary representing all returned properties associated to this object. Properties must be accessed as via standard dictionary subscription, e.g., properties["name"].
created_at : datetime
The timestamp when this object was created in HubSpot.
updated_at : datetime
The last modified timestamp for this object.
archived : bool
Whether this object is archived.
archived_at : datetime
The timestamp when this object was archived.
associations : Dict[str, CollectionResponseAssociatedId]
A dictionary whose key will be the requested association type, e.g., companies and associated value will be a container object with all the associations. See CollectionResponseAssociatedId.

AssociatedId

The ID of an associated object, as well as the type of association.

id : str
The ID of the associated HubSpot object.
type : str
The type of association, e.g., deals_to_companies.

CollectionResponseAssociatedId

A container object for a collection of AssociatedId objects returned by the API.

results : List[AssociatedId]
The list of AssociatedId objects returned by the API.
paging : Paging
Used by this library to assist with retreiving multi-page API responses.

Pipeline

A pipeline represents the steps objects travel through within HubSpot.

id : str
The HubSpot ID for the pipeline. All accounts start with one pipeline with the id default.
label : str
The human-readabel label for the pipeline.
stages : List[PipelineStage]
A list of PipelineStage objects in the order the object would follow through the pipeline.
created_at : datetime
The timestamp when this pipeline was created in HubSpot.
updated_at : datetime
The last modified timestamp for this pipeline.
archived : bool
Whether this pipeline is archived.
display_order : int
The place in the list of pipelines where this pipeline is shown in the HubSpot UI.

PipelineStage

A pipeline stage is one of the various stages defined in a Pipeline.

id : str
The HubSpot ID of the stage.
label : str
The human-readabel label for the stage.
metadata : Dict[str, str]
A dictionary of additional data associated with ths stage, such as probability.
created_at : datetime
The timestamp when this stage was created in HubSpot.
updated_at : datetime
The last modified timestamp for this stage.
archived : bool
Whether this stage is archived.
archived_at : datetime
The timestamp when this stage was archived.

PublicOwner

An owner in HubSpot. Owners of companies and deals are responsible for driving a sale to close or similar.

id : str
The HubSpot ID of the owner.
email : str
The owner's email address in HubSpot.
first_name : str
The owner's first name.
last_name : str
The owner's last name.
user_id : int
The associated user ID if the owner is a HubSpot user.
created_at : datetime
The timestamp when this owner was created in HubSpot.
updated_at : datetime
The last modified timestamp for this owner.
archived : bool
Whether this owner is archived.
teams : List[PublicTeam]
A list of teams the owner is in. See PublicTeam.

PublicTeam

A team of owners in HubSpot

id : str
The HubSpot ID of the Team.
name : str
The Team's name.
membership : str
One of PRIMARY, SECONDARY, or CHILD.