Use case 1: HubSpot - Create Contacts API

Businesses use Hubspot CRM for sales and marketing for optimal customer engagement. Hubspot offers an array of APIs that sync data between platforms to engage customers with the relevant data.

In this use case, we will go through the implementation of passing contacts to HubSpot's Create contact API by configuring Lemnisk's external API at the global level and creating engagement. we configure this API in the global level payload as the payload value will be the same in all the engagements.

Prerequisites:

API Docs / Reference doc: https://developers.hubspot.com/docs/api/crm/contacts#endpoint?spec=POST-/crm/v3/objects/contacts

Valid Authorization scheme and keys: Depending on your free/paid account with your external system, OR your internal tech implementation of the API, you should have the relevant authorisation mechanism and its keys/passwords/tokens handy. Your POC from the external vendor or your tech team shall help you with the same

You can get this API URL and payload for your API from the Hubspot team once you create your account.

Configuring Hubspot - Create Contacts API

Go to > Campaigns > Channels > External API

Step 1: Click the +Add New External API Button

Image: Add New External API

Step 2: Add Basic Details

• Name: Naming the configuration as Hubspot_CreateContacts

• Description: Enter the description of your API.

• Channel: Choose the channel you want the API to communicate with your audience. Here we choose Email as our preferred channel.

Step 3: Add External API Details

HTTP Method: Here we select POST as the HTTP Method as the API is a post request to add contacts emails in the Hubspot database.

URL: Paste the following API URL https://api.hubspot.com/crm/v3/objects/contacts ( API URL from the API reference doc)

Image: API URL

You can add parameters by creating variables at the end of the URL and declaring value inside {{value}} double curly braces. Since the Hubspot API does not contain any additional parameters, the window to configure the parameter will not appear.

Headers: Add Headers to provide the metadata about the request. Here we add the authorization and API key in the headers to authenticate the API. The API key will be provided by the Hubspot team.

Image: Headers

Payload: Paste the payload in the black code edit screen as shown below. Here we set the payload at the global level as the API contains the value which remains the same for all the engagements.

(Payload from the API reference doc)

{
  "properties": {
    "email": "[e-mail]",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "[phone]",
    "company": "HubSpot",
    "website": "hubspot.com",
    "lifecyclestage": "marketingqualifiedlead"
  },
"associations": [
    {
     "to": {
        "id": 123456
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 279
        } ]
    }, 
    {
     "to": {
        "id": 556677
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 197
        } ]
}]
}

( Payload from the API reference doc)

{
  "properties": {
    "email": "[e-mail]",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "[phone]",
    "company": "HubSpot",
    "website": "hubspot.com",
    "lifecyclestage": "marketingqualifiedlead"
  },
"associations": [
    {
     "to": {
        "id": 123456
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 279
        } ]
    }, 
    {
     "to": {
        "id": 556677
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 197
        } ]
}]
}

Image: Payload

You can configure the values in the payload load by clicking on the payload value and by assigning values and adding display names in the given fields as shown below. The display name will be shown on the UI as the variable alias when you're creating engagements for the configured API.

Default Value: The default value you provide here will be assigned to the parameter if the value is not provided by the user, or in the case of Macro when the system fails to replace it with a value.

Optional Field: You can set the field to be optional or to be mandatory by using the optional field and by assigning a condition to the optional field. Here we set the field as mandatory. To know more about optional and its conditions click here.

Gif: Configuring Payload Values

Step 5: Once all the fields are configured, click Save Details.

Demo: Configuring Hubspot's CreateContact API

Create engagement in Hubspot Create Contacts API

Image: Create Engagement

Step 1: Create an Engagement

Method 1 - Segment

• Go to Campaigns > Segments

• Select the Segment Name

• Click on External API on the left panel

• Click on the +Add Engagement Button

Method 2 - Channel

• Go to Campaigns > Channels

• Click on External API on the left panel

• Click on Add Engagement

• Select Segment Name from the list

• Click on Confirm And Proceed To the Next Step

Step 2: Add General details

• Engagement Name (mandatory): Enter a name for the Engagement. It should range between 6-25 characters.

• API(mandatory): Choose your API as Hubspot Create Contact

• Label (mandatory): Choose a product label from the list. Click here to learn more about Product Label.

Step 3: Add a Goal Goal Type: Choose a goal type from the list. You can set it to none if the goal is not decided yet.

Step 4: Configure Parameters

URL path parameters: This will be updated automatically based on the URL you configured while adding the external API. The parameters will be displayed here as you configured in the payload at a global level.

Image: Configuring Parameters

Step 5: Schedule Settings You can schedule an engagement to trigger immediately or to send later by configuring the Time and Date. Here we have selected the schedule as immediate.

Step 6: Click "Save"

Demo: Creating Engagement