Integrate Your Custom Data Source with LeadSquared

1. Feature Overview

In addition to the default data sources (99acres, Housing.com, Unbounce, Shiksha.com, etc.) listed on your account, you can also build custom integrations to capture leads from other data sources (e.g., Zendesk, Freshdesk, Zohodesk, etc.).
Once the leads are synced, you can leverage LeadSquared’s CRM features to nurture and convert your leads. Before you get started, install and configure the Universal Lead Capture Connector.

Note: Depending on your data provider, you can configure the connector to capture leads in real-time or periodically.

 

2. Prerequisites

  • You must be the Administrator of your LeadSquared account.
  • You must have developer experience (the connector requires API integration, see the following section).
  • The Universal Lead Capture connector is a paid feature. To enable it on your account, please reach out to your account manager, or write to support@leadsquared.com.
  • API to facilitate periodic lead sync from the third-party application to LeadSquared. The API must allow leads to be fetched by date range –
    • 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 header or query string). Complex authentication methods such as OAuth are not supported.

 

3. How it Works

Real-time Sync

Through real-time sync, leads are pushed to LeadSquared in real-time, by your data provider.

1. Connector Configuration

First, create, configure and test your custom data source.

  • In this step, configure the webhook format and map the API response data to the corresponding lead fields in your LeadSquared account. Once this is completed, a webhook URL is generated.
  • Configure this webhook URL in your data source provider’s account.

2. Run-time Configuration
After you’ve configured the connector, it gets listed on the Lead Capture app page.

LeadSquared Integration

  • At run-time, users can pass the authentication or any other variables required. They can set up failure notifications and override the sync frequency (configured at the connector level) if required.
  • Finally, users can enable the sync. There’s also a feature that allows you to sync historic data.

Once the sync is enabled, the connector is live, and data is pulled into your LeadSquared account.

3. View Logs
Logs are available for each sync instance. You can view all the data being pulled to your LeadSquared account from here. Notifications set up in the previous step will also inform you (via email) about failures.

 

Periodic Sync

Through periodic sync, you can configure the frequency based on which you want to pull leads from your custom data source to LeadSquared.

1. Connector Configuration
First, create, configure and test your Sync API.

  • In this step, configure the authentication variables, define the accepted formats for date/time data, and decide the sync frequency.
  • Then map the API response data to the corresponding lead fields in your LeadSquared account.

2. Run-time Configuration
After you’ve configured the connector, it gets listed on the Lead Capture app page.

LeadSquared Integration

  • At run-time, users can pass the authentication or any other variables required. They can set up failure notifications and override the sync frequency (configured at the connector level) if required.
  • Finally, users can enable the sync. There’s also a feature that allows you to sync historic data.

Once the sync is enabled, the connector is live, and data is pulled into your LeadSquared account.

3. View Logs
Logs are available for each sync instance. You can view all the data being pulled to your LeadSquared account from here. Notifications set up in the previous step will also inform you (via email) about failures.

Note: The following steps have been demonstrated using Zendesk public APIs. This is purely done for instructional purposes and can be substituted with the API of your application.

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 –

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

 

4. Installation

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

  1. On your LeadSquared account, navigate to Apps>Universal Lead Capture.
  2. Click Add Data Source, and on the Enter Basic Information pop-up, provide –
    • Data Source Name – The name of the data source from where leads will be pulled.
    • Help – The help article URL, which covers installation and configuration.
    • Description – A short description of the data source.
    • 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.

Integrate LeadSquared with your custom data souce

 

5. Set-up – Real Time Sync

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

Integrate LeadSquared with your custom data souce

 

5.1 Webhook Format

Enter the following webhook details –

Integrate LeadSquared with your custom data souce

PropertyDescription
API MethodThe HTTP method. Choose between GET and POST methods.
Selected Time ZoneThe time zone your data provider follows.
Lead SourceEnter the lead source through which the leads were captured (e.g., Zendesk, QuikrHomes, email campaign, etc.). This detail will be displayed on the Lead Details page, under Lead Source.

To make the lead source Editable, click the Checkbox checkbox.

Set-up InstructionsIf required, you can add set-up and configuration instructions for your users.

Once you’re done, click Save & Next.

 

5.2 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 Slider, and configure the transformation API. The steps to configure the API are similar to the below section, Define API Schema.

Integrate LeadSquared with your custom data souce

 

5.3 Mapping

On the Mapping screen, map the API response to the corresponding LeadSquared lead 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”]).

Integrate LeadSquared with your custom data souce

Once you’re done, click Save & Close. Then, configure the connector to begin pushing leads from your custom data source to LeadSquared.

 

6. Connector Configuration – Real Time Sync

After setting up your real-time sync connector instance, on the Lead Capture page, configure the connector settings to enable your data source to push lead data to LeadSquared.

  1. Navigate Apps>Universal Lead Capture.
  2. Under the custom data source you created, click Configure.
  3. On the Lead Capture page, click Real-time Sync.

Integrate LeadSquared with your custom data souce

 

6.1 Basic Details

Enter the following details –

Integrate LeadSquared with your custom data souce

PropertyDescription
Lead SourceEnter the lead source through which the leads were captured (e.g., Zendesk, QuikrHomes, email campaign, etc.). This detail will be displayed on the Lead Details page, under Lead Source.
Default Country CodeIf the lead’s mobile number is captured without a country code, then the default country code that’s selected from the dropdown will be added to the lead’s mobile number.
Select Time ZoneThe time zone of your custom data provider.
Lead Capture Search By CriteriaTo avoid duplicate leads, you must select one unique lead field (e.g., email Id, mobile number, PAN number, etc.) as the search key. This will be used to identify the leads pushed from your data provider.

To know how to mark a LeadSquared lead field as unique, please refer to How to Make a Custom Field Unique.

Select User to Notify on FailureIf there is an error in fetching leads, the selected user will receive a failure message via email. You can select a user from the list of all the users available in your LeadSquared account.

To know more about the type of errors, please refer to Error Notifications.

Once you’re done entering all the details, click Save & Next.

 

6.2 Mapping

On the Mapping screen, map the responses from your data provider to the corresponding lead field. The custom data source fields you’ve provided will be visible by default. If required, you can change or update the default field mapping.

  • To provide a default value for any field, enter the value under Default Value.
    • If the data provider doesn’t send data for any lead 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 Zoom slider.
  • You can also mark and update a unique lead field as the search key from this screen, by clicking unique icon.
  • To create a custom field, click the Add Custom button.
    1. Once this field is created, you must map it to the relevant LeadSquared lead field.
    2. After the field is mapped, to save the custom field, click Google.
    3. To delete a custom field, click .

Once you’re done mapping, click Save & Next.

Integrate LeadSquared with your custom data souce

 

6.3 Webhook URL

After you provide basic details and finish field mapping, a custom webhook URL is generated. To automate lead capture, copy this URL and configure it in your data provider’s account. Reach out to your data provider’s account manager to know how to do this.

After you’ve configured the URL, click More Actions, and enable the sync job. This ensures the data will be pushed to LeadSquared using the webhook.

Integrate LeadSquared with your custom data souce

Note:

  • The API must be configured in the HTTP method you used when configuring the data source.
  • From the More Actions dropdown, click View Logs to view the logs of all sync jobs that have taken place.

 

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.

Integrate LeadSquared with your custom data souce

7.1 Basic Settings

On the Basic Settings screen, enter the following details –

Integrate LeadSquared with your custom data souce

PropertyDescription
Lead SourceEnter the lead source through which the leads were captured (e.g., Zendesk, QuikrHomes, email campaign, etc.). This detail will be displayed on the Lead Details page, under Lead Source.

To make the lead source Editable, click the Checkbox checkbox.

Lead Capture Search By CriteriaTo avoid duplicate leads, select one unique lead field (e.g., email Id, mobile number, PAN number, etc.) as the search key. This will be used to identify and pull leads from your custom data source.
To know how to mark a LeadSquared lead field as unique, please refer to How to Make a Custom Field Unique.
Sync FrequencyUse the ‘Hours’ and ‘Minutes’ dropdowns to select a custom interval, based on which lead data will be pulled.

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 them in your Sync API to pull data based on date/time fields in the LeadSquared system.

Integrate LeadSquared with your custom data souce

 

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 Google 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.,

Note: 

  • To edit an existing variable, click .
  • To delete an existing variable, click .

Integrate LeadSquared with your custom data souce

 

7.3 Sync Start and End Time Settings

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

  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 source follows.
  2. From the Selected Time Zone dropdown, select the timezone your data source follows.
  3. Once you’re done, click Save & Next.

Integrate LeadSquared with your custom data souce

Note: You can also add your own custom Date Time format, by pasting the format (YYYY-MM-DDTHH:mm:ssZ, etc.) in the Enter Date Time Format box.

Integrate LeadSquared with your custom data souce

 

7.4 Define API Schema

Add 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.

Integrate LeadSquared with your custom data souce

 

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, you can view the lead data that’s being pulled within the response.
  4. Then, click Go to Response Mapping.

Integrate LeadSquared with your custom data souce

 

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 SuccessConsider as Error or Consider as Data.
  4. After mapping a response, click Google.
  5. To map additional responses, click the Add Mapping button.
  6. Once you’re done, click Save & Next.

Integrate LeadSquared with your custom data souce

 

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 Slider, and configure the transformation API. The steps to configure the API are similar to the previous section, Define API Schema.

Note: This step is optional. It can be used to transform the Sync API response.

Integrate LeadSquared with your custom data souce

 

7.6 Default Mapping

To complete the API configuration, map the API response fields to the relevant LeadSquared lead fields. This will ensure that the lead data will be mapped to the correct lead field.

  1. Click the Add Custom button.
  2. Enter the response field and the corresponding LeadSquared lead field.
    • To delete an existing field mapping, under Actions, click .
  3. Once you’re done, clickGoogle.
  4. After adding all the fields, click Save & Close. The lead data will now be mapped to the selected lead field.
Note: To capture lead data from the same data source in real-time, click Go to Real-time Settings.

Integrate LeadSquared with your custom data souce

 

8. Connector Configuration – Periodic Sync

After setting up your periodic sync connector instance, on the Lead Capture page, configure the connector settings in order to pull data from the custom data source.

  1. Navigate Apps>Universal Lead Capture.
  2. Under the custom data source you created, click Configure.
  3. On the Lead Capture page, click Real-time Sync.

Integrate LeadSquared with your custom data souce

 

7.1 Settings

On the Settings screen, enter the following details –

Integrate LeadSquared with your custom data souce

PropertyDescription
DetailsThe custom variables you’ve provided while setting up the data source are listed here. Provide the values for each parameter.
Lead SourceEnter the lead source through which the leads were captured (e.g., Zendesk, QuikrHomes, email campaign, etc.). This detail will be displayed on the Lead Details page, under Lead Source.
Default Country CodeIf the lead’s mobile number is captured without a country code, then the default country code that’s selected from the dropdown will be added to the lead’s mobile number.
Select Time ZoneThe time zone your data provider follows.
Lead Capture Search By CriteriaTo avoid duplicate leads, select one unique lead field (e.g., email Id, mobile number, PAN number, etc.) as the search key. This will be used to identify and pull leads from the custom data source.

To know how to mark a LeadSquared lead field as unique, please refer to How to Make a Custom Field Unique.

Select User to Notify on FailureIf there is an error in fetching leads, the selected user will receive a failure message via email. You can select a user from the list of all the users available in your LeadSquared account.
Sync FrequencyBy default, we display the sync frequency you selected when setting up the data source. If required, you can update the frequency.

Once you’re done entering all the details, click Save & Next.

 

7.2 Mapping & Manage Sync

On the Mapping screen, the custom data source fields you’ve provided will be visible by default. If required, you can change or update the default field mapping.

  • To provide a default value for any field, enter the value under Default Value.
    • If data is not captured for any lead 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 Zoom slider.
  • You can also mark and update a unique lead field as the search key from this screen, by clicking unique icon.
  • To create a custom field, click the Add Custom button.
    1. Once this field is created, map it to the relevant LeadSquared lead field.
    2. After the field is mapped, to save the custom field, click Google.
    3. To delete a custom field, click .

Integrate LeadSquared with your custom data souce

 

Enable Sync

After mapping the data source fields to the corresponding LeadSquared lead fields, enable lead sync. From the More Actions dropdown, click the Slider slider, and then click Save & Close. Once the sync is enabled, LeadSquared will pull leads from the data source depending on the Sync Frequency configured.

Integrate LeadSquared with your custom data souce

You can also manually sync leads, outside of the Sync Frequency that’s configured. This is especially useful if you have old/legacy lead data in your custom data source account.

  1. From the More Actions dropdown, click Sync Manually.
  2. On the Sync Manually pop-up, enter Start Date, End Date, and Time during which the lead data was captured in your data provider’s account.
  3. Once you’re done, click Submit. The leads that were captured during the selected time frame will be synced to LeadSquared.

Note:

  • It is recommended you run a manual sync job right after you configure the connector. This will ensure all the historic lead data available on your custom data source account will be synced to LeadSquared.
  • The Sync Start Time & End Time must be within a date range of seven days (e.g., from 20th July to 26th July).
  • You can sync up to 4,000 leads at once.

Integrate LeadSquared with your custom data souce

 

9. View Logs

Here, you can view logs of all the sync jobs that have taken place. View new leads, updated leads, lead capture errors and total lead capture events. You can also view the lead sync response and lead capture job status.

  1. Navigate to Apps>Universal Lead Capture.
  2. Against the custom connector, click Options, and then click View Logs.
    • Alternatively, from the configurations screen, you can click the View Logs button.
  3. You can filter the logs by selecting a date range, and by selecting a Job Status (“All”, “Success” and “Failure”).
    • The maximum date range you can select is the last 60 days.
  4. You can view the sync status of the leads captured across the following tiles –
    • New Leads – List of all the new leads that have been captured by LeadSquared during the selected date range.
    • Updated Leads – A list of all the –
      • Duplicate leads that were created with the same Search by Criteria value (e.g., with the same Email Id, Mobile Number, etc.).
      • Leads that previously contained an error, which were fixed and synced successfully.
    • Errors – The list of leads that have not been captured due to mapping errors (e.g., when a boolean field is mapped to an integer field, etc.).
    • Total Events – A list of all the lead capture events that have taken place.
  5. To view the Sync Response details, under Sync API Response, click the response.
    • Here, you can view the response status, the API URL, the request and the response.
    • The responses that are successful will contain the details of the leads that have been captured from the custom data source.
    • You can also view the lead capture response under Created, Updated and Errors, by clicking Information.

Note:

  • For a response that contains an error, the reason for the error is listed in the response. Once you fix it, you can click the Retry button to perform the sync again.
  • For a response that’s failed, the reason for the failure is listed in the response. Once you fix it, under Actions, you can click the Retry button to perform the sync again.

LeadSquared Integration

 

9. 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.

Integrate LeadSquared with your custom data souce

You can also perform the following additional actions –

  1. Navigate to Apps>Universal Lead Capture.
  2. Against the custom connector, click Options.
  3. From the list of options, you can perform the following actions –
    • Edit Settings (the Basic Settings and Sync API Configurations)
    • Edit Configurations
    • View Logs
    • Help
    • Remove Configurations

LeadSquared Integration

 

10. View Reports

You can view the total number of leads that have been pulled from your custom data source by referring to the Lead Source report. To know more, please refer to How to track the source of your Leads using Lead Source Report?

LeadSquared Integration

 

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!

Was this Helpful?

Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments