Integrate Your Custom Data Source with LeadSquared

1. Feature Overview

In addition to the default lead capture connectors (99acres, Zendesk Chat, Google Forms, Zoom Webinars, etc.) listed on your account, you can also build your own custom connectors to capture leads and activities from other data sources (e.g., HubSpot, Zohodesk, etc.). You can use the custom connector to make inbound and outbound calls. Once the leads are synced, you can leverage LeadSquared’s CRM features to nurture and convert your leads.

2. Prerequisites

• You must be the Administrator of your LeadSquared account.
• You must install and configure the Lead Capture Connector (also called the Universal Lead Capture Connector, ULC). This is a paid feature. To enable it on your account, contact your account manager, or write to support@leadsquared.com.
• You must have developer experience. The custom connector requires API integration.
• API to facilitate periodic lead sync from the third-party application to LeadSquared. The API must allow leads to be fetched by date range. The API must satisfy the following conditions –
  • Only REST APIs are supported.
  • Only GET and POST methods are supported.
  • The API must return data in JSON format.
  • The connector also allows you to configure a transformation API to normalize the data (convert it to a flat JSON format).
  • Authentication must be passed through the API (using the header or query string). Complex authentication methods such as OAuth are not supported.

3. How it Works

Real-time Sync connector

First, build, configure and test your custom data connector. To do this –

• Configure the webhook format, configure the authentication variables (which is optional) and map the API response data to the corresponding lead, activity or any other LeadSquared entity. To map the API response data to other LeadSquared entities (such as task fields, opportunity fields, etc.), enable Call Custom Actions, and use a relevant LeadSquared API to build and configure the custom action.
• Once you map the connector fields in LeadSquared, a webhook URL is generated.
• Configure this URL in your data provider’s account. To do this, you can either –
  • Copy this webhook and manually configure it in your data provider’s account.
  • Automatically pass the webhook from your LeadSquared account to your data provider’s account. To do this, you must develop a webpage that’ll perform this action, and configure this webpage inside the connector.

Periodic Sync

Create, configure and test your Sync API to capture leads and activities from your custom data source to LeadSquared.

• In this step, configure the authentication variables, map the API response data to the corresponding lead, activity or any other LeadSquared entities, define the accepted formats for date/time data, and determine the sync frequency.
• Then map the API response data to the corresponding lead, activity and other entity fields in LeadSquared.

In the steps below, we’ve configured the connector using the following example API, where leads will be fetched when the created-on date is after the start time of the sync operation…is the API fine? –

GET https://{{BaseURL}}/api/v2/users/search?query=created>{{START_DATE_TIME}}+role:end-user

4. Install the Connector

To install the Universal Lead Capture app –

1. From the main menu, navigate to Apps>Apps Marketplace,
2. Search for Universal Lead Capture, and click Install.
   • Alternatively, you’ll find the app listed under the Lead Capture tab.
3. Once the connector is installed, hover your cursor over , and click Configure.
4. On the Configure Universal Lead Capture pop-up, from the Select Role dropdown, choose the user roles for which you want to give connector configuration and actions permission.
   • If you choose to not give permissions to other user roles, then skip this step, and directly click Save.
5. Once you’re done, click Save. The connector is successfully installed.

No further configuration is required. To access and configure each individual connector, navigate to Apps>Universal Lead Capture.

5. Configure Custom Lead Providers

Once the Lead Capture connector is installed, create and configure your custom data source.

1. On your LeadSquared account, navigate to Apps>Lead Capture.
2. Click Add Data Source, and on the Enter Basic Information pop-up, enter –
   • Data Source Name – The name of the data source from where leads will be pulled.
   • Help – The help article URL that covers installation and configuration.
   • Description – A short description of the connector instance.
   • Logo – You can either drag and drop the data source logo, or you can use the Choose File button.
3. Once you’re done, click Save & Next.

6. Set-up – Real Time Sync

On the Lead Capture screen, from the Real Time Sync tab, to begin the set-up process, click Click to Enable and Configure.

6.1 Webhook Format

Enter the following webhook details –

Once you’re done, click Save & Next.

6.2 Authentication Variables

Depending on the data source you’re working with, define your own set of authentication variables (e.g., Base URL, Token, API Keys, etc.).

1. Click the Add New button, and enter the following details –
   • Display Label – The display name of the variable (e.g., Secret Key, Token, etc.).
   • Variable – The variable name that’s passed (e.g., {{secretKey}}, {{token}}, etc.). This variable should be written inside curly brackets “{{example}}”.
   • Value – The value of the variable that’s passed. Based on your requirement, you can choose to –
     • Ask From User – This will require the user to input the value.
     • Call API/Lapps – The value will be fetched from an API or Lapps. This can be used to fetch the authentication value from a different API. You can do this by calling the API/Lapp in the API Builder pop-up, and map its response as the value.
     • Hidden – Select this option to pass a default value, while keeping it hidden from your users. In the pop-up, enter the default value, and click Save.
   • Type – Select the data type of the variable from the following options –
     • Text
     • Password
     • Boolean
     • Number
2. Once you’re done entering all the details, click to save the variable.
   • To add more variables, click the Add New button.
3. Once you’re done adding variables, click Save & Next.,

6.3 Transformation Logic

If the data received via Sync API is complex in structure and needs to be further transformed into a flat JSON structure, you can configure an External API here to parse the data. To do this, enable , and configure the transformation API. The steps to configure the API are similar to the section below – Define API Schema.

6.4 Entity Options

Here, define the sync behavior of the connector when leads, activities and other entities are captured.

Lead/Contact Entity

Based on the Lead Capture Search By criteria (email Id, phone number, etc.), LeadSquared identifies and captures leads from your data provider. Lead capture is enabled by default, and it cannot be disabled. The following options are available to configure the connector’s Sync Behaviour –

• Capture (Create and Update existing) Record – Leads that only exist in your data provider’s account (but not in your LeadSquared account) will get created in LeadSquared. Leads that exist in both your data provider and LeadSquared accounts will get updated.
• Create only new record – Leads that only exist in your data provider’s account (but not in your LeadSquared account) will get created in LeadSquared.
• Update only existing record – Leads that exist in both your data provider’s account and LeadSquared accounts will get updated in LeadSquared.
• Do Nothing – When a lead is created or updated in your data provider’s account, no action will be performed in your LeadSquared account.

Edit Mapping

Once you configure the Sync Behaviour, you’ll have to ensure the field mapping is accurate. To do this, click Edit Mapping.

On the Default Mapping screen, map the API response to the corresponding LeadSquared lead and activity fields. To help you understand how to map your responses, we’ve listed down a few examples –

i) A straightforward, key-value pair response –

{

"page_name": "Final Lender Landing Page",

"page_id": "Summer-Campaign-1364",

"page_url": "http://aroundtheworldin80ways.com/Ladakh"

}

For such a response, you can map the keys to the corresponding LeadSquared lead fields (e.g., page_id to Related Landing Page ID, etc.).

ii) Nested key-value pairs –

{

"campaign":{

"id":"Zendesk-1364",

"title":"Zendesk_Leads"
},

"lead":{

"Name":"Paul Adams",

"email":"paul@example.com",

"phone":"9999999999"

}

}

Here, there’s a key-value pair (“title”) nested within an object (“campaign”). To map the parameters within the object to the corresponding LeadSquared lead fields, map it as a dot notation response (e.g., campaign.title to Source Campaign, etc.).

iii) A key containing a dotted notation –

{

"page_name":"Visit Ladakh",

"page_id":"Summer-Campaign-1364",

"data.json":{

"email":"paul@example.com",

"mobile_number":"9999999999",

"date_submitted":"2021-04-24"

}

}

Here, the key (“data.json”) that contains different parameters (“email”, mobile”, “date_submitted”), is rendered as a dotted notation. To map this key to the corresponding lead field, map it as follows – data*json.email to Email, data*json.mobile_number to Mobile Number, etc.).

iv) An encoded value –

{

"FirstName":"Paul+MX",

"Phone":"9999999999",

"Source":"Zendesk",

"EmailAddress":"mx%example.com"

}

Here, the response value (“EmailAddress”) is encoded (“mx%example.com”). To get the masked value, decode it when mapping the response (e.g., decode=>EmailAddress).

v) When you only want to capture data from certain fields –

{

"items":[

{
"nickname":"Paul",
"body":"From visitor",
"visitor_nickname":"Paul_1364",
"kind":"MessageToOperator",
"timestamp":"1629476535.249866"
},
{
"nickname":"Jai",
"body":"Hi from agent",
"operatorId":"5763330742157312",
"kind":"MessageToVisitor",
"timestamp":"1629476545.909106"
},
{
"nickname":"Jai",
"body":"how agent can help?",
"operatorId":"5763330742157312",
"kind":"MessageToVisitor",
"timestamp":"1629476556.704914"
}

]

}

To capture certain of the fields of the JSON object (“nickname”, “body”) use the parseTranscript key, followed by the JSON section (items in our case), and then give the fields you want to capture (parseTranscript=>items=>[“nickname”,”body”]).

To map your fields to LeadSquared –

• To provide a default value for any field, click  , enter the value under Default Value, and click .
  • If the data provider doesn’t send data for any lead/activity field, then the default value will get assigned to that specific field. But if the field already has an existing value, then the default value will be ignored.
• To disable lead data capture for any field, disable the slider.
• To mark a unique lead/activity field as the search key, click .
• To create a custom Calendly lead/activity field, click the Add Custom button.
  1. Once this field is created, you must map it to the relevant LeadSquared lead/activity field.
  2. After the field is mapped, to save the custom field, click .
  3. To delete a custom field, click .

Call Custom Actions

If required, you can configure the connector instance to perform other actions such as Create Task, Update Task, Create Opportunity, etc. This can be achieved by adding and configuring the relevant LeadSquared API for the action you want to perform. To configure the action –

1. Alongside Call Custom Actions, enable , and click Add Custom Action.
2. On the Define Param Mapping pop-up, enter the following details –
   • Basic Details – Enter the Name and Description of the action (e.g., Create an Appointment). Once you’re done, click Save & Next.

• • Param Mapping – Here you’ll have to map the API parameters to capture details from your LeadSquared account and from the data provider’s account.  
    

• Click Add Custom, and enter the following details –
  1. API Params – The parameters present in the API you’re passing.
  2. Default Mapping Key – The default value for the corresponding parameter.
  3. Description – The description for the parameter and key you’ve added.
  4. Editable – To allow your users to edit the parameter details, enable . To enhance performance, we recommend that you only edit the Mapping Key, and let all the other details remain as is.
  5. Actions – You can edit or delete an existing parameter.
• In our example, we’ve added all the mandatory parameters listed under the Create an Appointment API.
• The values for the first four parameters your see (“TaskType“, “RelatedEntity“, “Reminder“, “NotifyBy“) are present within LeadSquared. This allows us to hardcode the Default Mapping Key for these values, while giving users the option to edit the details if required (e.g., if they want to change the TaskType, if they want to edit the number of minutes before which they receive a notification, etc.).
• The Default Mapping Key values for the other parameters are dynamic, since the values are being pulled from the data source provider’s account (Calendly in our example). To ensure there’s no format mismatch between LeadSquared and the data provider’s account, we recommend you pass the Default Mapping Key in the LiquidJS format.
• We’ve passed two additional parameters that are not present in the Create an Appointment API – “event” and “eventId“. These are differentiator parameters. These parameters allow us to perform two different actions (e.g. Create and Update/Create and Delete, etc.) using the same API webhook we’re creating.
  • In our example, if we only pass “event“, a new Appointment task will get created. But if we only pass “eventId“, then an existing Appointment task will get updated.
  • If you’re looking to create a single API that allows you to perform two different actions, we recommend that you add similar differentiator parameters.
• To add more parameters, click Add Custom.
• Once you’re done, click Save & Next.
• Once the API is working as expected, click Save & Close.

• • Define API Schema – Add and configure the API through which the custom actions will be performed in LeadSquared.
    • API Configurations – Add and configure the API URL, the Header and the Body.
      1. In the Request URL box, enter the base URL and the other parameters you want to pass in the API.
      2. Click the Add New button to enter the API headers (accessKey, secretKey, etc.).
         • You can configure the content type format from the available options (Form Data, Raw JSON and x-www-form-urlencoded).
         • You can configure the API language from the available options (JSON or XML).
         • Parameters for which the values that are hardcoded are automatically added to the Body.
         • The “orgID” parameter is optional. You can include it in the Body when testing the API, and you can remove it once the API works as expected. The “orgID” is automatically picked up from your account.
      3. Once you’re done, click Save & Go to Test API.
    • Test API – Once the API details are added, pass values to test the API. Once you’ve added the values, click Send Test.
      • If the API works as expected, click Go to Response Mapping.
      • If the API doesn’t work as expected, identify the errors by viewing the logs. Once they’re fixed, click Go to Response Mapping.
    • Response Mapping – To help LeadSquared make sense of the API response, map the response parameters as success, failure or error
      1. Under the Key and Value fields, map relevant key-value responses.
      2. From the Mapping dropdown, select the correct outcome for that particular response.
      3. Under Message, enter the message you want to display in the response.
      4. After mapping a response, click . To map additional responses, click the Add Mapping button.
      5. Once you’re done, click Save & Close. The custom action you’ve configured will now fire as expected.

Activity Entity

Once leads are captured to LeadSquared, you can post custom activities to these leads (e.g., Ticket Creation, Chat Transcript, etc.). These activities will help users keep track of the lead’s journey to conversion. To post activities to the leads captured, alongside Activity Entity, enable the slider. The following options are available to configure the connector’s Sync Behaviour when activities are synced to LeadSquared –

• Capture (Create and Update existing) Record – New activities will get posted to the lead in LeadSquared, while existing activities will get updated.
• Create only new record – Only new activities will get posted to leads in LeadSquared.
• Update only existing record – Only existing activities on the leads captured will get updated in LeadSquared.

The steps to configure mapping is the same as the steps listed above, under Edit Mapping…

In addition to defining the activity entity, you can also create and define the activity schema. This step is optional. If required, you can use existing Custom Activity types when mapping the data source.

To define the activity schema –

1. Against Activity Type(s) Definitions, enable the slider, and click Add Schema.
2. On the Add Custom Activity Type – Define Schema pop-up, on the Schema Details tab, enter the following details –
   • Schema Name – The activity schema name.
   • Description – The activity description.
   • Directions – Inbound or Outbound activity.
   • Delete Activity – To allow your users to delete this activity, enable the checkbox.
   • Track Location – To track the location from where the activity was created, enable the checkbox.
   • Log Activity Changes – To keep a log of all the activity changes, enable the checkbox. To know more, refer to How to Log Activity Updates.
   • Allow pre-dated Activities – To allow your users to post this activity on a past date, enable the checkbox.
   • Show in Activity List – To display the activity on the Manage Activities page, enable the checkbox.
3. On the Param Mapping tab, create and add custom fields to the activity. To know more, refer to How to Add Custom Activity Types.
   • Display Name – The display name of the activity field (e.g., PAN number, etc.).
   • Type – The data type for the field (e.g., Number, Dropdown, etc.).
   • After creating a field, click . To create additional fields, click the Add Field button.
4. Once you’re done, click Save & Close.

Once the connector’s sync behaviour is configured, click Save & Next.

6.5 Configuration Steps

Identify the pages you want to display to your users when they’re configuring the connector. By default, the Basic Settings, Authentication and Entity Options pages are displayed to your users, and you cannot revoke user access to these pages. These are the pages that were configured in the previous steps.

You have the option to allow your users to access or not access the Webhook URL that’s generated for the connector. To revoke access, disable the slider. By revoking access, you can prevent manual errors from occurring when your users copy and paste the URL in your data provider’s account.

Additionally, when you disable access, you have the option to develop and add a webpage in the connector, which automatically configures the webhook URL in your data provider’s account. Once you build this webpage, to include it in your connector and display the page to your users –

1. Alongside Webhook URL, disable the slider.
2. Click Custom, and then click Add New.
3. Enter the following details –
   • Display Label – The display name of the page you’re displaying to your users.
   • Description – A description for the page you’re adding.
   • URL – The URL of the webpage you’ve developed.
   • Enable – To revoke page access to your users, disable the slider.
4. Once you’re done, click .
   • To add additional pages, click Add New, and repeat the steps listed above.

Once you’re done identifying the pages you want to display to your users, click Save & Close. The connector is built, and you’ll now have to configure it.

Note: To know how to configure the connector, we recommend you refer to this article.

7. Set-up Periodic Sync

On the Lead Capture screen, from the Periodic Sync tab, begin the set-up process by clicking the Click to Enable and Configure button.

7.1 Basic Settings

On the Basic Settings screen, enter the following details –

Once you’ve entered the details, click Save & Next.

7.2 Authentication Variables

System Variables

Under the System tab, the following system date/time variables are available by default. Use these variables in your Sync API to pull data for date/time fields.

Custom Variables

Under the Custom tab, Depending on the data source you’re working with, define your own set of authentication variables (e.g., Base URL, Token, API Keys, etc.).

1. Click the Add New button, and enter the following details –
   • Display Label – The display name of the variable (e.g., Secret Key, Token, etc.).
   • Variable – The variable name that’s passed (e.g., secretKey, token, etc.).
   • Value – The value of the variable that’s passed. Based on your requirement, you can choose to –
     • Ask From User – This will require the user to input the value.
     • Call API/Lapps – The value will be fetched from an API or Lapps. This can be used to fetch the authentication value from a different API. You can do this by calling the API/Lapp in the API Builder pop-up, and map its response as the value.
     • Hidden – Select this option to pass a default value, while keeping it hidden from your users. In the pop-up, enter the default value, and click Save.
   • Type – Select the data type of the variable from the following options –
     • Text
     • Password
     • Boolean
     • Number
2. Once you’re done entering all the details, click to save the variable.
3. To add more variables, click the Add New button.
4. Once you’re done adding all the variables, click Save & Next.,

7.3 Sync Start and End Time Settings

Each data provider follows a specific date-time format (Unix TimeStamp Format, MM-dd-yyyy HH:mm:ss, etc.). Here, you can define the date-time format followed by your data provider.

1. Define Format by either choosing Unix TimeStamp Format or Date Time Format.
   • If you chose Date Time Format, from the Enter Date Time Format dropdown, specify the format your data provider follows.
2. From the Selected Time Zone dropdown, select the timezone your data source follows.
3. Once you’re done, click Save & Next.

7.4 Define API Schema

Add and configure the API through which leads will be pulled from the custom data source.

API Configuration
First, configure the API.

1. Select the API request method from the options available (GET or POST).
2. In the Request URL box, enter the base URL and the other parameters you want to pass in the API.
3. Click the Add New button to enter the API headers (accessKey, secretKey, etc.).
4. Click Body, and then click the Add New button to enter the other parameters (startTime, etc.).
   • To edit a parameter, click .
   • To delete a parameter, click .
5. Then, from the available options (Form Data, Raw JSON and x-www-form-urlencoded), select the content type.
6. Once you’re done, click Go to Test API.

Test API
After the API is configured, test it to ensure leads are being pulled as expected.

1. Against the corresponding boxes, enter the values for each parameter.
2. After you’ve entered the values, click Send Test.
3. Once a Success response is returned, in the response, you can view the lead data that’s being pulled.
4. Then, click Go to Response Mapping.

Response Mapping
To help LeadSquared make sense of the API response, map the response parameters as data, success or failure.

For example, if your response looks like this –

{
"users":[
{
"id":35436,
"name":"Robert Jones",
"email":"robert@gmail.com"
},
{
"id":9873843,
"name":"Terry Gilliam"
}]}

For the mapping, response.data.users will be ‘Considered as Data’. This will consider the entire ‘Users’ object as data. You can then map the parameters within the object to the corresponding LeadSquared lead fields – e.g., name to First Name, email to Email, etc.

To map the API response –

1. Click the Add Mapping button.
2. Under the Key and Value fields, map relevant key-value responses.
   • To delete an existing key-value pair, under Actions, click .
3. From the Mapping dropdown, select the correct outcome for that particular response. You can choose Consider as Success, Consider as Error or Consider as Data.
4. After mapping a response, click .
5. To map additional responses, click the Add Mapping button.
6. Once you’re done, click Save & Next.

7.5 Transformation Logic

If the data received via Sync API is complex in structure and needs further transformation to a flat JSON structure, you can configure an External API here to parse the data.

To do this, enable , and configure the transformation API. The steps to configure the API are similar to the previous section, Define API Schema.

7.6 Entity Option

Here, define the sync behavior of the connector when leads, activities and other entities are captured.

Lead/Contact Entity

Based on the Lead Capture Search By criteria (email Id, phone number, etc.), LeadSquared identifies and captures leads from your data provider. Lead capture is enabled by default, and it cannot be disabled. The following options are available to configure the connector’s Sync Behaviour –

• Capture (Create and Update existing) Record – Leads that only exist in your data provider’s account (but not in your LeadSquared account) will get created in LeadSquared. Leads that exist in both your data provider and LeadSquared accounts will get updated.
• Create only new record – Leads that only exist in your data provider’s account (but not in your LeadSquared account) will get created in LeadSquared.
• Update only existing record – Leads that exist in both your data provider’s account and LeadSquared accounts will get updated in LeadSquared.
• Do Nothing – When a lead is created or updated in your data provider’s account, no action will be performed in your LeadSquared account.

Edit Mapping

Once you configure the Sync Behaviour, you’ll have to ensure the field mapping is accurate. To do this, click Edit Mapping.

On the Default Mapping screen, map the API response to the corresponding LeadSquared lead and activity fields. To help you understand how to map your responses, we’ve listed down a few examples –

i) A straightforward, key-value pair response –

{

"page_name": "Final Lender Landing Page",

"page_id": "Summer-Campaign-1364",

"page_url": "http://aroundtheworldin80ways.com/Ladakh"

}

For such a response, you can map the keys to the corresponding LeadSquared lead fields (e.g., page_id to Related Landing Page ID, etc.).

ii) Nested key-value pairs –

{

"campaign":{

"id":"Zendesk-1364",

"title":"Zendesk_Leads"
},

"lead":{

"Name":"Paul Adams",

"email":"paul@example.com",

"phone":"9999999999"

}

}

Here, there’s a key-value pair (“title”) nested within an object (“campaign”). To map the parameters within the object to the corresponding LeadSquared lead fields, map it as a dot notation response (e.g., campaign.title to Source Campaign, etc.).

iii) A key containing a dotted notation –

{

"page_name":"Visit Ladakh",

"page_id":"Summer-Campaign-1364",

"data.json":{

"email":"paul@example.com",

"mobile_number":"9999999999",

"date_submitted":"2021-04-24"

}

}

Here, the key (“data.json”) that contains different parameters (“email”, mobile”, “date_submitted”), is rendered as a dotted notation. To map this key to the corresponding lead field, map it as follows – data*json.email to Email, data*json.mobile_number to Mobile Number, etc.).

iv) An encoded value –

{

"FirstName":"Paul+MX",

"Phone":"9999999999",

"Source":"Zendesk",

"EmailAddress":"mx%example.com"

}

Here, the response value (“EmailAddress”) is encoded (“mx%example.com”). To get the masked value, decode it when mapping the response (e.g., decode=>EmailAddress).

v) When you only want to capture data from certain fields –

{

"items":[

{
"nickname":"Paul",
"body":"From visitor",
"visitor_nickname":"Paul_1364",
"kind":"MessageToOperator",
"timestamp":"1629476535.249866"
},
{
"nickname":"Jai",
"body":"Hi from agent",
"operatorId":"5763330742157312",
"kind":"MessageToVisitor",
"timestamp":"1629476545.909106"
},
{
"nickname":"Jai",
"body":"how agent can help?",
"operatorId":"5763330742157312",
"kind":"MessageToVisitor",
"timestamp":"1629476556.704914"
}

]

}

To capture certain of the fields of the JSON object (“nickname”, “body”) use the parseTranscript key, followed by the JSON section (items in our case), and then give the fields you want to capture (parseTranscript=>items=>[“nickname”,”body”]).

To map your fields to LeadSquared –

• To provide a default value for any field, click  , enter the value under Default Value, and click .
  • If the data provider doesn’t send data for any lead/activity field, then the default value will get assigned to that specific field. But if the field already has an existing value, then the default value will be ignored.
• To disable lead data capture for any field, disable the slider.
• To mark a unique lead/activity field as the search key, click .
• To create a custom Calendly lead/activity field, click the Add Custom button.
  1. Once this field is created, you must map it to the relevant LeadSquared lead/activity field.
  2. After the field is mapped, to save the custom field, click .
  3. To delete a custom field, click .

Call Custom Actions

If required, you can configure the connector instance to perform other actions such as Create Task, Update Task, Create Opportunity, etc. This can be achieved by adding and configuring the relevant LeadSquared API for the action you want to perform. To configure the action –

1. Alongside Call Custom Actions, enable , and click Add Custom Action.
2. On the Define Param Mapping pop-up, enter the following details –
   • Basic Details – Enter the Name and Description of the action (e.g., Create an Appointment). Once you’re done, click Save & Next.

• • Param Mapping – Here you’ll have to map the API parameters to capture details from your LeadSquared account and from the data provider’s account.  
    
    • Click Add Custom, and enter the following details –
      1. API Params – The parameters present in the API you’re passing.
      2. Default Mapping Key – The default value for the corresponding parameter.
      3. Description – The description for the parameter and key you’ve added.
      4. Editable – To allow your users to edit the parameter details, enable . To enhance performance, we recommend that you only edit the Mapping Key, and let all the other details remain as is.
      5. Actions – You can edit or delete an existing parameter.
    • In our example, we’ve added all the mandatory parameters listed under the Create an Appointment API.
    • The values for the first four parameters your see (“TaskType“, “RelatedEntity“, “Reminder“, “NotifyBy“) are present within LeadSquared. This allows us to hardcode the Default Mapping Key for these values, while giving users the option to edit the details if required (e.g., if they want to change the TaskType, if they want to edit the number of minutes before which they receive a notification, etc.).
    • The Default Mapping Key values for the other parameters are dynamic, since the values are being pulled from the data source provider’s account (Calendly in our example). To ensure there’s no format mismatch between LeadSquared and the data provider’s account, we recommend you pass the Default Mapping Key in the LiquidJS format.
    • We’ve passed two additional parameters that are not present in the Create an Appointment API – “event” and “eventId“. These are differentiator parameters. These parameters allow us to perform two different actions (e.g. Create and Update/Create and Delete, etc.) using the same API webhook we’re creating.
      • In our example, if we only pass “event“, a new Appointment task will get created. But if we only pass “eventId“, then an existing Appointment task will get updated.
      • If you’re looking to create a single API that allows you to perform two different actions, we recommend that you add similar differentiator parameters.
    • To add more parameters, click Add Custom.
    • Once you’re done, click Save & Next.
    • Once the API is working as expected, click Save & Close.

• • Define API Schema – Add and configure the API through which the custom actions will be performed in LeadSquared.
    • API Configurations – Add and configure the API URL, the Header and the Body.
      1. In the Request URL box, enter the base URL and the other parameters you want to pass in the API.
      2. Click the Add New button to enter the API headers (accessKey, secretKey, etc.).
      3. Click Body, and then click the Add New button to enter the other parameters (TaskType, NotifyBy, etc.).
         • You can configure the content type format from the available options (Form Data, Raw JSON and x-www-form-urlencoded).
         • You can configure the API language from the available options (JSON or XML).
         • Parameters for which the values that are hardcoded are automatically added to the Body.
         • The “orgID” parameter is optional. You can include it in the Body when testing the API, and you can remove it once the API works as expected. The “orgID” is automatically picked up from your account.
      4. Once you’re done, click Save & Go to Test API.
    • Test API – Once the API details are added, pass values to test the API. Once you’ve added the values, click Send Test.
      • If the API works as expected, click Go to Response Mapping.
      • If the API doesn’t work as expected, identify and fix the errors that are causing the API to fail. Once they’re fixed, click Go to Response Mapping.
    • Response Mapping – To help LeadSquared make sense of the API response, map the response parameters as success, failure or error
      1. Under the Key and Value fields, map relevant key-value responses.
      2. From the Mapping dropdown, select the correct outcome for that particular response.
      3. Under Message, enter the message you want to display in the response.
      4. After mapping a response, click . To map additional responses, click the Add Mapping button.
      5. Once you’re done, click Save & Close. The custom action you’ve configured will now fire as expected.

Activity Entity

Once leads are captured to LeadSquared, you can post custom activities to these leads (e.g., Ticket Creation, Chat Transcript, etc.). These activities will help users keep track of the lead’s journey to conversion. To post activities to the leads captured, alongside Activity Entity, enable the slider. The following options are available to configure the connector’s Sync Behaviour when activities are synced to LeadSquared –

• Capture (Create and Update existing) Record – New activities will get posted to the lead in LeadSquared, while existing activities will get updated.
• Create only new record – Only new activities will get posted to leads in LeadSquared.
• Update only existing record – Only existing activities on the leads captured will get updated in LeadSquared.

The steps to configure mapping is the same as the steps listed above, under Edit Mapping…

In addition to defining the activity entity, you can also create and define the activity schema. This step is optional. If required, you can use existing Custom Activity types when mapping the data source.

To define the activity schema –

1. Against Activity Type(s) Definitions, enable the slider, and click Add Schema.
2. On the Add Custom Activity Type – Define Schema pop-up, on the Schema Details tab, enter the following details –
   • Schema Name – The activity schema name.
   • Description – The activity description.
   • Directions – Inbound or Outbound activity.
   • Delete Activity – To allow your users to delete this activity, enable the checkbox.
   • Track Location – To track the location from where the activity was created, enable the checkbox.
   • Log Activity Changes – To keep a log of all the activity changes, enable the checkbox. To know more, refer to How to Log Activity Updates.
   • Allow pre-dated Activities – To allow your users to post this activity on a past date, enable the checkbox.
   • Show in Activity List – To display the activity on the Manage Activities page, enable the checkbox.
3. On the Param Mapping tab, create and add custom fields to the activity. To know more, refer to How to Add Custom Activity Types.
   • Display Name – The display name of the activity field (e.g., PAN number, etc.).
   • Type – The data type for the field (e.g., Number, Dropdown, etc.).
   • After creating a field, click . To create additional fields, click the Add Field button.
4. Once you’re done, click Save & Close.

Once the connector’s sync behaviour is configured, click Save & Next.

8. Other Actions

You can perform the following actions on your custom integration –

• Edit Basic Information – Change and edit the basic details (data source name, logo, etc.).
• View Logs – View logs of all the sync jobs that have taken place.
• Delete Data Source – Delete the entire data source, including all the settings.

Any Questions?

Did you find this article helpful? Please let us know any feedback you may have in the comments section below. We’d love to hear from you and help you out!