Using HTTP Raw - Setting Up an Integration to HubSpot

Relevant to: Demand Acceleration Platform

When posting leads out to HubSpot using HTTP Raw, the integration connects with the HubSpot API Create or Update a Contact endpoint.

This article provides the steps to gather the required information from HubSpot in order to use the API and how to set up a new integration on a Campaign/Source in the Demand Acceleration Platform.

Gather required information from HubSpot

Retrieve the following data points from HubSpot.

API Key

1. In HubSpot, go to Settings > Integrations > API Key. Click Copy.

Property API Names

1. In HubSpot, go to Settings > Properties. Click on each of the properties that will be mapped within the Demand Acceleration Platform.

2. From the Edit property modal, make a note of the following for each property:

• Internal name - Special characters should not be included (select the toggle to view the Internal name).
• Field type - Eg. string, currency, date, integer, phone, Boolean
• Picklist internal values (if applicable) - Common for fields like state, country, industry, etc.
• Field length restrictions - Min/max number of characters
• Field requirement - Whether field is required or optional, plus any other validation requirements.

3. For properties that are a Dropdown select field type, make a note of all the Internal Values (not the Label).

Adding a HTTP Raw Integration to a Campaign/Source

1. In the Demand Acceleration Platform, go to your Campaign/Source and navigate to the Integrations tab. Click the Add Integration button.

• If you can see an My HTTP tile here, the integration has already been added to the Campaign/Source. Proceed to Configure your HTTP Raw integration.

2. You will be presented with the Add Integration modal. 

Here there are two options:

• Option 1: Create a new Campaign/Source integration – Start from scratch! This will essentially create a default integration with the fields you created on the Fields tab of the Campaign or Source and their corresponding tokens will auto-populate in string format. You will need to review and manually adjust the field names and values within the Body according to your system needs. 
  • This option is most helpful when:
    • You or your team are new to the Demand Acceleration Platform.
    • You haven’t built any Campaign/Sources with a similar set up.
    • You are using very few fields or unique fields within this Source (eg. in Social or Webinar Sources, which have fewer, more specific fields).

• Option 2: Load From Existing – Start from something similar! This will make an exact copy of an existing integration from another Campaign/Source. Once loaded, changes can be made for the new Source.
  • This option is most helpful when:
    • You already have an existing integration that used similar fields and set up details (eg. existing builds from the same team, region, program).
    • You are creating multiple Sources that use the same Social or Webinar form fields.
    • You have complex routing rules that you would like to copy and manually check the Source fields and details match.

Decide which option works best for your build; instructions for both are outlined below.

Option 1: Create a new Campaign/Source integration

1. In the Add Integration pop-up modal, select My HTTP from the list.

This is now listed as an integration with a visible tile. Proceed to Configure your HTTP Raw integration.

Option 2: Load From Existing

1. In the Add Integration pop-up modal, select the Load From Existing button.

2. You will then be presented with a list of the existing Campaign template integrations to choose from. If you wish to switch to view your Source Integrations, use the Showing Campaigns button and select Source from the drop-down.

3. Click the desired Campaign/Source integration and select the integration from the dropdown in the Integration Name column. Then click the Load Integration button.

This will load a copy of your existing integration to the new Campaign/Source, which you can adjust accordingly.

Proceed to the Configuring Your HTTP Raw Integration section below for more details.

Configuring Your HTTP Raw Integration

Once an integration has been added to your Campaign/Source, you need to configure some key elements to define how lead data is sent to your Marketing Automation or CRM system.

1. To open your integration, hover over the integration tile and click the Settings icon.

2. Move through the sections below to configure your integration according to the needs of your Campaign/Source.

https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/
leadEmail/?hapikey=yourHubspotApiKey

URL

The integration uses the Create or Update endpoint of the Hubspot Contacts API with a predefined URL that needs to be personalized for your system. The base URL (as per the HubSpot Contacts API documentation) is as follows, with the values in bold indicating where you need to add your credentials.

https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/
leadEmail/?hapikey=yourHubspotApiKey

In order to personalize the URL:

1. In the Available Tokens panel, select Campaign/Source Fields.

2. Copy the token value for the Email field. 

3. Paste the token in the email value (in bold):

https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/
{{lead.Email}}/?hapikey=yourHubspotApiKey

This will ensure HubSpot can identify the email of the contact that the POST request is trying to create or update in the database.

4. Add your HubSpot API key to the apikey value (in bold):

https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/
{{lead.Email}}/?hapikey=123a456b-7890-1cd2-e3fg-4567h8901i

Body

The request body is written in json and follows the format below. The body property values (in bold) need to be replaced with a token for the associated field in your Campaign/Source. Using tokens here will ensure the dynamic field values are sent with the lead when posted to HubSpot.

{
"properties": [
{
  "property" : "firstname",
  "value" : "John"
},
{
  "property" : "lastname",
  "value" : "Smith"
},
….
]
}

1. From the Available Tokens panel, copy the relevant Campaign/Source field tokens.

2. In the body, paste the token values in place of the values (in bold) for each property, formatted like:

{
"properties": [
{
  "property" : "firstname",
  "value" : "{{lead.FName}}"
},
{
  "property" : "lastname",
  "value" : "{{lead.LName}}"
},
….
]
}

The final request body should look something like this:

Testing the integration

It is important to test your integration before you start collecting leads. It is advisable to work closely with your Marketing Ops team to confirm that all test data has been properly posted into HubSpot.

For instructions on testing your integration, see Using HTTP Raw - Testing a HubSpot Integration.

Recommended Reading

• Integrations Tab
• Fields Tab
• Using HTTP Raw - Testing a HubSpot Integration
• HubSpot Post Out Methods
• Using HTTP Raw

For more help, get in touch with our Support Team or your Customer Success Manager.

Connecting to HubSpot Template