CRM cards

Data fetch requests

As mentioned in the overview tab, HubSpot makes a data fetch request to your app whenever a user views the associated CRM record. These requests are sent to the card’s specified fetch/targetUrl with a payload providing details for the associated CRM record.

Responses can contain up to five card properties. If more card properties are available for a specific CRM object, your app can link to them.

Note that the request will timeout in 5 seconds. Within that, a connection must be made with 3 seconds. 

Example data fetch request:

GET: https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

With a header:

X-HubSpot-Signature: <some base64 string>

The X-HubSpot-Signature header provides verification that a request came from HubSpot. See request signatures for details.

Query parameters:

• userId: The numeric user ID of the customer requesting data.
• userEmail: The HubSpot address of the user requesting data.
• portalId: The HubSpot account ID of the customer requesting data. Account and Portal is used interchangeably. 
• associatedObjectId: The ID for the current object, depending on the associatedObjectType. This will be the companyId, dealId, contact vID, or objectId for tickets.
• associatedObjectType: The object type the user is requesting data about (contact, company, deal, or ticket). This will be one of the associatedHubSpotObjectTypes provided for this record type.
• And values for any of the requested associatedHubSpotObjectTypeProperties. If one of the request properties isn't defined for the current object, it won't be listed in the query string. In the example above, the company property domain is included. Request properties can be defined in the app settings UI, as you can see in the screenshot below: 

Example response:

Definitions:

• results: A list of up to five valid card properties. 
• results[].objectId: A unique ID for this object. This property is required.
• results[].title: The title of this object. This property is required.
• results[].link: The URI the user can follow to get more details about this object. This property is optional, but if all objects don’t have a link, you should provide a value of null.
• results[].properties: A list of custom properties that aren’t defined in the card settings. You can use this list to display a specific object's unique properties. These properties will be shown in the order they're provided, but after the properties defined in the card settings. This property is optional.
• results[].actions: A list of available actions a user can take on this object. See action types for details on specifying actions. This property is optional.
• totalCount: The total number of card properties available, if there are more than five related to the requested CRM object. This property is optional.
• allItemsLink: A URI showing all card properties associated with the requested CRM object, if there are more than five. This property is optional.
• itemLabel: The label to be used in the "See more" link, e.g. "See more tickets". This property is optional, and if it's not provided, it defaults to the card title.
• settingsAction: An iframe action giving users the ability to update the app's settings. See action types for details on specifying actions. This property is optional.
• primaryAction: The primary action for a record type, typically a "creation" action. See action types for details on specifying actions. This property is optional.
• secondaryActions: A list of actions displayed on the card level. See action types for details on specifying actions. This property is optional.

In addition to the above properties, the integrator can provide values for the properties defined in the card settings. In the above example, the created JSON property:

"created":"2016-08-04"

Is providing a value for this object for the pre-defined created property.

Handling action hooks 

When a user clicks on an action defined as an action hook, HubSpot sends a request using the URI and HTTP method specified in the action definition.

Example request:

DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com

With a header:

X-HubSpot-Signature: <some base64 string>

Query parameters:

• userId: The numeric user ID of the customer requesting data.
• userEmail: The HubSpot user address of the customer requesting data.
• associatedObjectId: The ID for the current object, depending on the associatedObjectType. This will be the companyId, dealId, contact vid, or objectId for tickets.
• associatedObjectType: The type of object the user is requesting data about (contact, company, deal, or ticket).
• portalId: The account ID (also called Hub ID) of the customer requesting data.
• And values for any of the requested associatedObjectProperties. If one of the requested properties is undefined for the current object, it will not be listed in the query string. In the above example, the company property domain is included.

The X-HubSpot-Signature header allows the integrator to verify that a request came from HubSpot. See request signatures for details.

Example response:

{"message": "Successfully deleted object"}

HubSpot will attempt to parse responses to action hooks as JSON and look for a message property. The user will get a message on either success or failure.

Response status code of 2XX will show a success message and 4XX or 5XX will show error messages.

Action types

The following sections provide details about each type of action that can be specified.

Iframe actions

When a user clicks an iframe action, a modal dialog with an iframe pointing at the provided URL will open.

Example iframe action:

Definitions:

• type: Should be IFRAME to indicate that this is an iframe action.
• width, height: The desired iframe dimensions.
• uri: The URI opened in the iframe.
• label: The label displayed in the action dropdown.
• associatedObjectProperties: A list of properties on the associated contact, company, deal, or ticket. The property values for the current object will be appended to the URI as query parameters when opening the iframe.

Signaling for the modal to close

When the user completes an iframe action, the modal dialog should close and return the user to the original CRM screen. To close the dialog model, the app can use a window.postMessage. The following messages are accepted:

• {"action": "DONE"} - The user has successfully completed the action.
• {"action": "CANCEL"} - The user has canceled the action.

Example: window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

Note: iframe modals accessed through an iframe action will have a responsive width. 

Action hook actions

Action hook actions send a server-side request to an app. The only UI a user sees for this action is a success or error message. This type of action is useful for simple operations that don’t require further user input.

Example action hook action:

Definitions:

• type: Should be ACTION_HOOK to indicate that this is an action hook action.
• httpMethod: The HTTP method to use when making the request. This can be GET, POST, PUT, DELETE, or PATCH.
• uri: The URI of the request to make.
• label: The label to display in the action dropdown.
• associatedObjectProperties: A list of properties on the associated contact, company, deal, or ticket. If httpMethod is GET or DELETE, these property values will be appended to the URI of the request as query parameters. Otherwise, they’ll be sent as request body parameters.

See Handling action hooks for more details on how to implement the action endpoint.

Confirmation actions

Confirmation actions behave the same as action hooks, except a confirmation dialog is shown to the user before running the server-side request.

Definitions:

• type: Should be ACTION_HOOK to indicate that this is an action hook action.
• httpMethod: The HTTP method to use when making the request. This can be GET, POST, PUT, DELETE, or PATCH.
• uri: The URI of the request to make.
• label: The label to display in the action dropdown.
• associatedObjectProperties: A list of properties on the associated contact, company, deal, or ticket. If httpMethod is GET or DELETE, these property values will be appended to the URI of the request as query parameters. Otherwise, they’ll be sent as request body parameters.

See Handling action hooks for more details on how to implement the action endpoint.

Confirmation actions

Confirmation actions behave the same as action hooks, except a confirmation dialog is shown to the user before running the server-side request.

Definitions:

• type: Should be CONFIRMATION_ACTION_HOOK to indicate that this is a confirmation action hook action.
• httpMethod: The HTTP method to use when making the request. This can be GET, POST, PUT, DELETE, or PATCH.
• uri: The URI of the request to make.
• label: The label to display in the action dropdown.
• associatedObjectProperties: A list of properties on the associated contact, company, deal, or ticket. If httpMethod is GET or DELETE, these property values will be appended to the URI of the request as query parameters. Otherwise, they’ll be sent as request body parameters.
• confirmationMessage: The message to display to the user in the confirmation dialog.
• confirmButtonText: The text for the "OK" button. This is optional, as the button text will default to "OK".
• cancelButtonText: Text for the "Cancel" button. This is optional, as the button text will default to "Cancel."

See Handling action hooks for more details on how to implement the action endpoint.