Universal Data Sync (UDS) – Define Authentication Variables

1. Feature Overview

With UDS, you can create an application and set up multiple data flows within it, enabling you to consolidate and manage all data flows for a single provider or purpose, within one unified group.

To call an API within these flows, you must setup authentication and authorisation credentials, such as tokens or keys. In UDS, you have a centralized space to securely store your authentication tokens and keys in one place. These credentials can be easily utilized across multiple flows within the same application, simplifying management and reducing redundancy.

If you’re new to UDS, see Getting Started with UDS.

2. Prerequisites

• You must be an Administrator user.
• The Universal Data Sync Connector is a paid feature. To enable it on your account, contact your account manager, or write to support@leadsquared.com.
• You must first create an App within UDS before you define authentication variables. For more information, see Create an App on UDS.

3. System and Custom Authentication Variables

You can configure the following variables:

• System Variables:
  These are predefined variables related to LeadSquared and UDS. They can be directly used in flows to dynamically render their actual values during execution.
• Custom Variables:
  These are user-defined variables that allow you to store and manage authentication credentials or other values specific unique to your business requirements.

To add a custom variable –

1. Click Add New.
2. Enter the display name of the variable. Supported characters include uppercase letters (A-Z), lowercase letters (a-z), numbers (0-9), hyphen/dash (-), underscore (_) and spaces.
3. Enter the data type.
4. If you mark the field as mandatory, and no value for the field is received over the webhook (the webhook is generated in a later step), the request is failed at the first touch-point to avoid unnecessary API calls.
5. Add a description for the variable.
6. Select the value of the variable as either Custom or Call API/LAPP.
   • Use Custom to hard-code a static value for the variable.
   • Use Call API/LAPP to dynamically populate the value of the variable from an API call or from the response of a LeadSquared LAPP.

For example, let’s say we need to call an API to generate an authentication token to securely connect to a third-party application. The API requires a AccessKey and SecretKey parameters in the request, and returns the AuthToken in the response. We’ll create 3 variables –

1. For Access_Key and Secret_Key, we’ll select the value of the variable as Custom and hard-code the values.
2. For the Auth_Token, we’ll select the value of the variable as Call API/LAPP, and configure the API to pass the AccessKey and SecretKey in the request and populate the AuthToken from the response.

4. Third Party API Setup

After selecting Call Lapp/API, configure the third-party API. This involves 3 steps –

1. Input cURL Request –

1. Click Edit Details and enter the API cURL request.
2. Scroll down and click Save & Next.

2. Define Param – 

1. The parameters are automatically populated based on your cURL request.
2. Change the Type of the parameter if required.
3. Under the Mapping column, map the parameters from the cURL request to the authentication variables you’ve created, or type the values in manually and press enter.
4. Use the delete icon under the Actions column to remove unwanted parameters.
5. Scroll down and click Save & Next.

3. API Configuration –

This section is auto-populated based on your cURL request. If required, you can make changes to the API configurations here –

1. Edit the HTTP method (Post, Get, etc.).
2. On the top right section, click View Merge Fields. You’ll see the list of parameters and LeadSquared system authentication variables (e.g., LEAD_ID, ORG_ID, LSQ_SECRET_KEY, APPLICATION_ID, etc.). You can append these parameters to the API query string or the the request body.
3. On the Headers tab, click Add New to add headers to the API request. Enter the required key-value pairs.
4. Navigate to the Body tab and review the request body. If required, change the request format (e.g., Form Data, www-form-urlencoded, Raw JSON/XML etc.).Click the View Merge Fields link to copy and add additional parameters.
5. Click Save & Close when you’re done.

5. Response Mapping For Success

Response Mapping lets you map parameters from a third-party API response to variables in LeadSquared. This enables seamless data integration, as the values returned by the external API can be dynamically captured and utilized in your data flows. Here you can define and map a successful response –

1. Data Key Selection –

1. Enter or paste the API response in the space provided.
2. Next select the child key. These are auto-populated in the drop-down based on the parameters available in the API response.

2. Success Criteria – 

Map custom HTTP response codes and keywords to indicate successful API calls. This is helpful when third-party APIs use non-standard response codes (instead of the typical 2xx OK) to signal a successful response. Additionally, they may include success keywords in the response body, such as "status": "completed" or "message": "success".

You can configure these unconventional success indicators in the connector by mapping specific response codes or keywords. This ensures your data flows proceed as expected, even when dealing with non-standard API responses.

1. Click Add Custom.
2. Enter the HTTP Response code and the keyword, and hit enter.

3. Token Expiry

Optionally, you can configure the expiry time for a token received in the API response. This ensures that the token remains valid for the designated period. Either –

• Select Response Key if the expiry value is received as a part of the response. This sets the expiry period based on the value returned by the API.
• Select Fixed Value to hard-code the time after which the token will expire.  The maximum allowed is time is 7 days or 604800 Seconds.

6. Response Mapping For Errors

Similarly, you can map specific HTTP response codes or keywords to indicate an error during an API call. This allows the system to detect and handle failed responses effectively. You can configure error handling by –

• Mapping HTTP error codes such as 400, 404, or 500 to indicate a failed request.
• Using error keywords from the API response body, such as "status": "failed" or "error": "invalid_request", to identify errors even when the HTTP code may not explicitly indicate failure.

1. Alongside Response Mapping for Error, click Edit Details.
2. Click Add Custom.
3. Enter the HTTP Response Code, Keyword(s) and Error Message. Click Auto Retry to initiate another API call (maximum limit is 3 times).
4. Scroll down and click Save & Close.

The Call LAPP/API configuration is now complete. The hard coded Access_Key and Secret_Key variables will now be passed in the third-party API request body, and the Auth_Token variable will be populated with the value from the API response.

7. Other Actions

Data Flow Level Actions

• Edit Flow – Editing the flow allows you to add more actions or edit existing ones. This includes adding new APIs, changing the parameter mapping, etc.
• Delete Flow – Delete the data flow, including all actions configured under it.
• View Logs –Track the execution history of your data flows. View detailed logs of inbound and outbound flows, including timestamps, statuses, and any errors encountered during the integration process. This helps you monitor and troubleshoot data sync activities efficiently
• Copy Webhook – Copy the webhook generated for the data flow and use it to create a LeadSquared webhook or automation, or to call the webhook from a custom source (e.g., Postman).
• Advanced Options – Edit the API request limits configured for the third-party APIs.

8. Next Steps

After defining the Authentication variables, create an Inbound or Outbound Data Flow.

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!