# 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](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

{% hint style="info" %}
You can get this API URL and payload for your API from the Hubspot team once you create your account.
{% endhint %}

## Configuring Hubspot - Create Contacts API

Go to > Campaigns > Channels > External API

**Step 1:** Click the **+Add New External API** Button

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FduiTHupw7pw1S0kFoSCZ%2Fimage.png?alt=media&#x26;token=2abe8c86-c356-4694-a447-22dd9e0eb5fe" alt=""><figcaption><p><em>Image: Add New External API</em></p></figcaption></figure>

**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](https://api.hubspot.com/crm/v3/objects/contacts)  ( API URL from the API reference doc)

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FLefcmYiErsebpkhivUEp%2Fimage.png?alt=media&#x26;token=ddb77acb-1b47-46e0-84a0-66cc99e37417" alt=""><figcaption><p><em>Image: API URL</em></p></figcaption></figure>

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.

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2F1nVETZafLKe0tNOcH7Qe%2Fimage.png?alt=media&#x26;token=8f85b3de-eb5d-4ee8-8489-48781df1e540" alt=""><figcaption><p><em>Image: Headers</em> </p></figcaption></figure>

**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)

```json
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "(555) 555-5555",
    "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)

```json
{
  "properties": {
    "email": "example@hubspot.com",
    "firstname": "Jane",
    "lastname": "Doe",
    "phone": "(555) 555-5555",
    "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
        } ]
}]
}
```

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FyCgOqD4u8S3dwOhpyb05%2FPayload.png?alt=media&#x26;token=dee2a64c-eac1-43fe-ad34-1d734fd6ea38" alt=""><figcaption><p><em>Image: Payload</em> </p></figcaption></figure>

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.](../..#optional-field)

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FbqkmAgA3938zGFvlkYzw%2Fezgif.com-gif-maker%20(1).gif?alt=media&#x26;token=f3d123d7-478c-4255-be1f-973e2dbb1fb1" alt=""><figcaption><p><em>Gif: Configuring Payload Values</em> </p></figcaption></figure>

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

{% embed url="https://drive.google.com/file/d/1go-qcnxUQClPBJpOH8c1UO4uApHSuC1a/view?usp=sharing" %}
_Demo: Configuring Hubspot's CreateContact API_
{% endembed %}

## Create engagement in Hubspot Create Contacts API

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2Fp4VLjCqtctxY0e0QJymW%2Fimage.png?alt=media&#x26;token=d764832d-cbae-4c8e-840a-5977a224c68f" alt=""><figcaption><p><em>Image: Create Engagement</em></p></figcaption></figure>

**Step 1: Create an Engagement**

{% tabs %}
{% tab title="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&#x20;
{% endtab %}

{% tab title="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
{% endtab %}
{% endtabs %}

**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&#x20;
* **Label (mandatory):** Choose a product label from the list. Click [here](../../../getting-started#product-label) 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.

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FkRI0OcwBAaffhpJkxXU4%2Fimage.png?alt=media&#x26;token=ad27b8a6-3d9a-4ea5-8a9c-89afc4b16430" alt=""><figcaption><p><em>Image: Configuring Parameters</em> </p></figcaption></figure>

**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"

{% embed url="https://drive.google.com/file/d/1D4_jeP5EDpRX5pGo0ZLmXU2ZlQGJRjdb/view?usp=sharing" %}
Demo: Creating Engagement
{% endembed %}
