External API

This document explains the simplified ways to configure External APIs and create engagement.

External API facilitates you to connect with multiple third-party APIs allowing you to integrate with any third-party service like a CRM, IVR, Private ESP/SSP etc. to automate your engagements.

Use cases for External API

1. CRM: Integrate with CRM like Hubspot, Vymo, etc.

2. IVR: Integrate IVR services to automate communication for immediate responses

3. Private ESP/SSP: Integrate your own email or SMS service providers to create engagement to ensure the confidentiality and privacy of your PII data through data encryption.

4. Email Service Provider (ESP): Integrate with email service providers like mailmodo, etc.

5. Facebook Conversion API/ Google Conversion API: Integrate Facebook and Google conversion API to send conversion data from CDP to Google and Facebook

6. Internal system API: Pass data from the CDP to internal APIs in services like Banking financial services and insurance which will have confidential APIs used internally for their service operations.

7. Lead submission API: Submit the data captured from WhatsApp or any other lead forms into your lead management system

Prerequisite

API Docs / API reference docs

Valid authorisation 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

The API URL and the payload can be fetched from the API provider.

Steps to Configure an External API

Go to > Campaigns > Channels > External API

Step 1: Click the +Add New External API Button

Step 2: Add Basic Details

• Name: Name your External API. This name cannot be editable once it is saved.

• Description: Enter the description of your API.

• Channel: Choose the channel in which you want the API to communicate with your audience. Lemnisk provides Email and SMS channels for the API to communicate.

The performance data of these Emails and SMS will be available in the Reports and Journey builder as usual basis the channel that you select.

Step 3: Add External API Details

HTTP Method: Select the necessary HTTP method from the dropdown. Supported methods: GET, POST, PATCH, PUT, and DELETE.

URL: Add the endpoint URL of your API and enter the variable for path parameters (if any).

URL Path parameters are variable parts of a URL path that are used to point to a specific resource within a collection

Adding dynamic path parameters in the URL:

If you have a path parameter that will change each time you trigger an engagement, you can configure it dynamically by defining the variable in {{variable}}. Here's an example to do it:

Image: Dynamic Path Parameters

This URL is custom-made for demonstration purposes

{{Campaign_ID}} is the URL path parameter we declared above and added a default value.

The parameters we add to this variable will be reflected while adding the engagement which can be changed later.

Image: Default value reflected while creating engagement

Headers: Add Headers to provide the metadata about the request.

Common headers that are used while making requests:

• Accept

• Content-Type

• Content-length

• Authorization ( use the necessary authorization keys which may vary according to the APIs)

• User-Agent

• Cache-Control

• Connection

Query Parameter:

Query parameters are the key-value pairs provided at the end of the URL which gives additional information to the webserver while making the request.

Payload: Paste the payload in the black code edit screen as shown below. You can set the payload to None if the API doesn't have any request body. GET requests will not have any payload however POST APIs may have the payload associated with the API.

Sample Payload:

{
    "details": {
        "data": {
            "param1": "Sample value", 
            "param2": "Sample value"
        }
    },
    "token": "abc"
}

You can set the payload at 2 levels.

Global Level: In the Global Level, you define the payload for the API. To define the payload, just enter the JSON payload in the code block. Please ensure that it should be a valid JSON. For invalid JSON, an error will be shown in the UI. If the given payload is correct, it will deploy a tree view. you can add static or dynamic fields, create variables and add the display term flexibly using the tree formation that enables you to assign values to the parameters based on parent and child objects.

The payload you entered will be displayed in the following tree view.

( This payload is custom-made for demonstration purposes)

Image: Object Tree

{
    "details": {
        "data": {
            "param1": "Sample value", // You can configure these key value parameters by giving name and value which will be displayed in engagement level 
            "param2": "Sample value"
        }
    },
    "token": "abc"
}

• To Configure the parameters in engagement level, pass the variable between double curly braces i.e., {{variable_name}}.

• Enter the display name which will be shown on the UI as the variable alias, when you're creating engagements for the configured API.

• Enter the default value that assigns value to the parameter by default 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.

Image : Setting the values of the parameter

Optional Field:

• If you wish the field to be mandatory, select No.

• Select Yes, if the field needs to be optional. In such a case, you have to define how to handle the payload when that particular key (param1 in the example) is not provided with a value.

Image: Setting conditions for the empty fields

Option 1: Send Empty Value (do nothing)

The parameters will be empty, and the default value will be shown here in all the engagements.

The payload will be:

{
    "details": {
        "data": {
            "param1": " ",
            "param2": "Sample Value 2"
        }
    },
    "token": "abc123"
}

Option 2: Drop details.data (Parent Node)

On Choosing drop details. data, the parent node (Data) will be dropped. The grandparent node (details) and ( Token) will be considered as objects.

The payload will be:

{
    "details": {},
    "token": "abc123"
}

Option 3: Drop details (Grandparent Node)

On Choosing drop details, the grandparent parent node (Data) will be dropped along with its child ( Data). Only (Token) will be considered as objects.

{
    "token": "abc123"
}

Option 4: Drop the whole Object

On choosing to drop the whole object, the entire payload will be dropped and the API won't get triggered.

Engagement Level:

The engagement level payload feature allows users to set a specific payload while creating an engagement instead of defining it at the global level. This flexibility is particularly beneficial when running campaigns with varying payload requirements. By utilizing the engagement level payload, users gain the liberty to send any customized payload when setting up engagements. This feature proves to be highly useful when integrating with external platforms like Mailmodo, where the payload may need to change from one campaign to another. Please note that at this time, our platform exclusively supports JSON payload at the engagement level.

Demo : Creating Engagement