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 Terms& Developer 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

OverviewEndpoints

Sending custom behavioral events 

Custom behavioral events are account-defined events. This doc will cover creating your event via the API.  Tracking events via the API allows you to track events that are unique to your business, as well as events that may not be automatically captured by HubSpot or by an integration. In addition to adding metadata (properties) to these events, you can use custom behavioral events across the HubSpot platform as if it were a HubSpot-defined event. HubSpot supports both custom properties and standard properties with custom behavioral events.

Getting started: a two-step process

Successfully setting up custom behavioral events is a two-part process. First, you must define (or name) your events and properties in the app. The UI allows you to define your portal-specific custom behavioral event. You can also define what properties you want to associate with your custom behavioral event to store metadata about the event.

Once you’ve set up your custom behavioral event, you can send these events. The following sections will walk you through sending your event via the API

Associations between custom behavioral events and objects

Custom behavioral events can be associated with contacts. They have a many-to-many relationship with contacts, meaning multiple contacts can be associated with a single event. Likewise, many events can be associated with a single contact.

Required fields and time stamping

The following are required values to include when triggering a custom behavioral event:

  • Identifier
  • Event Name

An identifier must be provided to tie the event to an object. For example for a contact you must provide either the contact id, an email or the utk of a contact.

Timestamps can be included to backdate events or if left blank the current timestamp will be used to date events. That means that you can provide HubSpot with a different timestamp than when the API itself fired. For example, your custom behavioral event may be ‘Attended Partner Webinar.’ The webinar took place two weeks ago, but you did not receive the data until today and are now ready to send this data to HubSpot. If you specify the exact date and time the event actually occurred in the timestamp field, HubSpot will recognize the event as happening two weeks prior.

Sending your event

Events HTTP API:   POST api.hubspot.com/events/v3/send 

This API is used to trigger a custom HubSpot event using an HTTP POST call. Note: You must have a Marketing Hub Enterprise subscription for access to the events tool.

Use case for this endpoint: You can use this call to trigger any custom events in your HubSpot account. Those events can then be used to track activity.

Response details

If the request is successful, it will have a status code of 200 with a response object in the body. The content-type will be application/json. We recommend using the JavaScript API on web pages when possible.

Method Details

HTTP Methods: [POST]

Response Format: [Response]

Requires Authentication?: [Yes]

Rate Limited?: Yes

Products: Marketing

Required Scope: BEHAVIORAL_EVENTS_INGESTION

Please note: Events will only be processed for accounts with  Marketing Hub Enterprise.  Each event must include at least one identifier, either utk, email or objectId.

 

POST BODY

  

DESCRIPTION

HubSpot Hub (portalId)

  

Your HubSpot Hub ID. See this page for help finding your Hub ID.

Optional - UTK (utk)

  

User token associated with a contact 

Optional - Email (email)

  

Email associated with a contact

Optional - Timestamp (timestamp)

  

When event occurred, can be backdated

Event Name (eventName)

  

Name of the event

Optional - Properties (properties)

  

Map of properties

Optional - Object Id (objectId)

  

Associated object id, for example a contact event will contain the contact id

 

Sample POST BODY for a CONTACT event

JSON 
//example
{
  "portalId": 123,
  "objectId": 456,
  "Utk": "1f234bb1-12ab-1234-sa11-123456",
  "email": "example@hubspot.com",
  "timestamp": 1498512177478,
  "eventName": pe123_eventname,
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Attribution reporting and custom behavioral events

One of the advantages to this API is that you tell HubSpot’s attribution reporting system to include specific events as a touchpoint in an attribution report. For example, you can tell HubSpot attribution reporting to listen to events like ‘Logged into mobile app’ or ‘Entered portal’ and attribute revenue to these moments as if they were any other event HubSpot is attributing revenue to.

If you know that there will be an event triggered through the HTTP API that you’ll want to include in attribution reporting, you can fill out HubSpot’s standard properties with the metadata that makes sense to how your business operates. For events that are fired through JavaScript, this won’t be necessary, as HubSpot will automatically listen for the other events happening nearby to triage the missing data.

Metadata HubSpot’s attribution system needs to include a custom behavioral event in reporting:

 

Asset Types 

AD("AD")

BLOG_POST("BLOG_POST"),

CALL("CALL"),

CONTACT_IMPORT("CONTACT_IMPORT"),

CONVERSATION("CONVERSATION"),

CUSTOM_BEHAVIORAL_EVENT("CUSTOM_BEHAVIORAL_EVENT"),

EMAIL("EMAIL"),

EXTERNAL_PAGE("EXTERNAL_PAGE"),

HUBSPOT_PAGE("HUBSPOT_PAGE"),

INTEGRATIONS("INTEGRATIONS"),

KNOWLEDGE_ARTICLE("KNOWLEDGE_ARTICLE"),

LANDING_PAGE("LANDING_PAGE"),

LISTING_PAGE("LISTING_PAGE"),

MARKETING_EVENT("MARKETING_EVENT"),

MEDIA_BRIDGE("MEDIA_BRIDGE"),

MEETING("MEETING"),

OTHER("OTHER"),

SALES_EMAIL("SALES_EMAIL"),

SEQUENCE("SEQUENCE"),

SOCIAL_POST("SOCIAL_POST"),

WEBSITE_PAGE("WEBSITE_PAGE");
 

Interaction Source 

CONVERSATION("CONVERSATION"),

DIRECT_TRAFFIC("DIRECT_TRAFFIC"),

EMAIL_MARKETING("EMAIL_MARKETING"),

HUBSPOT_CRM("HUBSPOT_CRM"),

INTEGRATION("INTEGRATION"),

MARKETING_EVENT("MARKETING_EVENT"),

OFFLINE("OFFLINE"),

ORGANIC_SEARCH("ORGANIC_SEARCH"),

OTHER_CAMPAIGNS("OTHER_CAMPAIGNS"),

PAID_SEARCH("PAID_SEARCH"),

PAID_SOCIAL("PAID_SOCIAL"),

REFERRALS("REFERRALS"),

SALES("SALES"),

SOCIAL_MEDIA("SOCIAL_MEDIA");

 

Asset Title

String value
Was this page helpful? *
This form is for feedback on our developer docs. If you have feedback on the HubSpot product, please share it in our Idea Forum instead.