Define custom events
-
Marketing Hub
- Enterprise
-
Sales Hub
- Enterprise
-
Service Hub
- Enterprise
-
Content Hub
- Enterprise
-
Operations Hub
- Enterprise
Custom events enable you to define and track events that are unique to your business, such as events on your site or in an app. You can configure events to store information within properties, which you can then use across HubSpot's tools.
To send custom event data to HubSpot, you first need to define the event. This is similar to custom CRM objects, where you first need to define the custom object before you can create individual records for that object. An event definition includes details such as its metadata, CRM object associations, and properties.
Below, learn more about creating and managing event definitions using the API. To learn how to create event definitions without using the API, check out HubSpot's Knowledge Base.
To create the custom event schema, make a POST
request to events/v3/event-definitions
. In the request body, include definitions for your event schema, including its label, name, CRM object associations, and custom properties.
Below is an example request body along with parameter definitions. For a full example, view the custom event example below.
label string (required)
The event's human readable label, which will display in HubSpot (up to 100 characters). Long labels may be cut off in certain parts of HubSpot's UI. |
name string
The unique, internal name of the event, which you'll use to reference the event through the API. If no value is provided, HubSpot will automatically generate one based on the Note the following naming requirements:
|
description string
The event's description, which will display in HubSpot. |
primaryObject string
The CRM object that the event will be associated with. Event completions will display on CRM record timelines of the specified object. Can be one of If no value is provided, HubSpot will automatically associate the event with contacts. This cannot be changed after the event definition is created. |
propertyDefinitions array
For each custom event definition, HubSpot provides a set of default properties that you can use when sending event data. Include this array to define any custom properties that your event needs outside of those default properties. You can include up to 50 custom properties per event. For each property, include:
Learn more about custom event properties below. |
Custom event properties are used to store information on individual custom event completions. These properties should be used when appropriate for sending event completions, but they are not required for an event completion to be valid. For each event definition, HubSpot provides a default set of 32 properties. In addition, You can create up to 50 custom properties per event definition.
Properties can be of the following types:
string
: a property that receives plain text strings. If the property name contains the wordsurl
,referrer
, orlink
, the property value can be up to 1024 characters. Otherwise, property values can be up to 256 characters.number
: a property that receives numeric values with up to one decimal.enumeration
: A property with pre-defined options. When creating this property type, include anoptions
array to set the available values.datetime
: A property that receives epoch millisecond or ISO8601 values representing a timestamp.
Below, learn about HubSpot's default event properties, how to define new properties for existing events, and how to update existing custom event properties.
hs_asset_description
hs_asset_type
hs_browser
hs_campaign_id
hs_city
hs_country
hs_device_name
hs_device_type
hs_element_class
hs_element_id
hs_element_text
hs_language
hs_link_href
hs_operating_system
hs_operating_version
hs_page_content_type
hs_page_id
hs_page_title
hs_page_url
hs_parent_module_id
hs_referrer
hs_region
hs_screen_height
hs_screen_width
hs_touchpoint_source
hs_tracking_name
hs_user_agent
hs_utm_campaign
hs_utm_content
hs_utm_medium
hs_utm_source
hs_utm_term
When naming your property, keep the following in mind:
- Once you create a property, the property’s name cannot be changed.
- The name can only contain lowercase letters, numbers, underscores, and hyphens.
- The first character of the property name must be a letter.
- The property name and label can each be up to 50 characters long.
- If an property name is not provided, one will be auto-generated using the property label.
- Long labels may be cut off in certain parts of the HubSpot UI.
To update an existing property on a custom event, make a PATCH
request to events/v3/event-definitions/{eventName}/property
. The only fields that can be updated on a property are the label
, description
, and options
for enumeration properties.
Please note: to change the type of property, use the DELETE
endpoint to delete the property and recreate it with the correct type.
To delete an existing property on a custom event, make a DELETE
request to events/v3/event-definitions/{eventName}/property/{propertyName}
.
When a property is deleted, it will no longer be available for use in future event completions. Past completions will still have the property values.
Please note: when deleting an event:
- All of the events for that event definition will be deleted and unrecoverable.
- Previously deleted
eventName
's cannot be used again.
The only fields that can be updated on an event definition are the label
and description
.
To update an existing custom event schema, make a PATCH
request to events/v3/event-definitions/{eventName}
.
When you delete a custom event, references to that event in other HubSpot tools, such as workflows and reports, will no longer use the event.
To delete a custom event, make a DELETE
request to events/v3/event-definitions/{eventName}
.
To fetch a single event definition, make a GET
request to events/v3/event-definitions/{eventName}
.
To search event definitions by specific criteria, make a GET
request to events/v3/event-definitions
. You can supply the following query parameters to refine your search:
searchString
: searches for events that contain the specified characters in thename
field. Searching is not fuzzy, but is instead a naive contains search.after
: a hashed string provided in paged responses for viewing the next page of search results.limit
: the maximum number of results to return.includeProperties
: a boolean value that specifies whether to include event properties in the returned results.
The following is a walkthrough of creating an example custom event.
This walkthrough covers:
1. creating a custom event definition.
2. creating a new property on the event definition.
Goal: a car dealership called CarSpot has an online inventory of all cars available on their lot. CarSpot wants to track when visitors to their site view a specific car available on their lot. To do so, they'll create a custom event, which they'll associate with contact records to track who views the listing. This event will also need a set of custom properties to store the car listing details viewed during each event.
Having decided what to call the event, what properties they'd like to include with each triggered event, and the CRM object they want to associate events with, they'll create the event schema by making a POST
request to /events/v3/event-definitions
with the following request body:
Just after implementing the event on their website, CarSpot decided that they want to see if listing price will influence click rate. To track this, they'll create a new property containing the price of the listing.
To define a new property, they'll make a POST
request to /events/v3/event-definitions/viewed_car/property
with the following request body:
With their custom event defined, they can now send event data to HubSpot using this custom event definition.
Thank you for your feedback, it means a lot to us.