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.
Importing
The library can be imported with the API key or Access Token supplied, but this may preclude the ability to use secrets from the Control Room Vault or similar credential manager.