Universal Connector - Integrate With Enrichment and Validation Providers Flexibly Follow

Overview

The Universal Connector is a new feature that helps improve the quality of your leads by enriching and validating them with third-party API integrations.

Please note: This feature is currently in beta. We are reviewing customer requests for integration with enrichment and validation services using Universal Connector. Get in touch with our support team to be added to the waitlist.

 

Setup Process

The below information is provided for informational purposes. We only provide assisted use of this feature at the moment. Our Support team will set up the integration for you based on the API documentation and authorisation details that you provide. We strongly discourage you from adjusting the Universal Connector configuration at this stage.

  1. Navigate to Processr > Quality Assurance tab within your campaign
  2. Click Add to add a new Processr job
  3. Select 'Universal Connector' from the dropdown in the Job field
  4. You will see the Universal Connector job configuration fields
  5. Configure endpoint details in the 'API' and 'Headers' sections of the form
  6. Configure request details in the 'Mapping' section of the form
  7. Configure lead data enrichment from the API response in the 'Result Mapping' section of the form
  8. Configure API response validation in the 'Validation Conditions' section of the form
  9. Click Save
  10. Optionally, navigate to Processr > Integration and configure how the enriched data should be mapped with your lead integrations

 

Universal Connector Job Configuration Reference

Configuring Endpoint and Requests

The below configuration must be based on the API documentation provided by the service you are integrating with.

API

Configure endpoint details:

  • ApiUrl: URL of the API endpoint starting with "https://".
  • Method: Endpoint HTTP method
  • Verify_ssl_peer: Enable SSL peer verification. Choose 'Yes' unless you are experiencing SSL connection problems
    Please note: Choosing 'No' will result in a less secure connection. We strongly discourage you from using this option.
  • Send_as_json: Send requests as JSON. If set to 'No', we will send requests as form data

Headers

Configure request HTTP headers. Add as many header names and values as required by the API.

OAuth

If the service you are connecting to requires OAuth authentication, then you will need to fill this section.

Configure OAuth authentication

  • URL: OAuth endpoint URL
  • Access_token_key: Response field that has the access token. For example, if access token is returned as "access_token" response element, then "Access_token_key" should be set to "access_token",
  • Method: OAuth endpoint HTTP method
  • Grant_type, Client_id, Client_secret: OAuth authentication request parameters

Click 'Add' or 'Remove' to provide other parameters if the OAuth process of the connected service isn't covered by the default set.

Using the token that was retrieved during OAuth process

The token that was retrieved by the OAuth can be used in other configuration sections as a "##token##" placeholder

For example, in the Authorization Bearer HTTP header:

Screenshot of using the OAuth token as Bearer Token.png

Mapping

Configure the request parameters. You can use hardcoded values or map lead data values automatically.

Example 1:

Mapping 'external_campaign_id' to 'campaignId' will send the following requests for the lead that belongs to the campaign ID 1234.

JSON request:

{
  "external_campaign_id": 1234
}

Form data request:

external_campaign_id=1234

Example 2:

You can map requests that have nested objects as well.

Image of the Mapping section of the Universal Connector modal, showing 'external' and campaign_id' mapping

Mapping 'external' with the nested 'campaign_id' to 'campaignId' will send the following JSON request for the lead that belongs to the campaign ID 1234.

{
  "external": {
    "campaign_id": 1234
  }
}

Example 3:

Use the |hardcode integration filter to map hardcoded values that might conflict with lead data fields.

Mapping 'contact_type' to 'email|hardcode' will send the following request for the lead with john.doe@example.com email:

contact_type=email

At the same time, mapping 'contact_type' to 'email' will send the following request for the same lead:

contact_type=john.doe@example.com

 

Configuring Lead Data Enrichment

Result Mapping

Configure the mapping of the data returned by the enrichment API to lead data fields.

Example 1: Regular mapping:

This is the response of the service:

{
  "person": {
    "linkedInURL": "https://www.linkedin.com/in/johndoe/",
    "job": "Accountant",
    "age": 41
  }
}

We want to save the result LinkedIn URL and job title elements of the response as separate lead fields under the Universal Connector fold.

We need to configure the following mapping:

  • enrichedPersonLinkedInURL -> person.linkedInURL
  • enrichedPersonJobTitle -> person.job

Please note: To help simplify management of multiple integrations on your platform, we recommend  you to prefix the mapped lead data fields with the name of the service you are integrating with. See 'SuperRichLinkedInURL' and 'SuperRichJobTitle' in the above example.

Example 2: Automated mapping of nested elements:

This is the response of the service:

{
  "person": {
    "linkedInURL": "https://www.linkedin.com/in/johndoe/",
    "job": "Accountant",
    "age": 41
  }
}

We want to save any elements of the person object that are provided with the response.

We need to configure the following mapping:

  • enrichedPerson -> person

The result will be saved as the following lead fields under the Universal Connector fold:

  • enrichedPerson.linkedInURL
  • enrichedPerson.job
  • enrichedPerson.age

Please note: Use automated nested mapping wisely. Trying to cascade large nested elements may result in degraded performance.

Example 3: Mapping lists (arrays):

This is the response of the service:

{
  "person": {
    "jobHistory": [
        {"title": "Software Engineer", "years": [2007, 2012]},
        {"title": "Senior Software Engineer", "years": [2012, 2022]},
    ]
  }
}

We want to save details about the first job in the list as three separate fields storing title, start year, and end year of the job.

We need to configure the following mapping:

  • enrichedPersonFirstJobTitle -> person.jobHistory.0.title
  • enrichedPersonFirstJobStartYear -> person.jobHistory.0.years.0
  • enrichedPersonFirstJobEndYear -> person.jobHistory.0.years.1

Please note: Elements numbering starts with 0.

Configuring Validation Rules

Validation Conditions

Validation conditions are used to determine when a job should pass or fail.

If this section is not configured, the job will pass if the API returns a successful HTTP status (2xx) and will fail if the API returns a non-successful HTTP status.

  • OverallOperation: Set to 'All' if all conditions should be met for the ValidationRule to apply. Set to 'Any' if at least one of the conditions should be met for the ValidationRule to apply.
  • ResponseField: The response field to apply the validation to
  • ResponseValue: Value to match ResponseField against
  • ComparisonOperator: Operator to compare the ResponseValue against ResponseField

 

Sending Enriched Lead Data to Client Integrations

Data stored for leads by the Universal Connector can be sent to client integrations using the Processr > Integration tab.

Image of the Mapping section of an integration, showing the apiresult field mapped to the Universal Connector using the system ID of the job

Mapping format

job_data[1173][core.data.0.<mapped field name>]

Example:

To map the enriched 'SuperRichLinkedInURL' field into client integration, use the following mapping:

job_data[1173][core.data.0.SuperRichLinkedInURL]

Please note: 1173 is the hardcoded system ID of the Universal Connector job. This number is the same across all campaigns on your platform, no matter how many services you integrate with using Universal Connector.

Articles in this section

See more

Related articles