Integration Builder

The Integration Builder feature allows you to create new custom integrations for products in real-time. Only users with the Global Admin and LMS Admin system roles have access to view and manage the Integration Builder feature.

General Tab

Integration Config Tab

Array Mapping Tab

Request Mapping Tab

Response Mapping Tab

Testing Tab

Logs Tab

Note: This feature is available only upon request and currently works only for the LMS Products. The Integration Builder requires a certain level of expertise in coding languages as it is primarily designed for developers.

To access the Integration Builder, go to the Client Management > Setup > Integration Builder section.

The Integration Builder section contains the following information:

  • ID: The unique identification number of the custom integration.

  • Name: The name of the integration.

  • Status: The status of the integration (Active / Disabled).

  • Product: The name of the Product

  • Created: The date and time when the integration was created.

  • Updated: The date and time when the integration was last updated.

You can narrow down the search results by using the following filters:

  • Name: Enter the name of the integration.

  • Status: Select the status of the integration (Active / Disabled).

  • Product: Select the Product.

To create a new custom integration, click the “Add new record” button and fill in the following fields in the pop-up window:

  • Type: Select the type of integration (New / Import).

    • Select the “New” option to create a new integration.

    • Select the “Import” option to upload a file with custom integration created in Integration Builder in JSON format.

  • Name: Enter the name of the integration.

  • Product: Select the Product.

Click the “Add” button to create the integration.

To create a new integration based on an existing custom one, click the “Clone” button in the “Actions” column of the corresponding integration. Enter a name for the new integration in the pop-up window and click the “Clone” button to confirm.

To download the integration in JSON format, click the “Export” button in the “Actions” column of the corresponding integration.

To configure the integration, click the “Configure” button in the “Actions” column of the corresponding integration, and the system will redirect you to the “Builder” setup page. Use the following tabs to configure or update the integration.

General Tab

The General tab allows you to view the general information about the integration and change its name and status.

  • Integration Name: Enter the new name for the integration or leave it as it is.

  • Product name: The name of the Product for which the integration was created.

  • Post model: The type of the Product.

  • Date updated: The date and time of the last update of the integration.

  • Status: The status of the integration (Active / Disabled).

  • Save campaign ID to Lead Stash: Check this box to save the campaign ID to the Lead Stash (e.g., for Ping Post Calls flows).

Click the “Save Integration” button to save changes.

Integration Config Tab

The Integration Config tab allows you to configure the integration parameters displayed on the “Integration” tab of the Campaign settings. These parameters can be later configured from the “Integration” tab directly, without updating the integration. You can add an unlimited number of parameters. If you need to remove any of the parameters, at least one parameter should be present. Example: The Redirect integration contains the “Redirect URL” parameter allowing you to add the redirect link on the “Integration” tab.

The Integration Config tab contains the following settings:

  • Variable Name: The name of the parameter. It should be unique and not match any existing parameter. The first character should be in lowercase.

  • Label: The name of the parameter displayed on the “Integration” tab.

  • Type: Select the “String” option to set the field type as a string (allows letters, numbers, and special symbols). The “Select” option sets the field type as select with configurable values for selection (Value / Label).

  • Required: Select the “True” option to set a required field. Select the “False” option to set a non-required field. You cannot perform a Request Test or a Response Test unless you fill out the values for config fields you have indicated as “Required”.

To add more parameters, click the “Add new” button.

Note: Any changes to the Integration Config fields will affect the running integration. After you apply the changes, you must review and update the integration settings of the previously set-up campaigns to ensure successful processing.

Array Mapping Tab

The “Array Mapping” tab allows you to configure the variable mapping that can be used in the Request mapping. The list contains all the variables available for the mapping based on the selected Product.

Select the variable from the drop-down list and click the “Add Mapping” button to edit the mapping for the selected variable.
Click the “+” button for the selected variable to display the mapping configuration block. 

The configuration block contains the following setting fields:

  • Slug: The name of the parameter. The name should be unique and not match any existing parameters.
  • Label: The parameter value received. The default value is used if no value is received. 
  • Mapping: The value that will be mapped to the received value and sent in the request. Values are case-sensitive and should match integration requirements.

Once the “Array Mapping” is configured, you can refer to this mapping in the “Request Mapping” tab. 

Request Mapping Tab

The “Request Mapping” tab contains the integration request settings and allows you to configure the request.

Turn on the “Add PrePing” toggle to activate the option to build integrations with the PrePing functionality.


The “Request builder (PrePing)” block allows you to configure the following settings: 

  • Request::Url: The post URL. The default value corresponds to the variable added by default on the Integration Config tab. 
  • Method Type: Select the posting method type for the request. 
    • For the “GET” type, fill in the additional parameters of the request in the Headers and Query Params blocks. 
    • For the “POST” type, configure the Data Type block of settings.
  • Headers and Headers/Query Params: If the integration documentation contains Headers or  Headers/Query Params, you can configure it here. The value type of the fields is Key:Value


By choosing POST as a method type, select the data format for the request (XML, JSON, FORM, None) in the “Data Type” field. Depending on the selected data type (XML/JSON/FORM), there are different configuration settings available:

  • The XML data type.
    Click the “Import By Sample” button to import the XML sample of the request. The Builder will fetch and add configured fields for further review and editing. The XML configuration:
  • Name: Enter the name of the parameter. It should be unique and not match any existing parameter.
  • Type: Select the data type (Object / String).
  • Value: Enter the variable from the list of available variables that will be used in the request. Start typing to see the suggestions. Please note that the value field supports Twig.

  • The JSON data type.
    Click the “Import By Sample” button to import the JSON sample of the request. The Builder will fetch and add configured fields for further review and editing. The JSON configuration:
  • Name: Enter the name of the parameter. It should be unique and not match any existing parameter.
  • Type: Select the data type (Object / Array / Boolean / String Number / NULL).
  • Value: Enter the variable from the list of available variables that will be used in the request. Start typing to see the suggestions. Please note that the value field supports Twig.

  • The FORM data type.The FORM configuration:
  • Name: Enter the name of the parameter. It should be unique and not match any existing parameter.
  • Type: The data type (String).
  • Value: Enter the variable from the list of available variables that will be used in the request. Start typing to see the suggestions. Please note that the value field supports Twig.


Note: Depending on the field and API documentation, "Value" fields can be hardcoded, mapped, or passed from the config or lead.

The Request Mapping tab allows creating conditions using the “Condition” parameter. The “Condition” allows you to manage the parameters sent in the request. Please note that the “Condition” field supports Twig.

Example: We have a “driver” object, and we do not want to include the “driver1” object into the parameters if it doesn’t match the required age. If the condition is < 18, then the request will not contain the parameters for the “driver1” object as it does not match the requirements. Therefore, if the condition is > 18, then the request will contain the object’s parameters.

Switch the “Does Response Need To Be Stored” toggle to the “On” position to enable the option to save the PrePing response for later use.   

Example: We have a PrePing response to obtain a bearer token for the integration. The Buyer doesn’t want to receive the token after processing every single lead but to use the same token for all the leads across the integration. 

To set up the “Does Response Need To Be Stored” function, fill in the following fields:

  • Response Store Key Name: The name of the storage for the received PrePing response. 
  • Response Store Ttl (in sec): The storage period (in seconds) of the received PrePing response. 

The “Request builder (POST)” block has the same structure and is configured in the same way as the “Request builder (PrePing)” block.

   

Response Mapping Tab

The “Response Mapping” tab allows you to configure the response processing. The Response Mapping settings should be based on the response details provided in the integration documentation. The “Response Mapping” fields support Twig. 

To set up the response configuration, fill in the following fields:

  • Data Type: Select the data processing format (XML / JSON / PLAIN). 
  • Accept::Sign: The condition that defines if the lead was accepted. 
  • Accept::Price: The field that records the offer price (if received).
  • Sold::Sign: The condition that defines if the lead was sold. 
  • Sold::Price: The field that records the price (if received).
  • Sold::RedirectUrl: The field for the redirect link (if received).
  • Reject::Sign: The condition that defines if the lead was rejected. If the condition states the “is defined” option, all statuses will be processed as rejected. 
  • Reject::Reason: The field that records the reason for the reject.
  • Error::Reason: The field that records the reasons for all other errors.

Note: The response configuration fields support Twig.

You can find the configured Response Mapping example on the screenshot below:

The example of a JSON response:

The “sold” status is displayed in the global object key “status” with the “sold” value. The “Sold::Sign” field depends on the received status (for example, if we set the response.status == “sold” value, it will define if the lead is sold or not. 

For the “price” parameter, we put the value received in the response of the sold lead. As the “price” parameter is inside another object, we put the “response.price.unitValue” value.

For the “redirectUrl”response.redirectUrl.

An example of a response for an invalid request:

If the lead is rejected, the “status” parameter displays the “400” value. There can also be other responses, including the authorization error or any other error, but the Response Builder provides an option only for the rejected status. That is why we put the “response.status is defined” value into the “Reject::Sign” field - which means that all the received statuses will be processed as rejected, except for the “sold” status as it already has a condition set up.

Then we set the “response.title” value for the “Reject::Reason” field.

The response might not contain the price, redirectUrl, or errors in some cases. In this case, the corresponding fields should be left blank.

To set up the “PrePing response builder” block switch the “Add PrePing” toggle to the “On” position. 

 

To set up the response configuration, fill in the following fields:

  • Data Type: Select the data processing format (XML / JSON / PLAIN). 
  • Success::Sign: The condition that defines if the lead was sold. 
  • Error::Reason: The field that records the reasons for all other errors.

The “Response PrePing” block can process and reuse the values received in the response. To configure it, in the “Optional Lead Variables” block, fill in the variable name in the “Variable Name” field. Fill in the processed value in the “Expression” field.

Note: The Response Builder setup might require some coding knowledge to analyze the response of the buyer system. 

Testing Tab

The “Testing” tab allows you to emulate the test of the created integration.

The tab contains the fields added to the “Integration Config” tab. To run the test, first, fill in those fields. Note: Only those fields defined as required must be filled in with dummy data. Optional fields can be left blank. 

To check the correct sending of the Request, click the “Perform Test” button in the “Request Preview” block. The Request Test allows checking if the request is formed correctly after Request Builder variables have been configured. 

To check the correct processing of the Response, enter the data in JSON or XML format from your Integration Documentation and click the “Perform Test” button in the “Response Check” block. Note: The PING response needs to result in a sale for the test to proceed to the POST response test.

Logs Tab

The Logs tab allows you to view the changes and compare all the previous backup versions of the Integrational Builder events stored in the system.

The list of logs contains the following information:

  • Created: The date and time when the integration builder event was created.
  • Name: The name of the integration builder event.
  • User: The user who initiated the integration builder event.
  • Type: The type of the integration builder event (Log, Restore).
  • Diff: The versions comparison.
  • New Schema: The new code schema.
  • Old Schema: The old code schema.

You can narrow down the search results by using the following filters:

  • Created Date: Select the date of creation (Any time, Last six months, Today, Yesterday, This Week, Last Week, This Month, Last Month, Custom Range).
  • Type: Select the type (Log, Restore).
  • Integration: Select the integration.
  • User: Select the user.

To compare the versions of the integration builder event, click the “Diff” button in the “Actions” column. The blocks will be loaded automatically. All the changes are highlighted in yellow, and all the new records are highlighted in green.

To restore the previously saved backup version of the integration builder event, click the “Restore” button. Also, the “Restore” button is available in the corresponding event in the “Actions” column.

In the “Restore to this version” popup window, enter the “Yes” word and click the “Restore” button to confirm the action.

Note: The Restore event will be logged and displayed if “Restore” was done by a user.