Media Bridge

This API is in beta.

Please note: This API is currently in public beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer Developer Beta Terms of Use. You also acknowledge and understand the risk associated with testing an unstable API. 

This API is currently under development. While it is, you'll need to keep some things in mind:

  • Create & edit Media Bridge objects: Developers can push media into the portal as Media Bridge objects, and experiment with CRM APIs for manipulating the underlying objects. Please let us know ( once you have created your Media Bridge object so we can allowlist them as part of this beta phase’s requirement.
  • Familiarize with CMS modules/module fields: Developers can consider which fields might be useful for their apps’ module, and embed media in a CMS page with the crm_object or crm_objects HubL functions.
  • Push events into HubSpot tools: Developers can push Played Events into the CRM contact activity timeline, and Played Events and Quartile Events into the custom report builder and revenue attribution reports

Why Media Bridge?

The Media Bridge API provides a way for integrators to push media and media consumption data into HubSpot. It also facilitates creating a set of out-of-box media features for HubSpot users. These features include: 

  • Module components that make it easy for customers to embed the media in HubSpot’s drag and drop editors, such as in pages and email.
  • CRM timeline events that show when prospects or customers have engaged with videos, audio, and other media types. 
  • Lists that can be generated to create targeted, personalized experiences.
  • Workflows to automate interactions, based on media consumption events.
  • Reporting to gain insight into how contacts and companies engage with media and measure the ROI of media assets.

Underlying Technologies: The media bridge is built on top of a couple of core technologies that HubSpot has built: Custom Objects and Unified Events, which is our new events tracking system. While third party integrators will be able to do everything they will need to with the native media bridge APIs, we will also expose information about the underlying objects so that integrators can directly interact with the custom objects APIs if they want to do something that is not natively supported via the media bridge API.

Using your developer portal

For both registering your app, and setting up your initial object definitions, you will be doing this by calling apis from your developer portal that your app lives in. This is done by making the api calls and including your developer portal’s portalId as a “portalId” query parameter, and by including your developer portal’s hapikey as a “hapikey” query param with your request. This allows us to make sure that only the owner of each media bridge object is able to modify parts of the object definition.

Registering your app with Media Bridge

In order for your app to work correctly with the Media Bridge, you must register your app with the media bridge before any other action can be done. The only required field of the registration API call is a name field. The name registered here will be used as the default prefix of your object’s labels in the HubSpot App. For example, if the name provided was “Example Co.”, the video objects would be labeled “Example Co. Videos” throughout the HubSpot app.

Creating your initial Media Bridge Definition(s)

Before you start sending Media objects in the Media Bridge, you will need to let the Media Bridge know that you intend to create Media objects of a certain Media Type (VIDEO, AUDIO, or IMAGE) use the POST /media-bridge/{appId}/settings/object-definitions endpoint. This allows the Media Bridge to set up your App Object with the required properties. This process of telling the Media Bridge that you want to create objects for a certain Media type can be called more than once, so there is no need to worry about defining each media type you may want to use in the future in this initial request.  

Customizing your Media Bridge Object Definition

Once the initial media object definition has been created, developers are able to create and modify the various properties of their objects. This can be done using the /media-bridge/v1/{appId}/schemas and /media-bridge/v1/{appId}/properties apis. These APIs use the same request and response objects as their CRM api counterparts, but have layered some additional logic in them that allow media bridge developers to use them when normally these developers would not be able to use these APIs yet. This is set up this way so that in the future, when App Objects (CRM Objects created by an App) are fully released and supported by the CRM APIs, media bridge developers can make a one line change of switching the API paths, and everything will work as expected.

Installing your Media Bridge App into a Portal

Now that your initial setup is done, you can now start installing your app into a test portal. In order for your app to have the right permissions when it is installed into a portal, your app will need to request the and media_bridge.write scopes. Now it’s time to install. The install is done via OAuth. During testing this can be done by manually hitting the OAuth URL and authenticating into your portal. When it is live for customers, this OAuth flow will be available either via that URL surfaced somewhere in your webpage, or via the marketplace, and the user clicking the install button.

To verify the app is installed correctly, visit{accountId} and it should be listed on the upper right. This Demo UI offers an easy way to view created objects via a Picker panel.

Creating your Media Objects

Now that you have registered your app with the Media Bridge, and you have told the Media Bridge what types of media you want to use, you are ready to start creating those media objects. To start creating media bridge objects, developers will need to install their app into a portal. This will allow developers to get an OAuth token that will be used for requests to create and modify media objects in the portal. Some additional documentation on OAuth can be found in our OAuth developer documentation. Since the Media Bridge objects are CRM Objects, we urge developers to use the Crm Object Apis. These APIs expect an “Object Type” as part of most requests, and developers can find the Object Type of their Media Bridge objects by calling the GET /media-bridge/v1/{appId}/settings/object-definitions/{mediaType} API endpoint

A media object represents a piece of embeddable content in a third party system. Once a media object is added to the media bridge, it will be made available for embedding in HubSpot CMS content, and available to associate with media events.

For Video and Audio media, this table lists out all of the default/required properties of those media types:

Default Object Properties

VIDEO and AUDIO (* denotes required)

Default Required properties of the audio video media types

An id used to identify the specific piece of media in HubSpot’s media bridge system. This is autogenerated by HubSpot, and cannot be set by developers.


The duration of the media in milliseconds.


A URL that must return a valid oEmbed response that follows the oEmbed spec. Requires video or rich type with an iframe in html.


The URL of the raw media file. This may be used in the future to help support social embedding.


URL to an image that will be used as the thumbnail for embedding the media into content in places such as the media picker. The ideal size for this thumbnail is 640x480 pixels.


URL of an image representing the media. This image should be the same dimensions as the original media, and may be used in places where an image placeholder is needed (for example, when the media is inserted in an email).


The id of the media in the third party’s system. This gives integrators the ability to fetch media from the media bridge based on the same id that they use in their own system. (This is the api endpoint that leverages this mapping)


A provider-supplied path to the object, intended to represent the object’s location in the third party’s folder system (if any). HubSpot will attempt to represent this directory structure when displaying these objects to the user, but may nest each provider’s objects and folders within a top-level folder named after the provider.


The name of the media. This will be shown inside of the HubSpot UI in places such as the media picker.


A URL that allows a user to view or interact with the media in the media provider’s system. This is used in the HubSpot UI to give users the ability to identify the media without relying on just the title.

IMAGE media type - same as above, other than

  • hs_oembed_url must return a oEmbed type photo with a url attribute
  • hs_file_url is required
  • hs_duration and hs_poster_url are removed

Creating CMS Modules to embed media

Each provider is responsible for creating their own module to render their media in the HubSpot CMS. 

The Embed field gains a new “Media integration” source type when MB integrations are installed, which allows selecting media with via a Picker panel. After selecting, the media’s oembed_url and oembed_response are available in HubL to easily render players

Additionally, the id and media_type of selected media are stored to enable querying for the underlying CRM object via the crm_objects hubl function. This can be used to pull any or all of the properties that are part of a media object. 

Example use of crm_objects function where the id of the media objects are 459 and 922:

Apps can fetch the object_type` (“a123_Videos” in the example) using the GET /media-bridge/{appId}/settings/object-definitions/{mediaType} API.

{% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }

Fetch a specific image: {% set object = crm_object("a123_Images", 459) %} {{ object }}

Getting started with Custom Modules

To start building a custom module, visit the Marketing > Files and Templates > Design Tools section of HubSpot. Click the "Add field" dropdown to add an Embed field.

Check the "Media integration" option in the "Support source types" field (requires a Media Bridge integration to be installed in the account). This will enable the Embed field to select Media Bridge media via a Picker panel.

embed field - source types

To display the selected media use the "Copy snippet" and paste into the module.html section.

Click "Preview" in the upper right, and it should be possible to select Media Bridge media in the left sidebar via "Select from  ". 


embed field - after select


Sending your events

A media event is an event that happens in relation to a media object, like a play event. Once a media event is sent to the media bridge, it will be available for use in the report builder, available for the contact timeline.

There are 3 types of events that the Media Bridge supports out of the box, a Played event, a Quartile event, and an Attention Span event.

A Played event represents when a user has begun playing a piece of media.

A Quartile event represents when a user has reached quarterly milestones (0%, 25%, 50%, 75%, 100%) in terms of how much the media they have consumed.

An Attention span event represents a more holistic view of how the user consumed the media.

Event Reporting Cadence

While the media bridge does not strictly enforce any restrictions on how events are reported from third parties, for the sake of consistency, we do have preferred intervals at which certain events get reported.

Played Event: Intended to be reported when a user has started to consume a piece of the media.

Attention Span Event: Intended to be reported when a user has fully consumed a piece of media, or once the user has completed their session.

Quartile Event: Intended to be reported on a rolling basis as the user reaches each quartile milestone of percent of media consumed.

Displaying events on the Contact Timeline
In order to have events show up on the contact timeline, we require that a “Media Played” event is sent for every session. Events from a session will have a single card on the contact activity timeline. 

Connecting an event to a contact

In order to connect a media event to a contact, integrators must provide either a contactId or a contactUtk. If a contactUtk is provided, the API will handle converting that into a contactId. If both a contactId and contactUtk are provided in the request, we will use the contactId as the source of truth. This allows the media bridge to create an association between the contact that the event. This association enables the media bridge to unlock cross-object reporting, allowing customers to connect their media events to not only individual contacts, but also the companies those contacts are a part of, as well as deals that those contacts are involved in. Due to this requirement, we encourage developers to inform their users about potential discrepancies between the data that is available in HubSpot and the developer’s own app.

Connecting an event to a piece of media

We require that every event contains either a mediaId or an externalId, and if both are provided, we will treat the mediaId as the source of truth. We require this to be included in events so that HubSpot users know what media an event is associated with.

Connecting an event to a page

Information about what pages an event happens on can help HubSpot users gain a better big picture idea of where their media is being consumed. In order to connect a media event to a page, integrators can provide a pageId if it is a page hosted on the HubSpot CMS, or a pair of pageName and pageUrl for pages hosted outside of HubSpot’s CMS.

This table outlines all of the properties for the three events that the Media Bridge support natively:

Use this table to describe parameters / fields
PropertyEvent TypeDescription
All Events

The id of the media that this event is related to.


The id of the media in the third party’s system. This gives developers the ability to refer to media in the media bridge based on the same id that they use in their own system. This can be used instead of the mediaBridgeObjectId in events if developers chose. If both an externalId and mediaBridgeObjectId are provided, the mediaBridgeObjectId will be used and the externalId will be ignored.

All Events

A unique identifier to represent a viewing session. This can mean different things to different providers, and HubSpot is letting providers decide what a session means to them. This will be used to group events that happened in the same session together. This is expected to be generated by the third party’s system.

All Events

The id of the contact in HubSpot’s system that consumed the media. This can be fetched using HubSpot's contact from utk api.The API also supports supplying a UTK, and will handle converting this into a contact ID automatically.

All Events

The UTK token that identifies what contact consumed the media.

All Events

The content Id of the page that an event happened on.

All Events

The name or title of the page that an event happened on.

All Events

The URL of the page that an event happened on.

All Events

The timestamp at which this event occurred, in milliseconds since the epoch.

attentionSpanMapString / attentionSpanMap
Attention Span

This is the raw data which provides the most granular data about spans of the media, and how many times each span was consumed by the user. 

Example: consider a 10 second video where each second is a span. If a visitor watches the first 5 seconds of the video, then restarts the video and watches the first 2 seconds again, the resulting attentionSpanMapString would be “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”.

Attention Span

The percent of the media that the user consumed. Providers may calculate this differently depending on how they consider repeated views of the same portion of media. For this reason, the API will not attempt to validate totalPercentWatched against the attention span information for the event. If it is missing, HubSpot will calculate this from the attention span map as follows: (number of spans with a value of 1 or more)/(Total number of spans).

Attention Span

The seconds that a user spent consuming the media. The media bridge calculates this as totalPercentPlayed*mediaDuration. If a provider would like this to be calculated differently, they can provide the pre-calculated value when they create the event

Quartile Event

A quartile percent value (0, 25, 50, 75, 100) for how much of the media has been consumed so far.

Played Event

A URL that can be used to display data from an external system using an iFrame. When included, the event on the contact timeline will display a link that will open a modal window displaying the iFrame contents when clicked.


The media type that the event belongs to. (VIDEO, AUDIO) This allows us to properly assign the event to the correct objects when a single provider has support for multiple media types.

Was this article helpful? *
This form is used for documentation feedback only. Learn how to get help with HubSpot...