Access and test APIs in beta. 

Please note: This API is currently under development and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer TermsDeveloper BetaTerms. You also acknowledge and understand the risk associated with testing an unstable API. 

This API is currently in beta. For the latest stable version check out these pages: Get Events, Get Event by ID, Get a Group of Events by ID.

Custom Behavioral Events

  • Marketing Hub
    • Enterprise

Custom behavioral events are account-defined events that store event details in event properties. There are three types of custom behavioral events that you can create in HubSpot:

  • Manually tracked behavioral events are custom events that are unique to your business that are not captured automatically by HubSpot or by an integration. You can manually send data to these events through this API.

Below, learn how to create a manually tracked custom behavioral event, send event data through the API, and to use event data once captured.

Create an event

To set up your event, first create the event in HubSpot. When creating the event, HubSpot will include a set of default event properties that you can use to store event data. You can also create additional properties for the event. These properties can be created or edited at any time. 

Once you’ve set up your event, you can send data to it through the API.

Send event data

To send event data to HubSpot, make a POST request to There is a limit of 30 million custom behavioral events that can be logged per month in your account.

In the request body, you'll need to include event information as well as a contact to associate the event completion with. The following fields are required when triggering a custom behavioral event:

  • Identifier: Either the contact ID, email, or utk of the contact associated with the event.
  • Event name: the internal name of the event, which can be found in HubSpot. Learn how to find an event's internal namecustom-event-internal-name

Send property data

To include specific properties in the request body, use the following format:

"properties": { "property1": "string", "property2": "string", "property3": "string" }

The values you send will depend on the type of event property. Most of the default event properties are single-line text (string). However, you can create custom properties of any type for each event. Review the table below when formatting property values.

Use this table to describe parameters / fields
Property typeDescription

A string representing a set of options. When sending multiple values, separate them with a semicolon. In HubSpot, this type corresponds to dropdown select, radio select, and multiple checkbox properties.


A timestamp in the form of epoch milliseconds or ISO8601. In HubSpot, this type corresponds to date picker properties.


A plain text string limited to 65,536 characters. In HubSpot, this type corresponds to single-line and multi-line text properties.


A number value containing numeric digits and at most one decimal. In HubSpot, this type corresponds to number and calculation properties.

To view an event's available properties:

  • In HubSpot, navigate to Reports > Analytics Tools.
  • Click Custom Behavioral Events.
  • Click the name of the event.
  • Click the Properties tab.
  • In the properties table, view the property type under the name of the property. custom-event-properties-table


Set the time of an event

To specify the time of event completion, you can include a timestamp in an occurredAt field in your request. By default, if you do not include this field, HubSpot will set the completion time as the time of sending the request. The occurredAt field can be helpful if you want to store a different timestamp than when the API itself fired. For example, you have an event Attended Partner Webinar. The webinar took place two weeks ago, but you only received the data today. You could set the occuredAt property to include a timestamp from two weeks ago, which will set those dates in HubSpot accordingly.

Example request body

Below is an example request body for a login event which sends city, country, page, and interaction source data to HubSpot. The contact that completed the event is represented by the objectId field. For more details on sending event data, click the Endpoints tab at the top of this article.

// POST to https://api/ { "eventName": "pe1234567_login_event", "properties": { "hs_city": "Cambridge", "hs_country": "United States", "hs_page_id": "53005768010", "hs_page_content_type": "LANDING_PAGE", "hs_touchpoint_source":"DIRECT_TRAFFIC" }, "objectType": "contacts", "objectId": "608051" }

Exceeding any of the following limits will result in a failed request:

  • The property label and internal name are limited to 50 characters.
  • URL and referrer properties can receive up to 1024 characters, while all other properties can receive up to 256 characters.
  • Each event completion can contain data for up to 50 properties.
  • Property internal names must start with a letter and contain only lowercase letters a-z, numbers 0-9, and underscores.
  • Properties with the same internal name after lowercasing are considered duplicates, and only one of the properties will be used on completion. HubSpot will sort in ascending lexicographical order and keep the last property seen among the first 50 properties.

Retrieve event data

To retrieve a contact's event data, make a GET request to /events/v3/events/eventType={EVENT_NAME}&objectType=contact&objectId={CONTACT_ID}

The above request includes:

  • eventType: the internal name of the event.
  • objectType: the record's object type.
  • objectId: the contact's ID.

Attribution reporting

JavaScript events such as clicked element and visited URL events are automatically populated with asset type and interaction data for attribution reporting. To include the same data for manually tracked behavioral events, you'll need to manually include the data in the request body using event properties. Learn more about analyzing custom behavioral events.

Below, learn about the available values for asset types and interaction sources, along with example requests. 

Asset type

To attribute a specific asset type to a custom behavioral event request, include the hs_page_content_type property in the request body. For example:

// example request body { "eventName": "pe1234567_manually_tracked_event", "properties": { "hs_page_id": "53005768010", "hs_page_content_type": "LANDING_PAGE" }, "objectType": "contacts", "objectId": "6091051" }

You can also use the hs_asset_type property. If both hs_page_content_type and hs_asset_type are included in one request, hs_page_content_type will override the hs_asset_type value.

HubSpot's standard content types, such as landing pages and blog posts, can be represented with the following values:

Use this table to describe parameters / fields

An interaction with a website page.


An interaction with a landing page.


An interaction with a blog post.


An interaction with a knowledge base article.

For all other types of assets, use the following values:

Use this table to describe parameters / fields

An interaction with an ad, such as a Facebook or Google ad.


An interaction with a call.


An interaction via a contact import.


An interaction related to a HubSpot conversation.


The internal name of a custom behavioral event, such as pe123456_manually_tracked_event.


An interaction with an email.


An interaction with an external page.


An interaction via an integration.


An interaction with a marketing event.


An interaction via the media bridge.


An interaction with a meeting.


An interaction with a 1:1 sales email.


An interaction with a sequence.


An interaction with a social media post.


An interaction with an asset not in one of the above categories.

Asset title

To attribute a custom behavioral event to an asset, include the hs_page_title or hs_asset_title property in your request with the name of the asset formatted as a string. For example:


// example request body
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
 "objectType": "contacts",
 "objectId": "6091051"

Interaction sources

To attribute a custom behavioral event to a specific source, include the hs_touchpoint_source property in your request with one of the following values:

Use this table to describe parameters / fields

The interaction source is a conversation.


The interaction source is direct traffic.


The interaction source is a marketing email.


The interaction source is the HubSpot CRM.


The interaction source is an integration.


The interaction source is a marketing event.


The interaction source is offline.


The interaction source is organic search.


The interaction source is from an uncategorized campaign.


The interaction source is a paid search ad.


The interaction source is a paid social ad.


The interaction source is a referral.


The interaction source is sales.


The interaction source is social media (not a paid social ad).

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.