Hubspot (version v1.*.*)

add_contact_to_list#

Add contact records that have already been created in the system to a contact list. You can add multiple records at once, either by vid or by email address. Up to 500 records can be added to a list in a single request, including records specified by ID and by email. Please note that you cannot manually add contacts to dynamic lists. To determine whether a list is dynamic or static, when you get a list, you will see a flag called dynamic that equates to true or false.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/lists/add_contact_to_list

Type: object

{ }

batch_create_or_update_events#

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/timeline/batch-create-or-update-events

Type: object

{ }

create_batch_contacts#

Create a group of contacts or update them if they already exist. Particularly useful for periodic syncs from another contacts database to HubSpot.

Parameters

$body#

For formatting, see https://developers.hubspot.com/docs/methods/contacts/batch_create_or_update

Type: object

{
  "properties" : [ {
    "property" : "string",
    "value" : "string"
  } ]
}

auditId#

A string that allows you to represent these change sources however you'd like.

Type: string

create_contact#

Create a new contact in HubSpot with a simple HTTP POST to the Contacts API. The contact will be created instantly inside of HubSpot, and will be assigned a unique ID (vid) that can be used to look up the contact inside of HubSpot later.

Parameters

$body#

Properties for the contact to be added. While we recommend that all contact records include an email address, it is possible to create contacts without an email address by leaving out the email property.

Type: object

{
  "properties" : [ {
    "property" : "string",
    "value" : "string"
  } ]
}

create_contact_list#

Create a new list in a given HubSpot account to populate with contacts. Creating this list show in the user interface, so beware that users will be able to edit and even delete lists that are programatically created in HubSpot.

Parameters

$body#

See https://developers.hubspot.com/docs/methods/lists/create_list for format

Type: object

{ }

create_event_type#

Create Timeline Event Type for a particular application

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

userId (required)#

The ID of the user you're creating the event type for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/timeline/create-event-type

Type: object

{ }

create_or_update_contact#

Create a contact if it doesn't exist in an account already, or update it with the latest property values if it does. If successful, your request will return the unique identifier (VID) of the contact and whether or not the request was a create or an update.

Parameters

contact_email (required)#

Type: string

$body#

Properties for the contact to be created or updated. While we recommend that all contact records include an email address, it is possible to create contacts without an email address by leaving out the email property.

Type: object

{
  "properties" : [ {
    "property" : "string",
    "value" : "string"
  } ]
}

create_smtp_api_token#

This endpoint is used to create an SMTP API Token. An API token provides both a username and password which can then be used to send email through the HubSpot SMTP API.

Parameters

$body#

See format details at https://developers.hubspot.com/docs/methods/email/transactional_email/smtpapi_overview/list/create

Type: object

{ }

create_timeline_event_type_property#

Create a new property for a specified timeline event type.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

event_type_id (required)#

The ID of the event type you want to update.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/timeline/create-event-type-property

Type: object

{ }

create_update_event#

Create a new event, or update an existing event.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/timeline/create-or-update-event

Type: object

{ }

delete_contact#

Delete an existing contact from a particular HubSpot portal. If a contact with the same email address interacts with the portal again (via a form submission for example) the contact will be added back into the user interface.

Parameters

contact_id (required)#

You must pass the Contact's ID that you're deleting in the request URL.

Type: string

delete_contact_list#

Delete a list in a given HubSpot account, identified by its unique ID. Note that lists can be used by users to trigger marketing automation campaigns, so a good best practice is to only delete the lists that your integration with HubSpot has created.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

delete_event_type#

Delete an existing Timeline event type.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

get_batch_by_email#

For a given account, return information about a group of contacts by their email addresses. This method will also return you much of the HubSpot lead "intelligence" for each requested contact record. The endpoint accepts many query parameters that allow for customization based on a variety of integration use cases.

Parameters

email (required)#

The email of the contact that you want to get the data for. You can include this parameter multiple times to request multiple records. Any email address that doesn't belong to an existing contact record will be ignored. Requests should be limited to 100 or fewer emails.

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

includeDeletes#

Boolean "true" or "false" to indicate whether the return of deleted contacts is desired. Default is false.

Type: boolean

property#

Specify the properties that should be returned for each ID. By default, the endpoint returns all valued properties for a contact.

Type: string

propertyMode#

One of “value_only” or “value_and_history” to specify if the current value for a property should be fetched, or the value and all the historical values for that property. Default is “value_only”.

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

get_batch_by_user_token#

For a given account, return information about a group of contacts by their user tokens. A visitor's user token is stored in the hubspotutk cookie. This cookie is created automatically by the HubSpot tracking code. The endpoint accepts many query parameters that allow for customization based on a variety of integration use cases. By default, this endpoint will not return the history for properties, only the current value of any populated properties, but you can include the history using the parameters listed below.

Parameters

utk (required)#

Each user token requires it's own query parameter (utk=xxx&utk=yyy). Requests should be limited to 100 or fewer user tokens. Any user tokens that are provided that are not associated with a contact record will be ignored.

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

includeDeletes#

Boolean true or false to indicate whether the return of deleted contacts is desired. Default is false.

Type: boolean

property#

Specify the properties that should be returned for each ID. By default, the endpoint returns all valued properties for a contact. If this parameter is used, only the specified property or properties will be included.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

get_batch_by_vid#

For a given account, return information about a group of contacts by their unique IDs. A contact's unique ID is stored in a field called 'vid' which stands for 'visitor ID'. The endpoint accepts many query parameters that allow for customization based on a variety of integration use cases. By default, this endpoint will not return the history for properties, only the current value of any populated properties, but you can include the history using the parameters listed below.

Parameters

vid (required)#

Each vid requires it's own query parameter (vid=10&vid=11). Requests should be limited to 100 or fewer vids. Any vids that are provided that are invalid will be ignored.

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

includeDeletes#

Boolean true or false to indicate whether the return of deleted contacts is desired. Default is false.

Type: boolean

property#

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

get_batch_contact_lists#

For a given account, return a set of contact lists that you specify with multiple listId parameters. This will return only the metadata on these lists and not all of the contacts in the list. See this page for details on getting contact records in individual lists.

Parameters

listId (required)#

An integer that represents the list IDs that you want returned to your call. As you can see in the example URL below, you can specify as many "listId" parameters as you wish on the URL to return multiple lists at once. Any list IDs that are invalid will be ignored.

Type: string

get_campaign_data#

For a given campaign, return data associated with the campaign.

Parameters

campaign_id (required)#

The ID of the campaign you want to update.

Type: string

get_contact_by_email#

For a given account, return information about a single contact by its email address. Since all contacts in HubSpot are de-duplicated off of an email address, you will only ever receive a single contact back from the API.

Parameters

contact-email (required)#

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “all”.

Type: string

property#

By default, all valued properties will be included. If you include the "property" parameter, then the returned data will only include the property or properties that you request.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is true.

Type: boolean

get_contact_by_utk#

For a given account, return information about a single contact by its user token, stored in the hubspotutk cookie. This cookie is created automatically by the HubSpot tracking code.
This method will also return you much of the HubSpot lead "intelligence" for each requested contact record. The endpoint accepts many query parameters that allow for customization based on a variety of integration use cases.

Parameters

contact_utk (required)#

The user token (HubSpot cookie) for the contact that you're searching for.

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “all”.

Type: string

property#

By default, all valued properties will be included. If you include the "property" parameter, then the returned data will only include the property or properties that you request.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is true.

Type: boolean

get_contact_by_vid#

Update an existing contact in HubSpot. This method lets you update the properties of a contact in HubSpot.

Parameters

vid (required)#

Type: string

formSubmissionMode#

One of 'all', 'none', 'newest', 'oldest' to specify which form submissions should be fetched. Default is 'all'.

Type: string

property#

By default, you will get all properties that the contact has values for. If you include the "property" parameter, then the returned data will only include the property or properties that you request. You can include this parameter multiple times to specify multiple properties. The lastmodifieddate and associatedcompanyid will always be included, even if not specified. Keep in mind that only properties that have a value will be included in the response, even if specified in the URL.

Type: string

propertyMode#

One of 'value_only' or 'value_and_history' to specify if the current value for a property should be fetched, or the value and all the historical values for that property. Default is 'value_and_history'.

Type: string

showListMemberships#

Boolean 'true' or 'false' to indicate whether current list memberships should be fetched for the contact. Default is true.

Type: string

get_contact_list#

For a given portal, return a contact list by its unique ID. This returns only the metadata for the list; see this page for getting the contact records in the list. If you are not storing the list ids inside of your application, you'll need to first find the list id by using the get all lists endpoint.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

get_contact_property#

Returns a JSON object representing the definition for a given contact property.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/companies/get_contact_property

Type: object

{ }

get_event#

Get the data for a specific timeline event. All data that the event has will be returned, including the optional fields that were set for you.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

event_id (required)#

The ID of the event you want to retrieve.

Type: string

event_type_id (required)#

The ID of the event type you want to update.

Type: string

get_event_by_id#

Query the event log for a specific event and get results for that email event.

Parameters

created (required)#

The creation timestamp (in milliseconds since epoch) of the event to return.

Type: string

id (required)#

The unique ID of the event to return.

Type: string

get_lifecyclestages_for_contacts#

Returns the number of contacts that entered the individual lifecycle stages during the provided time period. The time period may be up to a two year window. Additionally supports aggregating the results by a second property. This property must be an enumerated property (such as a multiple checkbox or dropdown property) with 20 or fewer option. This would support custom enumerated properties.

Parameters

fromTimestamp (required)#

A millisecond timestamp representing the start of the time period that you want the stats for.

Type: integer

toTimestamp (required)#

A millisecond timestamp representing the end of the time period that you want the stats for.

Type: integer

aggregationProperty#

A second optional property to further breakdown the lifecycle stage buckets. This must be an enumerated property with 20 or fewer options.

Type: string

get_subscription_status#

For a given portal, return the email subscription information for the given email address and portal. For specific email subscription types, if the value is true or false, the definition will be returned. If the value is null for a specific type, nothing will be returned.

Parameters

email_address (required)#

The email address for which you are requesting subscription status.

Type: string

portalId (required)#

The HubSpot Portal ID for the portal that you're making the call for.

Type: string

get_timeline_event_type_properties#

Get the custom properties for a specified event type.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

event_type_id (required)#

The ID of the event type you want to update.

Type: string

list_all_contact_lists#

Return the contact lists for a portal. By default, you will get up to 20 lists to you at a time. You can get more lists in a single request (up to 250) using the count parameter.

This operation has no parameters

list_all_contacts#

For a given portal, return all contacts that have been created in the portal. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page.

Parameters

formSubmissionMode#

One of 'all', 'none', 'newest', 'oldest' to specify which form submissions should be fetched. Default is 'newest'.

Type: string

property#

If you include the 'property' parameter, then you will get the specified property in the response. This parameter may be included multiple times to specify multiple properties.

Type: string

propertyMode#

One of 'value_only' or 'value_and_history' to specify if the current value for a property should be fetched, or the value and all the historical values for that property. Default is 'value_only'.

Type: string

showListMemberships#

Boolean 'true' or 'false' to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: string

list_campaigns#

For a given portal, return all campaign IDs sorted by recent activity associated with the portal. The campaign IDs are returned in descending order of most-recent activity. You can then use the IDs to look up data on the perfomance of each campaign.

This operation has no parameters

list_campaigns_by_id#

For a given portal, return all email campaign IDs associated with the portal. The email campaign IDs are returned in no particular order. You can then use the IDs to look up data on the performance of each marketing email campaign.

This operation has no parameters

list_contact_lists_dynamic#

Get dynamic lists for a portal. Dynamic lists automatically update themselves when new contacts are created or are updated, meaning that you can't manually add contacts to dynamic lists.

This operation has no parameters

list_contact_lists_static#

Get static contact lists in a portal. Static lists (as opposed to dynamic lists) are lists that are edited (added to or updated) manually - via the add contact to list method, or manually in HubSpot.

This operation has no parameters

list_contacts_in_list#

For a given portal and a given list, identified by its unique ID, return a list of contacts that are in that list.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

property#

If you include the "property" parameter, then the properties in the "contact" object in the returned data will only include the property or properties that you request.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

list_email_events#

Query the event log for events matching specified parameters. Note that events will be returned in reverse-chronological order.

Parameters

appId#

Only return events which correspond to the given HubSpot Application ID.

Type: string

campaignId#

Only return events from the given HubSpot Campaign ID.

Type: string

endTimestamp#

Only return events which occurred at or before the given timestamp (in milliseconds since epoch).

Type: string

eventType#

Only return events of the specified type (case-sensitive). The possible types are described in the Email Events Bible .

Type: string

excludeFilteredEvents#

Only return events that have not been filtered out due to customer filtering settings. The default value is false.

Type: boolean

recipient#

Only return events related to the given recipient.

Type: string

startTimestamp#

Only return events which occurred at or after the given timestamp (in milliseconds since epoch).

Type: string

list_event_types#

Get Timeline Event Types for a particular application

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

userId (required)#

The ID of the user you're creating the event type for.

Type: string

list_recently_added_contacts_in_list#

For a given HubID and a given list, return contacts that have been recently added to that list, starting with the most recently added contact and pageing backwards. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page, as specified by the "count" parameter.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

property#

If you include the "property" parameter, then the properties in the "contact" object in the returned data will only include the property or properties that you request.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

list_recently_created_contacts#

For a given account, return all contacts that have been recently created. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page, as specified by the "count" parameter.

Parameters

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

property#

If you include the "property" parameter, then the properties in the "contact" object in the returned data will only include the property or properties that you request.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

list_recently_updated_contacts#

For a given portal, return all contacts that have been recently updated or created. A paginated list of contacts will be returned to you, with a maximum of 100 contacts per page, as specified by the "count" parameter. The endpoint only scrolls back in time 30 days.

Parameters

formSubmissionMode#

One of “all”, “none”, “newest”, “oldest” to specify which form submissions should be fetched. Default is “newest”.

Type: string

property#

If you include the "property" parameter, then the properties in the "contact" object in the returned data will only include the property or properties that you request.

Type: string

propertyMode#

Type: string

showListMemberships#

Boolean "true" or "false" to indicate whether current list memberships should be fetched for the contact. Default is false.

Type: boolean

list_smtp_api_tokens#

This operation has no parameters

list_subscriptions#

Returns all email subscription types that have been created in the given Hub ID.

Parameters

portalId (required)#

The HubSpot Portal ID for the portal that you're making the call for.

Type: string

list_subscriptions_timeline#

For a given portal, return a time-ordered list of subscription changes.

Parameters

changeType#

Only return timeline changes of the specified type (case-sensitive). The possible types are described in the Email Subscriptions Bible .

Type: string

endTimestamp#

Only return timeline items which occurred at or before the given timestamp (in milliseconds since epoch).

Type: string

includeSnapshots#

Include the user's full subscription snapshot with each timeline item. This snapshot is equivalent to what this endpoint would have returned at that time.

Type: string

startTimestamp#

Only return timeline items which occurred at or after the given timestamp (in milliseconds since epoch).

Type: string

merge_contacts#

Merge two contact records. The contact ID in the URL will be treated as the primary contact, and the contact ID in the request body will be treated as the secondary contact.

Parameters

contact_id (required)#

Unique identifier for a particular contact. In HubSpot's contact system, contact ID's are called "vid".

Type: string

$body#

properties for the contact to be updated

Type: object

{
  "vidToMerge" : "string"
}

reset_password#

Once you have an SMTP API, the List SMTP API Tokens endpoint can be used to list all SMTP API Tokens in the portal. However, for security reasons the password is only provided during the time of the token creation. This endpoint allows for the creation of a replacement password for a given Token, keyed by the userName field.

Parameters

userName (required)#

The userName field of the SMTP API Token needing a password reset.

Type: string

search_contacts#

For a given account, return contacts and some data associated with those contacts by the contact's email address, first and last name, phone number, and company name.

Parameters

q (required)#

The search term for what you're searching for. You can use all of a word or just parts of a word as well. For example, if you we're searching for contacts with "hubspot" in their name or email, searching for "hub" would also return contacts with "hubspot" in their email address.

Type: string

property#

If you include the "property" parameter, then the properties in the "contact" object in the returned data will only include the property or properties that you request.

Type: string

send_single_email#

Send an email designed and maintained in the HubSpot marketing Email Tool.

Parameters

$body#

See format details at https://developers.hubspot.com/docs/methods/email/transactional_email/single-send-overview

Type: object

{ }

update_contact_by_email#

Update an existing contact in HubSpot. This method lets you update the properties of a contact in HubSpot.

Parameters

contact-email (required)#

Type: string

$body#

properties for the contact to be updated

Type: object

{
  "properties" : [ {
    "property" : "string",
    "value" : "string"
  } ]
}

update_contact_by_vid#

Parameters

vid (required)#

Type: string

$body#

properties for the contact to be updated

Type: object

{
  "properties" : [ {
    "property" : "string",
    "value" : "string"
  } ]
}

update_event_type#

Update an existing event type.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

event_type_id (required)#

The ID of the event type you want to update.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/timeline/update-event-type

Type: object

{ }

update_list#

Update a list in a given HubSpot account. Note that like creating a list, users will be able to edit and even delete these lists inside of the HubSpot user interface.

Parameters

list_id (required)#

Unique identifier for the list that you're looking for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/lists/update_list

Type: object

{ }

update_subscription_status#

For a given email address, update the email type subscription status, or permanently unsubscribe an email address from all email.

Parameters

email_address (required)#

The email address for which you are requesting subscription status.

Type: string

portalId (required)#

The HubSpot Portal ID for the portal that you're making the call for.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/email/update_status

Type: object

{ }

update_timeline_event_type_property#

Update an existing property for a specified timeline event type. The id passed in the JSON body needs to match the id of an existing property or this will return a 404 error. Properties cannot be moved from one event type to another, so the eventTypeId included in the JSON body must match the event-type-id in the URL. Please note that the name cannot be updated.

Parameters

application_id (required)#

The ID of the OAuth app you're creating the event type for.

Type: string

event_type_id (required)#

The ID of the event type you want to update.

Type: string

$body#

See format details at https://developers.hubspot.com/docs/methods/timeline/udpate-timeline-event-type-property

Type: object

{ }