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 Description
object_idstr, NoneNone
propertiesnullA dictionary of HubSpot properties to set to the HubSpot object being created or updated.

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

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

Arguments

Argument Type Default value Description
api_keystrnullThe API key for the account to autheniticate to.
param api_key:The API key for the account to autheniticate 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 Description
access_tokenstrnullThe access token created for the Private App in your HubSpot account.
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 Description
object_typestrnullThe object type to be created or updated by the batch.
modeBatchModenulleither UPDATE or CREATE.

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 Description
object_typenullThe object type to be created.
propertiesnullAll 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.

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 Description
propertiesList[Dict[str, str]]nullA list of dictionaries of HubSpot properties to set to the HubSpot objects being created or updated.
idsList[str], NoneNoneThe 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.

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 Description
object_typestrnullThe object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
object_idstrnullThe ID of the object to be returned.
id_propertystr, NoneNone(Optional) Can be used to allow the API to search the object database using an alternate property as the unique ID.
label_as_keyboolTrue(Optional) Defaults to True. Setting this to False will cause the returned dictionary to key off of id instead of label.
use_cacheboolTrue(Optional) Setting this to False will force the system to recache the pipelines from Hubspot.

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 Description
object_typestrnullThe object type to be returned and that has the ID indicated.
object_idstr, List[str]nullThe ID of the object to be returned.
id_propertystr, NoneNone(Optional) Can be used to allow the API to search the object database using an alternate property as the unique ID.
propertiesstr, List[str], NoneNone(Optional) A list of strings representing property names to be included in the returned object. Nonexistent properties are ignored.
associationsstr, List[str], NoneNone(Optional) A list of strings representing object types to retrieve as associated object IDs.

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 Description
owner_idstrThe owner's HubSpot ID.
owner_emailstrThe email address registered to the owner.
user_idstrThe owner's associated HubSpot user ID.

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 Description
hs_objectSimplePublicObject, SimplePublicObjectWithAssociations, Dictnull
owner_propertystr, NoneNoneAn alternate property of the provided object to use as the field containing the Owner to be looked up.

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 Description
object_typestrnullThe object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
pipeline_idstrnullThe numerical pipeline ID or the pipeline label visibal in the HubSpot UI (case sensitive).
use_cacheboolTrue(Optional) Setting this to False will force the system to recache the pipelines from Hubspot.

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 Description
object_typestrnullThe object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
pipeline_idstrnullThe numerical pipeline ID or the pipeline label visibal in the HubSpot UI (case sensitive).
label_as_keyboolTrue(Optional) Defaults to True. Setting this to False will cause the returned dictionary to key off of id instead of label.
use_cacheboolTrue(Optional) Setting this to False will force the system to recache the pipelines from Hubspot.

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 Description
user_idstr
user_emailstr

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 Description
object_typestrnullThe type of object for the object ID provided, e.g. contact.
object_idstr, List[str]nullThe 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.
to_object_typestrnullThe type of object associations to return.

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 Description
object_typestrnullThe object type to be returned and that has the ID indicated. Custom objects will be validated against the schema.
archivedboolFalse(Optional) Setting this to True will return archived pipelines as well.
use_cacheboolTrue(Optional) Setting this to False will force the system to recache the pipelines from Hubspot.

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 Description
object_typestrnull
natural_searchnullall additional unlabeled parameters will be parsed as a natural language search.
searchList[Dict], NoneNonethe search object to use as search criteria.
string_querystra 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.
propertiesstr, List[str], NoneNonea list of strings representing return properties to be included in the returned data.
max_resultsint1000
  • 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 Description
object_typestrnullThe type of object for the object ID provided, e.g. contact.
object_idstrnullThe HubSpot ID for the object of type object_type.
to_object_typestrnullThe type of object to associate the object_id to.
to_object_idstrnullThe HubSpot ID for the object to associate the object_id to.
association_typestrNone

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 Description
batch_inputBatchInputFactorynullA batch object such as one returned from the Get current batch keyword.

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 Description
object_typestrnullThe object type to be created.
object_idstr, List[str]nullThe HubSpot ID of the object to be updated
id_propertystr, NoneNone
propertiesnullAll 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.

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.