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.
HTTP Raw is ideal for more complex and/or custom post outs to HubSpot. |
In this article
Gather required information from HubSpot
Retrieve the following data points from HubSpot.
Data to collect from HubSpot |
Where to find the data | |
API Key |
In HubSpot: Settings > Integrations > API Key. |
|
Properties
|
In HubSpot: go to Settings > Properties. See section for detailed instructions.
|
Use the Connecting to HubSpot Template at the end of this article to help capture your details. |
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).
- This option is most helpful when:
- 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.
- This option is most helpful when:
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.
Field |
Recommendation | |
Profile Name |
Enter a name for your integration.
|
|
Method
|
Select POST. |
|
URL |
The URL will be formatted as below and you need to replace the bold values with your credentials. See section for detailed instructions. https://api.hubapi.com/contacts/v1/contact/createOrUpdate/email/ |
|
Headers |
Enter the following Headers:
|
|
Body |
Configure the body of the POST request that will be sent via the Hubspot Contacts API to create or update a lead in the database. The HubSpot API expects the body to be in JSON format with a specific way of defining fields and values. See section for detailed instructions. |
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.
The HubSpot integration has been added to your Campaign/Source. |
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.