Enriching Leads with the Lookup using Table Step

Feature Snapshot

Summary:
The Lookup using Table step adds data from one of your tables to each lead while it moves through a flow. The step matches one or more lead fields against the table’s key columns. When it finds a matching row, it copies the columns you choose onto the lead. Later steps, such as filters, deliveries and pricing, can use that data.

Key Benefits:

• Adds your own reference data to leads in real time, with no external database or service
• Replaces long chains of rules that map one value to another
• Lets you decide what happens when no row matches: continue or stop the flow
• Picks up table updates automatically, with no flow edits

Typical Use Cases:

• Routing leads by territory (postal code → buyer or office)
• Adding campaign data from a tracking phone number
• Mapping codes to descriptions (state → region, sub ID → landing page)

How It Works

The step reads from a table you create under Assets → Tables. See Creating and Managing Tables to set one up.

For each lead, the step:

1. Reads the lead fields you mapped to the table’s key columns, for example Postal Code → zip_code.
2. Finds the row whose key columns match those values. If the table has more than one key column, the lead must match all of them.
3. Copies the columns you chose from that row onto the lead. Each one is stored as <step>.query.<column>, for example lookup_table.query.region.
4. Applies your Match Handling settings if no row matches, or if the lookup times out or errors: the lead either continues with the fields left empty, or the flow stops.

Example

This table uses zip_code as its key column and returns region and office:

zip_code,region,office
78701,Central,Austin
10001,Northeast,New York
94105,West,San Francisco

The step maps the lead field Postal Code to zip_code and returns both columns. A lead with Postal Code 10001 gets these fields:

A later filter or delivery step can then use lookup_table.query.office to send the lead to the right office. A lead with Postal Code 60601 matches no row, so the step follows your If no results are found setting.

Matching rules

• Matching is exact and case-sensitive. For example, TX does not match tx.
• Spaces at the start and end of a value are ignored.
• The lead needs a value for every mapped key column to get a result.

Step-by-Step Instructions

Before you start

Create the table under Assets → Tables, with your key column(s) and the columns you want to return. See Creating and Managing Tables.

Add the step to a flow

1. Open your flow.
2. Select Add to Flow. Under Built-in steps, select Lookup using Table.
   Expected Result: A step named Lookup Table - Query is added to the flow’s Steps list, and its settings panel opens.
3. Make sure the step runs before any step that uses the data it returns.

Choose the table and map the key columns

1. In Table and Lookup Field, open the Table list and select your table. You can search by name.
   Expected Result: The row count, column count and last-updated date appear below the list. Use them to confirm you picked the right table.
2. In the grid, choose a lead Field for each table column. The table column on the right is fixed: there is one row for each key column.
   • Some fields have a selector next to them. Raw compares the whole field value. The other options compare one part of it, for example Zip for the 5-digit part of a postal code. Pick the option that matches how the keys are stored in your table.
3. Map a field to every key column. If a key column is left unmapped, the lookup can’t return a result. The lead must match all of the key columns to return a result.

Choose the data to return

1. In Data to Return, select a column from the list. Only the columns the table returns are listed. If you don’t select any column, every column the table returns is added to the lead.
   Expected Result: The lead field the value is stored in appears next to it, for example price → lookup_table.query.price.
2. Select Add Column to return another column. Select the trash icon to remove one.

Column names are stored in lower case, with spaces replaced by underscores. A column named Zip Code becomes lookup_table.query.zip_code.

Set the match handling

Choose what happens in each case:

• Continue and leave fields empty: the lead moves on to the next step without the table fields. Use this when the data is helpful but not required.
• • Stop the flow: the lead doesn’t go on to later steps. Its outcome is failure, and the reason (for example, No match was found.) is sent back to the source. Use this when the lead has no value without the table data.

Note: Match Handling only applies when the step looks up a value. If a mapped field is empty on a lead (for example, the lead has no postal code), there’s nothing to look up, so the step is skipped. The lead continues to the next step without the table data, even when Stop the flow is selected. To stop these leads, add a filter before this step that rejects leads with an empty value in the mapped field.

Save the flow

Select Save. The step starts running on the next lead the flow receives.

Validation & Monitoring

• Test the setup: Select Test Flow, or submit test leads, with values that are in the table and values that aren’t. Confirm that matching leads get the returned fields and that non-matching leads follow your Match Handling settings.
• Check the lead: Open the lead in the Events tab and look for the lookup_table.query.<column> fields.
• Check table usage: On the table’s detail page, Last queried and Flows show that the flow is using it.

Best Practices

• Place the step before every step that uses its data, such as filters, deliveries and pricing.
• Return only the columns later steps need.
• Use Continue and leave fields empty while you test, so a missing match doesn’t block leads. Switch to Stop the flow only when the lead has no value without the data.
• Store keys in the same format your source sends them, including letter case and leading zeros (e.g. 02134, not 2134).
• Check the selector next to each mapped field (Raw or a part, such as Zip) so the compared value matches how your keys are stored.
• To change the data, update the table instead of editing the flow.

Frequently Asked Questions (FAQ)

Where is the returned data stored on the lead?

In fields named <step>.query.<column>, for example lookup_table.query.price. The Data to Return section shows the exact field name for each column.

Can I match on more than one field?

Yes. If the table has more than one key column, map a lead field to each one. The lead must match all of them to return a result. You can’t skip a key column; to match on fewer, use a table with fewer key columns. See Creating and Managing Tables.

What happens if no row matches?

The step follows your If no results are found setting: the lead continues with the fields left empty, or the lead stops with the reason No match was found.

Do I need to change the flow when I update the table?

No. The step always reads the table’s current data.

Can I use the same table in more than one flow?

Yes. Add a Lookup using Table step to each flow and select the same table.

Can I use a table to set the lead’s purchase price?

Yes. Use the Table option in the source’s Lead purchase price settings. See Setting the Lead Purchase Price from a Table.

Glossary

Related Articles

• Creating and Managing Tables
• Setting the Lead Purchase Price from a Table
• Pricing
• Real-Time Bidding

• lookup-step-add-to-flow.png70 KB
• lookup-step-table-and-field.png70 KB
• lookup-step-data-to-return.png80 KB
• lookup-step-match-handling.png80 KB