Send custom event completions

OverviewEndpoints
APPLICABLE PRODUCTS
  • Marketing Hub
    • Enterprise
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise
  • Content Hub
    • Enterprise
  • Operations Hub
    • Enterprise

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

  • Clicked element and visited URL events are custom events that the tracking code automatically populates with data. You can further customize these events by updating your tracking code with the trackCustomEvent function. 
  • Manually tracked 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 event, send event data through the API, and to use event data once captured.

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

// POST to https://api/hubspot.com/events/v3/send { "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_touchpoint_source":"DIRECT_TRAFFIC" } }
Use this table to describe parameters / fields
ParameterTypeDescription
eventName
Required
String

The internal name of the event. You can find this by querying your existing event definitions or within the HubSpot app.

objectId
Required
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 User Token. All other object types require objectId.

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. Learn more about event properties below.

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.
  • There is a limit of 500 unique event definitions per account.
  • There is a limit of 30 million event completions per month. 

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.

Event properties

Event data is stored in properties, either in the set of default event properties or in custom defined properties. When sending event data, you'll can update properties by including them in a properties object.

"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
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 timestamp in the form of epoch milliseconds or ISO8601. In HubSpot, this type corresponds to date picker properties.

string

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

number

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 your HubSpot account, navigate to Reporting > Data Management > Custom 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

 

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:

// 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
ValueDescription
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:

Use this table to describe parameters / fields
ValueDescription
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:

JSON 
// 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
ValueDescription
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).
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.