Add Input To Batch

Add the provided free-named keyword arguments to the current batch input. If creating an UPDATE batch, you must also provide the Hubspot object id (an alternate ID property cannot be used).

Arguments

Argument	Type	Default value
object_id	str, None	None
properties		null

The keyword will fail if an ID is provided to a batch that is currently in CREATE mode and has any inputs already.

See Batch Inputs` for complete information on using the batch input API.

param properties:	A dictionary of HubSpot properties to set to the HubSpot object being created or updated.
param id:	The HubSpot ID of the object to be updated. If provided, the batch is assumed to be in UPDATE mode. The keyword will fail if an ID is provided to a batch that is currently in CREATE mode and has any inputs already.

Auth With Api Key

Deprecated! Use Auth With Token instead.

Arguments

Argument	Type	Default value
api_key	str	null

Authorize to HubSpot with an account-wide API key. This keyword verifies the provided credentials by retrieving the custom object schema from the API.

param api_key:	The API key for the account to authenticate to.

Auth With Token

Authorize to HubSpot with Private App access token. This keyword verifies the provided credentials by retrieving the custom object schema from the API.

Arguments

Argument	Type	Default value
access_token	str	null

Learn more about Private Apps: https://developers.hubspot.com/docs/api/private-apps

param access_token:	The access token created for the Private App in your HubSpot account.

Clear Current Batch

Returns the current batch and then clears it.

See Batch Inputs` for complete information on using the batch input API.

Create New Batch

Creates a new blank batch input for the provided object_type in either the UPDATE or CREATE mode.

Arguments

Argument	Type	Default value
object_type	str	null
mode	BatchMode	null

See Batch Inputs` for complete information on using the batch input API.

param object_type:	The object type to be created or updated by the batch.
param mode:	either `UPDATE` or `CREATE`.

Create Object

Creates a new Hubspot object of the provided object_type and with the provided properties in Hubspot. Read-only or nonexistent properties are ignored. The object_type parameter automatically looks up custom object IDs based on the provided name.

Arguments

Argument	Type	Default value
object_type		null
properties		null

The Hubspot properties to be updated must be provided as additional labeled paremeters to this keyword.

Returns the newly created object. The new object's id is available via the property id.

param object_type:	The object type to be created.
param properties:	All remaining labeled parameters passed into this keyword will be used as the properties of the new object. Read-only or nonexistent properties will be ignored.

Execute Batch

Sends the current batch input to the Hubspot API.

Keyword will only fail if all inputs resulted in error. Partial failures are reported as warnings.

See Batch Inputs` for complete information on using the batch input API.

return:	The updated or created objects as a list of `SimplePublicObject` types.

Extend Batch With Inputs

Extends the current batch input with the provided lists of Hubspot properties and Hubspot object ids. The ids parameter must be provided when extending an UPDATE batch. The two provided lists will be zipped together in the same order as provided.

Arguments

Argument	Type	Default value
properties	List[Dict[str, str]]	null
ids	List[str], None	None

The keyword will fail if an ID is provided to a batch that is currently in CREATE mode and has any inputs already.

See Batch Inputs` for complete information on using the batch input API.

param properties:	A list of dictionaries of HubSpot properties to set to the HubSpot objects being created or updated.
param ids:	The HubSpot IDs of the objects to be updated. If provided, the batch is assumed to be in UPDATE mode. The keyword will fail if an ID is provided to a batch that is currently in CREATE mode and has any inputs already.

Get Current Batch

Returns the current batch.

See Batch Inputs` for complete information on using the batch input API.

return:	The current batch input object.

Get Current Batch Inputs

Returns the inputs in the current batch. The returned list will be a list of dictionaries each with either 1 or 2 keys depending on if the batch is in CREATE or UPDATE mode. If in UPDATE mode, the dictionaries will have the keys properties and id, but if in CREATE mode, the dictionaries will only have the properties key.

See Batch Inputs` for complete information on using the batch input API.

return:	A list of dictionaries representing the current inputs.

Get Current Stage Of Object

Returns the current pipeline stage for the object as a tuple of the stage label and that stage's associated metadata as a dictionary. If you want the label to be returned as the numerical API ID, set label_as_key to False.

Arguments

Argument	Type	Default value
object_type	str	null
object_id	str	null
id_property	str, None	None
label_as_key	bool	True
use_cache	bool	True

If the object type does not have an applied pipeline, the keyword will fail.

This keyword caches results for future use, to refresh results from Hupspot, set use_cache to False.

param object_type:	The object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
param object_id:	The ID of the object to be returned.
param id_property:	(Optional) Can be used to allow the API to search the object database using an alternate property as the unique ID.
param label_as_key:	(Optional) Defaults to `True`. Setting this to `False` will cause the returned dictionary to key off of `id` instead of `label`.
param use_cache:	(Optional) Setting this to `False` will force the system to recache the pipelines from Hubspot.
return:	A tuple where index 0 is the label or ID of the object's current stage and index 1 is associated data.

Get Object

Reads objects of object_type from HubSpot with the provided object_id. The objects can be found using an alternate ID by providing the name of that HubSpot property which contains the unique identifier to id_property. The object_type parameter automatically looks up custom object IDs based on the provided name. If a list of object IDs is provided, the batch API will be utilized, but in that case, associations cannot be returned.

Arguments

Argument	Type	Default value
object_type	str	null
object_id	str, List[str]	null
id_property	str, None	None
properties	List[str], str, None	None
associations	List[str], str, None	None

A list of property names can be provided to properties and they will be included in the returned object. Nonexistent properties are ignored.

A list of object types can be provided to associations and all object IDs associated to the returned object of that type will be returned as well. Object types passed to this parameter are also validated against built-in objects and custom object schemas.

param object_type:	The object type to be returned and that has the ID indicated.
param object_id:	The ID of the object to be returned.
param id_property:	(Optional) Can be used to allow the API to search the object database using an alternate property as the unique ID.
param properties:	(Optional) A list of strings representing property names to be included in the returned object. Nonexistent properties are ignored.
param associations:	(Optional) A list of strings representing object types to retrieve as associated object IDs.
return:	The requested object as a `SimplePublicObject` or `SimplePublicObjectWithAssociations` type. If a batch request was made, it returns a list of `SimplePublicObject`.

Get Owner By Id

Returns an owner object with details about a HubSpot user denoted as an owner of another HubSpot object, such as a contact or company. You may provide the identifier as owner_id, owner_email, or user_id. The owner_id will correspond to fields from the CRM API while the user_id will correspond to the user provisioning API (see keyword Get User).

Arguments

Argument	Type	Default value
owner_id	str
owner_email	str
user_id	str

The owner object has the following attributes (accessible via dot notation):

If more than one of these IDs are provided, the keyword prefers the owner_id, then owner_email, then the user_id.

param owner_id:	The owner's HubSpot ID.
param owner_email:	The email address registered to the owner.
param user_id:	The owner's associated HubSpot user ID.
return:	The requested `PublicOwner` object.

Get Owner Of Object

Looks up the owner of a given Hubspot object, the provided object should be from this library or it should be a dictionary with an hubspot_owner_id key. If the object has no owner, this keyword returns None. See keyword Get owner by ID for information about the returned object.

Arguments

Argument	Type	Default value
hs_object	SimplePublicObject, SimplePublicObjectWithAssociations, Dict	null
owner_property	str, None	None

You can use an alternate property as the owner ID property by providing it with argument owner_property. If that property does not exist this keyword will try the default hubspot_owner_id property, instead.

param object:	A HubSpot object, best if the object was obtained via another keyword such as `Get owner by ID`
param owner_property:	An alternate property of the provided object to use as the field containing the Owner to be looked up.
return:	The `PublicOwner` of the provided object.

Get Pipeline

Returns the object_type pipeline identified by pipeline_id. The provided pipeline_id can be provided as the label (case sensitive) or API ID code.

Arguments

Argument	Type	Default value
object_type	str	null
pipeline_id	str	null
use_cache	bool	True

The Pipeline object returned includes a stages property, which is a list of PipelineStage objects. The stages of the pipeline represent the discreet steps an object travels through within the pipeline. The order of the steps is determined by the display_order property. These properties can be accessessed with dot notation and generator comprehension; however, these are advanced Python concepts, so it is generally easier to use the keyword Get Pipeline Stages to get an ordered dictionary of the stages from first to last.

Example

*** Tasks ***
Get Step One
    ${pipeline}=    Get pipeline    DEALS   default
    ${step_one}=    Evaluate
    ... next((s.label for s in $pipeline.stages if s.display_order == 0))

This keyword caches results for future use, to refresh results from Hupspot, set use_cache to False.

param object_type:	The object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
param pipeline_id:	The numerical pipeline ID or the pipeline label visibal in the HubSpot UI (case sensitive).
param use_cache:	(Optional) Setting this to `False` will force the system to recache the pipelines from Hubspot.
return:	The `Pipeline` object requested.

Get Pipeline Stages

Returns a dictionary representing the stages available in the requested pipeline. Only pipelines for object_type are searched using the pipeline_id as the label or Hubspot API identifier code.

Arguments

Argument	Type	Default value
object_type	str	null
pipeline_id	str	null
label_as_key	bool	True
use_cache	bool	True

By default, the keys of the returned dictionary represent the labels of the stages, in order from first to last stage. You can have the keyword return the numerical API ID as the key instead by setting label_as_key to False.

Each item's value is a dictionary with three keys: id, label and metadata. The id is the numerical API ID associated with the stage and label is the name of that stage. The metadata is a dictionary of metadata associated with that stage (e.g., isClosed and probability for "deals" pipelines) that is unique per pipeline.

Example

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

Task Setup      Authorize Hubspot

*** Tasks ***
Use pipeline stages
    ${stages}=    Get pipeline stages    DEALS    Default
    ${closed_won_stage_id}=    Set variable    ${stages}[Closed Won][id]
    ${deals}=    Search for objects    DEALS
    ...    dealstage    EQ    ${closed_won_stage_id}
    Log    Deals that have been won: ${deals}

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

This keyword caches results for future use, to refresh results from Hupspot, set use_cache to False.

param object_type:	The object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
param pipeline_id:	The numerical pipeline ID or the pipeline label visibal in the HubSpot UI (case sensitive).
param label_as_key:	(Optional) Defaults to `True`. Setting this to `False` will cause the returned dictionary to key off of `id` instead of `label`.
param use_cache:	(Optional) Setting this to `False` will force the system to recache the pipelines from Hubspot.
return:	A dictionary representing the pipeline stages and associated data.

Get User

Returns a dictionary with the keys id and email based on the provided user_id or user_email. If both are provided, this keyword will prefer the user_id.

Arguments

Argument	Type	Default value
user_id	str
user_email	str

Note

This keyword searches system users, not the CRM owners database.

List Associations

List associations of an object by type, you must define the object_type with its object_id. You must also provide the associated objects with to_object_type. The API will return a list of dictionaries with the associated object id and association type (e.g., contact_to_company).

Arguments

Argument	Type	Default value
object_type	str	null
object_id	str, List[str]	null
to_object_type	str	null

You may provide a list of object IDs, if you do, the return object is a dictionary where the keys are the requested IDs and the value associated to each key is a list of associated objects (like a single search).

param object_type:	The type of object for the object ID provided, e.g. `contact`.
param object_id:	The HubSpot ID for the object of type `object_type`. If you provide a list of object_ids, they will be searched via the batch read API.
param to_object_type:	The type of object associations to return.
return:	A list of dictionaries representing the associated objects. The associated objects are returned as `AssociatedId` objects.

List Pipelines

Returns a list of all pipelines configured in Hubspot for the provided object_type. By default only active, unarchived pipelines are returned.

Arguments

Argument	Type	Default value
object_type	str	null
archived	bool	False
use_cache	bool	True

This keyword caches results for future use, to refresh results from Hupspot, set use_cache to False.

param object_type:	The object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
param archived:	(Optional) Setting this to `True` will return archived pipelines as well.
param use_cache:	(Optional) Setting this to `False` will force the system to recache the pipelines from Hubspot.
return:	A list of `Pipeline` objects representing the pipelines associated with the provided `object_type`.

Search For Objects

Returns a list of objects of the specified type based on the provided search criteria. The following types are supported:

Arguments

Argument	Type	Default value
object_type	str	null
natural_search		null
search	List[Dict], None	None
string_query	str
properties	List[str], str, None	None
max_results	int	1000

COMPANIES
CONTACTS
DEALS
FEEDBACK SUBMISSIONS
PRODUCTS
TICKETS
LINE ITEMS
QUOTES
Custom objects, which can be provided as the name of the object or the custom object ID in Hubspot.

Returns no more than max_results which defaults to 1,000 records. Provide 0 for all results.

By default, search criteria can be passed as additional unlabeled arguments to the keyword. They must be provided in order: property_name, operator, value. Boolean operators AND and OR can be used, but if both are used, groups of criteria combined with AND will be combined first, with each of those groups being combined with OR second. You can only define a maximum of three groups of filters combined with OR and each of those groups can have no more than three filters combined with AND.

You can use the following operators in your search:

OPERATOR	DESCRIPTION
LT	Less than
LTE	Less than or equal to
GT	Greater than
GTE	Greater than or equal to
EQ	Equal to
NEQ	Not equal to
BETWEEN	Within the specified range
IN	Included within the specified list
NOT_IN	Not included within the specified list
HAS_PROPERTY	Has a value for the specified property. When using this operator, or its opposite below, you cannot provide a value.
NOT_HAS_PROPERTY	Doesn't have a value for the specified property.
CONTAINS_TOKEN	Contains a token.
NOT_CONTAINS_TOKEN	Doesn't contain a token.

Example search:

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

*** Tasks ***
Obtain contacts with search
    ${contacts}=    Search for objects    CONTACTS
    ...    firstname    EQ    Alice    AND    lastname    NEQ    Smith
    ...    OR    enum1    HAS_PROPERTY
    ${message}=    Catenate    These contacts will have the first name "Alice" but not the last name "Smith",
    ...    or they will have a value in the proeprty "enum1": ${contacts}
    Log    ${message}

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

Alternatively, search criteria can be passed as a list of dictionaries to the label-only parameter search.

To include multiple filter criteria, you can group filters within filterGroups:

When multiple filters are present within a filterGroup, they'll be combined using a logical AND operator.
When multiple filterGroups are included in the request body, they'll be combined using a logical OR operator.

You can include a maximum of three filterGroups with up to three filters in each group.

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

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

hs = Hubspot(secrets["API_KEY"])

combination_search = [
    {
        "filters": [
            {
                "propertyName": "firstname",
                "operator": "EQ",
                "value": "Alice",
            },
            {
                "propertyName": "lastname",
                "operator": "NEQ",
                "value": "Smith",
            },
        ]
    },
    {"filters": [{"propertyName": "enum1", "operator": "HAS_PROPERTY"}]},
]
contacts = hs.search_for_objects("CONTACTS", search=combination_search)
print(
    "These contacts will have the first name 'Alice' but not the "
    + "last name 'Smith', or they will have a value in the "
    + f"property 'enum1': {contacts}"
)

Controlling Returned Properties

You can retrieve additional properties for the objects by defining them with properties. Properties must be provided as a single property as a string, or a list of properties as a list. If a requested property does not exist, it will be ignored.

Using Associations

Associated objects can be used as search criteria by using the pseudo-property associations.{object_type}, where {object_type} is a valid object type, such as contact, but this is not supported when seaching custom objects.

Text-based Search Query

If you want to search all text-based fields with a simple string, it can be provided via the optional label-only parameter string_query. This cannot be used at the same time with search_object or natural_search parameters.

param natural_search:	all additional unlabeled parameters will be parsed as a natural language search.
param search:	the search object to use as search criteria.
param string_query:	a string query can be provided instead of a search object which is used as a text-based search in all default searchable properties in Hubspot.
param properties:	a list of strings representing return properties to be included in the returned data.
return:	A list of found HubSpot objects of type `SimplePublicObject`.

Set Association

Sets an association between two Hubspot objects. You must define the primary object_type and it's Hubspot object_id, as well as the Hubspot object it is to be associated with by using the to_object_type and to_object_id. You may also define the association_type, but if not, one will be inferred based on the provided object types, for example, if object_type is company and to_object_type is contact, the inferred association_type will be company_to_contact.

Arguments

Argument	Type	Default value
object_type	str	null
object_id	str	null
to_object_type	str	null
to_object_id	str	null
association_type	str	None

Returns the object with it's associations.

param object_type:	The type of object for the object ID provided, e.g. `contact`.
param object_id:	The HubSpot ID for the object of type `object_type`.
param to_object_type:	The type of object to associate the `object_id` to.
param to_object_id:	The HubSpot ID for the object to associate the `object_id` to.
return:	The object represented by the `object_id` with the new association. The associations will be available on the returned object's `associations` property.

Set Current Batch Input

Sets the current batch input to the provided one.

Arguments

Argument	Type	Default value
batch_input	BatchInputFactory	null

See Batch Inputs` for complete information on using the batch input API.

param batch_input:	A batch object such as one returned from the `Get current batch` keyword.

Update Object

Performs a partial update of an Object identified by object_type and object_id with the provided properties in Hubspot. The objects can be found using an alternate ID by providing the name of that HubSpot property which contains the unique identifier to id_property. The object_type parameter automatically looks up custom object IDs based on the provided name.

Arguments

Argument	Type	Default value
object_type	str	null
object_id	str, List[str]	null
id_property	str, None	None
properties		null

The Hubspot properties to be updated must be provided as additional labeled paremeters to this keyword.

Returns the newly created object. The new object's id is available via the property id.

param object_type:	The object type to be created.
param object_id:	The HubSpot ID of the object to be updated
param properties:	All remaining labeled parameters passed into this keyword will be used as the properties of the new object. Read-only or nonexistent properties will be ignored.