How to use LeadMCP

What the database contains

Records combine professional profile information with company details. Some contacts have no stored profile URL, so deduplicate using name and email.

The search workflow

• Define the audience and explain your assumptions.
• Inspect every relevant filter and expand the terms you will try.
• Count each plausible route. Counts are free and exact.
• Combine complementary routes into one defensible audience.
• Deliver the results, explain their breadth, and offer company website checks for a closer match.

1. Define the audience

Specify the company criteria, person criteria, intended location, requested volume, and inclusion rules. Decide how to handle ambiguous matches.

State search assumptions in one sentence. When asked who to target, recommend one audience and show alternatives with counts.

2. Inspect every relevant filter

Call get_available_columns to inspect searchable fields, descriptions, and caveats. Use get_available_values for fields with accepted lists of values.

Check current field coverage before filtering. A missing named parameter does not mean a field is unavailable; inspect where_sql options too.

Industry labels, classification codes, funding categories, and company descriptions can find different companies. Count each plausible route before deciding which to combine.

Tell the user which routes you will try and why. A software audience might combine industry categories, classification descriptions, and software-related keywords.

On the person side, compare department and seniority with title variants. Include singular, plural, and related keyword forms.

Explain difficult categories plainly. An agency audience may need several filter routes followed by website checks.

3. Count each route

Use count_contacts before retrieving rows. Submit independent counts together, then compare the audience sizes.

Aim for broad, plausible coverage. Do not narrow an Unlimited search solely to conserve plan credits.

Leave email and phone requirements out of the initial count. Apply them later and report the difference.

4. Combine complementary routes

Named parameters intersect with AND. Values within an array combine with OR. Use where_sql to combine alternative routes for the same concept.

Adding both persona and title parameters narrows to their intersection. Combine alternative role definitions inside where_sql instead.

Each additional constraint can remove contacts. If counts look unexpectedly small, relax a clause before concluding the market is small.

Keep where_sql within 4,000 characters. Shorten expressions with supported matching functions or remove weak routes.

Inspect sample company names before reporting the total. Results are grouped by company, so a large count may be concentrated at one employer.

Company requirements
AND (industry route OR classification route OR description route)
AND (role route OR title route)

5. Check company websites

Deliver the initial count and explain that catalog filters produce a broad audience. Offer website reviews to apply the user's precise inclusion rules.

Choosing between filters

Count plausible alternatives instead of assuming one classification covers the market. Companies appear differently across independent industry systems.

Search description fields using plain-language phrases. Users do not need to supply classification codes.

If a plausible phrase returns nothing, inspect ten known matching records and read the stored wording before trying again.

Combine alternative role definitions with OR

A job title and a derived function can describe the same audience differently. Requiring both excludes contacts found by only one route.

Use where_sql to combine seniority labels with title patterns, such as a leadership level or a title containing 'head of'.

Keywords across text fields

Search several company text fields. For people, inspect descriptions, headlines, job descriptions, and job titles, then expand to other relevant text fields.

Choose the right location family

Person location, company headquarters, company offices, and job location are separate concepts. Choose the family the user means and state it.

Combining location families intersects them and can sharply reduce the audience.

Technographics

Technology fields help identify ecommerce companies and businesses using products relevant to a service, such as HubSpot optimisation.

Apply contactability last

Many records lack an email or phone. Size the audience first, then apply contactability requirements and report both counts.

Beyond search

For named accounts, combine domains with role filters. lookup_decision_makers returns Director-level and more senior contacts with verified emails.

Use search_contacts for other roles. Colleague lookup tools retrieve contacts with valid emails at a company.

Match names and companies with leadmcp_enrich_person_batch. Batch enrichment tools also accept professional profile URLs.

Other batch tools accept email addresses as input. Use create_csv_enrichment_upload_link for CSV enrichment.

Enrichment matches people to database records.

Start with the user's existing file

A file of people needing more fields is an enrichment task. A file of companies needing more people is a domain-filtered search.

A list of CEOs needing marketing leaders beside them requires search. Enrichment alone cannot find the additional people.

Add people to a company list

Large domain arrays can fail with 502 errors. Smaller batches keep requests manageable.

Search and CSV exports may label email differently: Email and Work Email. Deduplicate by name and email because profile URLs can differ.

• Read the existing file without requesting a template. Find domains or derive them from website or email columns, preserving other columns.
• Send domain arrays together instead of making one request per row. Batch large lists at 5,000 domains to avoid oversized requests.
• Count multiple role definitions, including persona, function with seniority, and title patterns. Present the counts before choosing the broader defensible route.
• Combine routes with where_sql and request company domains so results can be joined back to the input.
• Join locally by domain and write a new file. Preserve every original row, including companies with no matches.
• Review actual titles before delivery. Derived marketing fields can include art or product directors who do not match a marketing executive request.
• Identify domains with no matches and offer broader titles or relaxed email requirements.

Common query mistakes

• A zero count describes the filter and value, not necessarily the market. Verify coverage and accepted values, such as United States instead of US.
• Unknown columns produce errors; valid empty columns can return zero. Inspect the catalog before interpreting the result.
• Short substrings can match unintended words. Pet can match Petroleum or Carpet; Sales can match Salesforce.
• Seniority, persona, and department are derived labels. Validate them against job titles.
• For exports above 50,000 rows, use exhaustive, nonoverlapping partitions and confirm their counts sum to the total. Export offsets are API-only.
• Download links expire. Retrieve the file while the link remains valid.
• Decision-maker lookups target Director-level and above with verified emails. Use search for managers and specialist roles.
• Long retrievals may stall in chat clients. Explain that constraint before starting and consider a coding client.
• Plan credits cover search, export, and enrichment. Paid scrapes use a separate prepaid wallet; insufficient_wallet_cash refers to that balance.
• Unlimited plans report a null credit balance. Null means unlimited access, not zero credits.

Tools by task

The field catalog is free to inspect. Check it before claiming a field cannot be filtered.

If observed API behavior differs from this guide, reproduce the difference at a meaningful scale. Follow the API response and explain the discrepancy.