Define custom events

Last modified: August 28, 2025

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.

Create an event definition

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. The request body below provides a basic example of an event definition:

{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}

If you want to automatically link event completions to records of a specified CRM object type, you can include a customMatchingId in your POST request. Within this field, define a primaryObjectRule object with two fields: the unique object property that you’ve set up beforehand as the targetObjectPropertyName, and one of the properties you defined in the propertyDefinitions from your event definition. For example, the following request body specifies a customMatchingId that matches on a CRM object property name of "unique_object_property" and the event property name of "string_property":

{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}

A full list of available parameters for the request body are detailed in the table below:

Parameter	Type	Description
`label`	String	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 label. This property cannot be changed after the event definition is created. This property can only contain lowercase letters, numbers, underscores, and hyphens (up to 50 characters). The first character must be a letter.
`description`	String	The event’s description, which will display in HubSpot.
`primaryObject`	String	The type of CRM object that event data will be associated with. Event completions will appear on the CRM records of that object type. Can be one of: `"CONTACT"` (default), `"COMPANY"`, `"DEAL"`, `"TICKET"`, `"<CUSTOM_OBJECT_NAME>"`. This cannot be changed after the event definition is created.
`propertyDefinitions`	Array	In addition to the HubSpot default event properties, you can include this array to define custom event properties (up to 50). For each property object, include the following fields: `name`: the property’s internal name, which you’ll use when sending event data through the API. `label`: the property’s in-app label. `type`: the type of property. Default is `string`. `options`: for `enumeration` type properties, this array defines the available values. Must include both a `label` and `value` for each option. `description`: text that describes the property.
`customMatchingId`	Object	As an alternative to including the target object’s `objectId` in the event completion data, this optional field defines a rule to automatically link event completions to records of the specified CRM object type. This is done by matching the value of a property in the event data with the value of a unique property on the target object. This object must include a nested `primaryObjectRule` object, which in turn must include two fields: `targetObjectPropertyName`: a string that specifies the name of the unique property on the target CRM object to use for matching. `eventPropertyName`: a string that specifies the name of the property in the custom event data to use for matching.
`includeDefaultProperties`	Boolean	An optional field that specifies whether the event should include the set of default event properties. If no value is provided, this field will automatically be set to `true`.

Event properties

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:

bool: a property that receives a boolean value. Values must be represented as true or false.
date: a property that receives a date representing a specific day, month, and year. Values must be represented in UTC time and can be formatted as ISO 8601 strings or EPOCH-timestamps in milliseconds (i.e. midnight UTC).
datetime: A property that receives epoch millisecond or ISO8601 values representing a timestamp.
enumeration: A property with predefined options. When creating this property type, include an options array to set the available values.
number: a property that receives numeric values with up to one decimal.
string: a property that receives plain text strings. If the property name contains the words url, referrer, or link, the property value can be up to 1024 characters. Otherwise, property values can be up to 256 characters.

Below, learn about HubSpot’s default event properties, how to define new properties for existing events, and how to update existing custom event properties.

HubSpot’s default 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

Define new properties

To define a new property on an existing custom event, make a POST request to events/v3/event-definitions/{eventName}/property. In the request body, include the definition for your property.

{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}

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.

Update existing custom properties

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.

Delete a property

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.

Update an event

To update an existing custom event schema, make a PATCH request to events/v3/event-definitions/{eventName}. The only event definition fields that can be updated are label and description.

{
  "label": "Event label",
  "description": "A description of the event"
}

Delete an event

To delete a custom event, make a DELETE request to events/v3/event-definitions/{eventName}. Deleting a custom event will remove it from any other HubSpot tools that are referencing it, such as workflows and reports.

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, so exercise caution when deleting an event.

Get existing event definitions

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 the name 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.

Events

Event Definitions

Event Completions

Create an event definition

Event properties

HubSpot’s default event properties

Define new properties

Update existing custom properties

Please note:

Delete a property

Update an event

Delete an event

Please note when deleting an event:

Get existing event definitions

Events

Event Definitions

Event Completions

​Create an event definition

​Event properties

​HubSpot’s default event properties

​Define new properties

​Update existing custom properties

​Please note:

​Delete a property

​Update an event

​Delete an event

​Please note when deleting an event:

​Get existing event definitions

Create an event definition

Event properties

HubSpot’s default event properties

Define new properties

Update existing custom properties

Please note:

Delete a property

Update an event

Delete an event

Please note when deleting an event:

Get existing event definitions