Lead Enrichment API: Enrich Leads From Your Own API

What It Does

The Lead Enrichment API lets you plug in any API you already use to enrich or check leads, even one we have no built-in integration for. Every time a lead arrives, Lead Distro AI sends the fields you choose to your API, reads the values you pick out of its answer, and saves them into campaign fields before the lead is sent to your destinations. From there they behave like any other field: you can put them in a destination's POST body, filter destinations on them, and set pricing on them.

You can also give it a pass rule, for example "only pass leads the API marks as valid", and decide what happens when the API is down or the lead fails the rule.

Common Uses

• Add data your destinations ask for. Household income, credit band, property details, or a lead score from your own model, sent along with the lead.
• Route on your own data. Send high-income leads to one destination and the rest to another, using a destination filter on the enriched field.
• Price on your own data. Charge more for leads your API grades highly, using conditional pricing on the enriched field.
• Stop bad leads before they are sent. Use a pass rule with Block lead so a lead your API rejects never reaches a destination.

Before You Start

• An API endpoint that accepts a GET or POST request and answers with JSON.
• The API's login details, if it needs any: an API key (sent as a header or a query parameter), a bearer token, or a username and password.
• One sample response from the API, so you know where each value you want sits in the answer.

Step 1: Add Your API

• Go to Settings → Integrations → Lead Enrichment API and click Add enrichment API.
• Give it a Name, paste your Endpoint URL, and choose POST or GET.
• On a POST, set the Content-Type your provider accepts: application/json sends a JSON object, application/x-www-form-urlencoded sends name=value pairs. GET requests ignore this and send the fields on the query string.
• Pick how your API logs in: No auth, API key (header), API key (query param), Bearer token, or Basic, and enter the credential. Basic has separate Username and Password boxes, so if your provider wants the API key as the username, put it in Username and leave Password empty.
• Under Request mapping, add each lead field you want to send and the name your API expects for it. For example, send phone as phone_number and zip_code as zip.
• Under Run on campaigns, tick the campaigns whose leads should go through it. You can change this later with the Campaigns button. Leave it empty and it runs on nothing.

Step 2: Choose What to Keep From the Answer

Under Response mapping, add one row for each value you want. On the left, type where the value sits in your API's answer, using dots to step into nested objects. On the right, give it a short output name. You will pick this output name in Step 4.

For example, if your API answers like this:

{
  "valid": true,
  "result": {
    "income_band": "75k-100k",
    "homeowner": true
  }
}

Step 3: Set a Pass Rule and What Happens on Failure (Optional)

• Pass rule. Leave it empty if you only want to enrich leads, which is the common case. To gate leads, add conditions on the answer, for example valid equals true, and choose Match all or Match any.
• On failure. Choose what happens when your API errors, times out, or the lead fails the pass rule. Pass through sends the lead anyway (recommended while you are setting up). Block lead stops it: the lead is marked Rejected with the reason "Blocked by Enrichment API" and is not sent.
• Daily limit. Caps how many leads are sent to your API per day. When it is reached, leads keep flowing without the lookup until the next day.

Click Create to save. If you skipped Run on campaigns, click Campaigns next to it and turn it on for each campaign that should use it.

Step 4: Save the Values Into Campaign Fields

• Open your campaign and go to the Fields tab.
• Edit the field that should hold the value, or add a new one (for example income_band).
• Under Fill from your enrichment API, pick the output name from Step 2.
• Save the field. Repeat for each value you want to keep.

Step 5: Send It to Your Destinations

Add the field to your destination's POST body like any other field, for example:

{
  "phone": "{{phone}}",
  "email": "{{email}}",
  "income_band": "{{income_band}}"
}

You can also use the field in destination filters (for example, only send leads where income_band is 100k+) and in conditional pricing.

Step 6: Send a Test Lead

Use Send Test Lead on the campaign. The test lead goes through your API just like a real lead. Open the lead and check that the field is filled in, then open the destination's delivery log to see the value in the POST body your destination received.

Good to Know

• Direct Post campaigns only. On a Ping Post campaign the lead is offered to destinations right away, so the values are saved on the lead but may not be in that delivery.
• Your API adds time to each lead. Destinations get the lead after your API answers. If it has not answered within 8 seconds, the lead continues as set in On failure.
• It runs at intake only. Reprocessing a lead does not call your API again, so leads that arrived before you set this up keep an empty field.
• Your API provider bills you directly. Lead Distro AI adds no charge for the lookups.