Customizing HubSpot using the CRM Cards API

I'm regularly talking with people looking to get the most out of their HubSpot portals. More often than not they've got a multitude of different systems that they need HubSpot to communicate with and whilst they don't necessarily need to login to each of those systems it's crucial that they are able to view the data and interact with them without ever leaving the HubSpot CRM.

Some common scenarios I typically see are outlined in more detail below:

• The marketing team and/or sales teams are going to be using HubSpot but their support team is using another tool to manage customer tickets. It would be beneficial for them to have total visibility on these tickets before reaching out to ensure for a truly tailored experience. It would also be helpful to provide these teams with a way of passing important information back to the support team directly from Hubspot.
• The sales team are using HubSpot but all of the accounting and invoicing occurs in another system. The details of the invoices are important to have visible from within HubSpot and ideally they'd be able to create an invoice without ever having to leave the HubSpot CRM.
• The customer support team is using Hubspot but their product/engineering team are managing various software issues and bugs from another tool. The details of those issues are important to have surfaced in the CRM and it's also crucial that the support team can associate tickets raised by customers to various issues/bugs being worked on by the product team.
• Our marketing and sales team need the ability to send SMS/WhatsApp messages directly from the CRM to an individual.
• Our marketing and sales team need visibility of important account information directly on the contact record in the CRM.

Regardless of the scenario it can be summarized by saying that there is a requirement for Hubspot users to have visibility of data from another system within the HubSpot CRM on a Contact, Company, Deal or Ticket record whilst also having the ability to interact with said system as required.

I posted an article a few weeks back that discusses "How Marketing and Sales teams can Supercharge the HubSpot CRM" and it referenced what is known as the CRM Cards API. It can help to solve for all of the scenarios outlined above and and what's even better is that it's free to use for all HubSpot customers!

It's important to note that the Cards API does require development resources to implement but once done it can really help to maximise your teams efficiency and ensure that they are getting the most out of Hubspot.

Upon mentioning the CRM Cards API it's always followed by 3 of the same questions and in this article I want to touch on those in more detail. They are:

1. What is it?
2. Do you have any examples?
3. How do we implement it?

So if you're an existing HubSpot customer who wants to learn a little bit more about how this can help you or are planning an integration in the future my hope is that the content of this article will shed some light on the best route forward.

1) What is it?

The CRM Cards API allows you to create your own custom cards on Contact, Company, Deal and/or Ticket records within Hubspot. These cards are automatically loaded from the right sidebar when you access a record in the CRM and will surface information from an external source/system. It also allows you to interact with that external source/system without ever leaving HubSpot.

You'll notice in the example to the right that the card is pulling in lots of information and displaying it to the Hubspot user, this is all loaded from an external system.

Each item/object within the card can have their own set of properties and actions. Actions could involve making requests to other systems or opening a modal/window within Hubspot to give your users the ability to interact with the external system.

The major benefit is that a HubSpot user can very quickly and easily look at data relating to the record they are viewing within the CRM and action as needed.

In the next section I want to look at some specific examples of the Cards API in the wild!

2) Do you have any examples?

Yes, the CRM Cards API is already in use by lots of integrations listed on the HubSpot app marketplace. The functionality depends on the type of integration. Some examples include:

• Jira: A card is added to a ticket record that will allow you to associate tickets with new and existing Jira Issues. You can also view information relating to these issues directly from the HubSpot CRM. This ensures that your support team has a means of communicating with your engineering team and can also easily see the status of issues from HubSpot.
• PandaDoc: A card is added to Contact, Company and Deal records within the Hubspot CRM. You are then able to create documents without ever leaving HubSpot. You're also able to personalize these documents with information contained in the CRM to create truly tailored documents. This allows your sales (and services) teams to continue working within HubSpot and create documents as needed using the data in the HubSpot CRM.
• SakariSMS: A card is included on the contact record that allows you to create and view SMS messages that have been sent from Sakari SMS. HubSpot users can quickly and easily send SMS messages to the contact they're viewing without having to leave HubSpot.
• OrgChartHub: A card is added to Contact and Company records in the HubSpot CRM. It allows you to create, view and manage account hierarchies without ever leaving HubSpot. This is a particularly useful integration for companies focusing on ABM (Account Based Marketing).

There is a lot more apps on the marketplace using the CRM Cards API. I hope that the examples above help to give you a flavor of what is possible as this API can be used for your own bespoke requirements.

Below is an example of a CRM Card I created that loads anytime I open a contact record in my Hubspot portal:

So now that we know what the CRM Cards API is and what it looks like let's look at how you can implement it...

3) How do we implement it?

The first thing you'll need is to create what is known as a "Developer portal". These portals are special accounts that allow developers to register their applications, configure the settings needed for oAuth and test as needed.

Once you've registered your application you can manage the CRM cards. You can have up to 25 CRM cards per application. You'll notice within your application settings there is an option for "CRM Cards". From within here you can then click to create a new "CRM Card". Upon doing so you will see something like below:

Lets break the above interface down in more detail...

3.1) Data Request

There are a couple of important things to be aware of in the above interface. Firstly you'll notice you need to provide a "Data fetch URL". This is the URL that HubSpot will make a request to as soon as a CRM record is loaded. It's effectively a webhook. You will also be required to select at least one record you want the card to appear on. This is done by enabling the "Appear on this type?" toggle. There is also the option to allocate what "properties sent from Hubspot" when the record is loaded. This is useful if you want to send the email of a contact to the "Data fetch URL" which you might use to look up data in the external system.

With the above setup anytime a Contact record is loaded in the installed portal a GET request is made to the URL provided along with a number of properties included as query string parameters by default. They are:

• associatedObjectID = The ID of the Object being loaded in the CRM
• associatedObjectType = The type of Object being loaded in the CRM
• portalID = the ID of the portal 
• userEmail = The user accessing the record
• userID = The user id accessing the record

It will also include any additional properties we specified from the "properties sent from hubspot" section. In this case "firstname", "email" and "lastname". The actual request would look something like this:

https://webhook.site/2bc84ba9-73b0-4500-bc18-76293942efe5?associatedObjectId=19751&associatedObjectType=CONTACT&email=contactb%40demospot.org&firstname=Contact&lastname=B&portalId=7248615&userEmail=jackcoldrick%40hubspot.com&userId=3975103

The idea is that the application can then process this information, query an external source and return a JSON response object which contains the objects to display along with the various actions relating to each.

3.2) Card Properties

Every item loaded into the CRM card is going to have properties associated with it that will provide the HubSpot user more specifics as to what they're looking at. For instance with the Hubspot native JIRA integration it returns properties relating to specific issues (Priority, Assignee etc) linked to the ticket loaded in the CRM.

The properties returned by the card are managed from within the application. It looks something like this:

3.3) Custom Actions

When actions are defined for a CRM card, they must make a call an endpoint. There isn't much more to this from a configuration standpoint. You're effectively whitelisting endpoints that your card will need to make requests to. This could be something like "Adding an invoice", "Creating a ticket", "Sending an SMS" etc...

Thats all from me...

That about wraps up the CRM Cards API and I hope that you have a clearer idea of how it can help you get the most out of your HubSpot portal. Thank you as always for taking the time to read and if you've any questions or thoughts on any of the above please leave a comment below!