Send custom event completions

Last modified: August 28, 2025

Custom events are account-defined events that store event details in event properties. In addition to customizing your tracking code to send event data to HubSpot, you can also send event completion data via this API. Below, learn how to use the API to create custom events and send/retrieve custom event data.

Define the event

To send event completion data to HubSpot, you first need to define the event itself, including its metadata, CRM object associations, and properties. You can define events using the custom event definition API, or if you have a Marketing Hub Enterprise subscription you can create the event in HubSpot. When creating the event, HubSpot will provide the option to 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 or by customizing your HubSpot tracking code.

Send event data

To send event data to HubSpot, make a POST request to https://api.hubspot.com/events/v3/send with your event data in the request body. Before sending event data, review the limits below, as exceeding these limits will result in an error.

{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}

Parameter	Type	Description
`eventName`	String	The internal name of the event. You can find this by querying your existing event definitions or within the HubSpot app.
`objectId`	String	The ID of the CRM record that the event will be associated with. For contacts, you can alternatively use the `email` or `utk` field to identify the contact by email address or HubSpot usertoken. All other object types require `objectId`, unless a custom matching ID is defined for the event. If a `customMatchingId` is defined for the event, HubSpot will automatically set or override the `objectId` based on the configured mapping. Learn more in the custom event definitions guide.
`occurredAt`	String	By default, HubSpot will set the event completion timestamp to the time that the request is sent. To specify the time of event completion, include a timestamp in an `occurredAt` field in the `POST` request body (ISO 8601 format). This can be especially helpful for backdating event data to more accurately reflect real-life event completion.
`properties`	Object	The event properties to send data to. This can include HubSpot’s default event properties or any custom properties you’ve defined for the event. Most default event properties are string properties, but you can review all event properties by either querying the event definition or navigating to the event in HubSpot. If a custom matching ID is set up for the event, you may omit the `objectId`. HubSpot will attempt to link the event with a CRM object by setting the `objectId` on the event based on the configured mapping. Learn more about event properties below.

Retrieve event data

To retrieve event data, make a GET request to /events/v3/events.

To return all event completions for a specific event, include the eventType parameter along with the internal event name (e.g., pe123456_custom_event). You can retrieve all event types using the event analytics API.
To return event completions for a specific object, include the objectType parameter along with either the objectId or objectProperty.<property> parameters. The objectType should specify the type of CRM object (e.g., contact), while the other parameters specify the unique identifier value for the object (either record ID or a unique identifier property value). For contacts, you can use email as a unique identifier property.

For example, to retrieve all events completed by a specific contact, your request URL could be: /events/v3/events?objectType=contact&objectId=111111. Alternatively, you can use the contact’s email address: /events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com To filter the results by event completions with a specific event property value, you can include the property.<propertyName> parameter. For example, to retrieve page visit events for your homepage, your request URL might be: /events/v3/events?eventType=e_visited_page&property.hs_page_title=home

For property values with spaces, replace the spaces with either %20 or +. For example: property.hs_page_title=home+page.

Learn more about available parameters in the reference documentation.

Event properties

Event completion data is stored in event properties, either in the set of default event properties or in custom-defined properties. When sending event data, include a properties object with key-value pairs for the properties you want to update along with the property values to store.

"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.

Property type	Description
`bool`	A boolean value, either `true` or `false`.
`enumeration`	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.
`date`	A value 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 timestamp representing a specific day, month, year, and time of day. Values must be represented in UTC time and can be formatted as ISO 8601 strings or UNIX-timestamps in milliseconds.
`number`	A number value containing numeric digits and at most one decimal. In HubSpot, this type corresponds to number and calculation properties.
`string`	A plain text string limited to 65,536 characters. In HubSpot, this type corresponds to single-line and multi-line text properties.

To view an event’s available properties:

In your HubSpot account, navigate to Data Management > Custom Events.
In the table, click the name of the event.
At the top, click the Properties tab.
In the properties table, view the property type under the name of the property.

Limits

When sending event data, 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 1,024 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.

The following limits also apply to the custom event endpoints:

There is a limit of 500 unique event definitions per account.
There is a limit of 30 million event completions per month.
The send custom event completions endpoint supports up to 1250 requests per second.
The custom event completion batch endpoint supports batches of 500.

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 events, you’ll need to manually include the data in the request body using event properties. Learn more about analyzing custom 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:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "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:

Value	Description
`STANDARD_PAGE`	An interaction with a website page.
`LANDING_PAGE`	An interaction with a landing page.
`BLOG_POST`	An interaction with a blog post.
`KNOWLEDGE_ARTICLE`	An interaction with a knowledge base article.

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

Value	Description
`AD`	An interaction with an ad, such as a Facebook or Google ad.
`CALL`	An interaction with a call.
`CONTACT_IMPORT`	An interaction via a contact import.
`CONVERSATION`	An interaction related to a HubSpot conversation.
`CUSTOM_BEHAVIORAL_EVENT_NAME`	The internal name of a custom event, such as `pe123456_manually_tracked_event`.
`EMAIL`	An interaction with an email.
`EXTERNAL_PAGE`	An interaction with an external page.
`INTEGRATIONS`	An interaction via an integration.
`MARKETING_EVENT`	An interaction with a marketing event.
`MEDIA_BRIDGE`	An interaction via the media bridge.
`MEETING`	An interaction with a meeting.
`SALES_EMAIL`	An interaction with a 1:1 sales email.
`SEQUENCE`	An interaction with a sequence.
`SOCIAL_POST`	An interaction with a social media post.
`OTHER`	An interaction with an asset not in one of the above categories.

Asset title

To attribute a custom 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: hs_page_title:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "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:

Value	Description
`CONVERSATION`	The interaction source is a conversation.
`DIRECT_TRAFFIC`	The interaction source is direct traffic.
`EMAIL_MARKETING`	The interaction source is a marketing email.
`HUBSPOT_CRM`	The interaction source is the HubSpot CRM.
`INTEGRATION`	The interaction source is an integration.
`MARKETING_EVENT`	The interaction source is a marketing event.
`OFFLINE`	The interaction source is offline.
`ORGANIC_SEARCH`	The interaction source is organic search.
`OTHER_CAMPAIGNS`	The interaction source is from an uncategorized campaign.
`PAID_SEARCH`	The interaction source is a paid search ad.
`PAID_SOCIAL`	The interaction source is a paid social ad.
`REFERRALS`	The interaction source is a referral.
`SALES`	The interaction source is sales.
`SOCIAL_MEDIA`	The interaction source is social media (not a paid social ad).

Events

Event Definitions

Event Completions

Send custom event completions

Define the event

Send event data

Retrieve event data

Event properties

Limits

Attribution reporting

Asset type

Asset title

Interaction sources

Events

Event Definitions

Event Completions

​Define the event

​Send event data

​Retrieve event data

​Event properties

​Limits

​Attribution reporting

​Asset type

​Asset title

​Interaction sources

Define the event

Send event data

Retrieve event data

Event properties

Limits

Attribution reporting

Asset type

Asset title

Interaction sources