Concepts
Waterfall templates
Every built-in waterfall template, its inputs, outputs, capabilities, speed, run mode and list-price cost, generated from the template library.
Before you start
A template is a prebuilt waterfall. Each step names a capability rather
than a vendor, so the router chooses the vendors unless you pin them. Browse them with the
explanations of each step at /waterfalls/templates. This page is
generated from the same library as the API (GET /v1/waterfalls/templates).
Status
| Status | Meaning |
|---|---|
| Ready | Routed vendors can run every stage today on your own vendor keys. availability.vendor_keys lists the keys that unlock it; one key per stage is enough. |
| Sandbox | Runs on the sandbox-* vendors with a grid_test_ key, no vendor key needed. Sandbox calls are priced like real ones and draw on your credit. Use the scenario input to script hits, misses and timeouts. |
| Preview | Vendors document the capability publicly, but none is routed yet. You can read the steps; creating one returns 422 validation_failed. |
Costs are list prices per run from the catalog: the minimum is the cheapest vendor per stage and the
maximum is every eligible vendor trying, capped by the template's max_cost_micro. Conditional
stages count 0 toward the minimum. With your own keys, GridRouter charges $0 and the vendor bills its
own rate.
Contacts
| Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run |
|---|---|---|---|---|---|---|
work-email Work email finder: Name + company domain → a verified work email. | Ready | first_name, last_name, domain | email, confidence, status, mx_provider | people.email.find → email.verify | Balanced: one at a time, hedged · Sync (one request) | $0.012–$0.078 |
email-from-profile Email from a profile URL: B2B profile URL → name and employer → verified work email. | Ready | profile_url | full_name, title, company_name, company_website, email, confidence, status, mx_provider | people.enrich → people.email.find → email.verify | Balanced: one at a time, hedged · Sync (one request) | $0.012–$0.090 |
mobile-number Mobile number finder: Profile URL or email → a mobile / direct dial. | Ready | profile_url?, work_email?, personal_email? (Send at least one of profile_url, work_email or personal_email.) | mobile_number | phone.mobile.find | Thorough: cheapest first · Sync (one request) | $0.060 |
email-verification Email verification (consensus): One address → a verdict that several verifiers agree on. | Ready | email | status, mx_provider | email.verify | Fast: vendors race · Batch (lists) | $0.016 |
catch-all-resolution Catch-all resolution: Keep verifying until a verifier gives a definitive valid or invalid. | Ready | email | status, mx_provider | email.verify | Thorough: cheapest first · Batch (lists) | $0.0035–$0.016 |
reverse-email-lookup Reverse email lookup: Email → the person behind it: profile, title, employer. | Ready | email | profile_url, full_name, first_name, last_name, title, company_name, company_website, location, country, work_experience | people.profile.find → people.enrich | Balanced: one at a time, hedged · Sync (one request) | $0.120–$0.132 |
phone-validation Phone validation: Phone number → valid, line type and carrier. | Preview | phone | valid, line_type, carrier_name, country_code, ported | phone.lookup | Fast: vendors race · Batch (lists) | — |
dnc-check Do-not-call check: Phone number → line type, then DNC and litigator lists before dialing. | Preview | phone | line_type, listed, lists, litigator, reassigned | phone.lookup → compliance.dnc.check | Balanced: one at a time, hedged · Batch (lists) | — |
sandbox-work-email Work email finder (sandbox): Swift, then Deep, then Sure on the sandbox vendors: runs on a test key, no vendor key needed. | Sandbox | first_name, last_name, domain, scenario? | email, confidence | people.email.find | Balanced: one at a time, hedged · Sync (one request) | $0.004–$0.028 |
sandbox-mobile-number Mobile number finder (sandbox): Cheapest-first mobile waterfall over the sandbox vendors. | Sandbox | profile_url?, work_email?, scenario? (Send profile_url or work_email.) | mobile_number | phone.mobile.find | Thorough: cheapest first · Sync (one request) | $0.015–$0.090 |
People
| Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run |
|---|---|---|---|---|---|---|
person-enrichment Person enrichment: Profile URL or email → title, seniority, employer and history. | Ready | profile_url?, email? (Send profile_url, or email when you don't have it.) | profile_url, full_name, first_name, last_name, title, company_name, company_website, location, country, work_experience | people.profile.find → people.enrich | Balanced: one at a time, hedged · Sync (one request) | $0.012–$0.132 |
job-change-detection Job change detection: Profile URL + the company you know them at → did they move, and where. | Ready | profile_url, domain? | job_change_detected, current_company, expected_company, summary, status | signals.job_change | Balanced: one at a time, hedged · Batch (lists) | $0.036 |
decision-makers Decision maker by role: Company domain + job title → the person who holds it. | Ready | domain, job_title | name, first_name, last_name, profile_url, company_name | people.role.find | Balanced: one at a time, hedged · Sync (one request) | $0.024 |
employee-list Employee list: Company domain → people who work there, billed per row. | Ready | domain, limit? | people, total_count | people.search | Balanced: one at a time, hedged · Sync (one request) | $0.006–$0.036 |
social-profiles Social profiles: Email or name → the person's social profiles and handles. | Preview | email | profile_url, platform, handle, followers | social.profile.find | Balanced: one at a time, hedged · Sync (one request) | — |
Company
| Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run |
|---|---|---|---|---|---|---|
company-enrichment Company enrichment: Domain → firmographics: headcount, industry, revenue, funding, stack. | Ready | domain | name, employees, industry, website, description, founded_year, revenue, total_funding, technologies | company.enrich | Balanced: one at a time, hedged · Sync (one request) | $0.012 |
technographics Technographics: Domain → the technologies a company runs. | Preview | domain | technologies, technology_category, last_detected | company.technographics | Fast: vendors race · Sync (one request) | — |
funding-financials Funding and financials: Domain → funding rounds, investors, revenue and filings. | Preview | domain | total_funding_usd, last_round_type, last_round_date, investors, revenue_usd, fiscal_year | company.funding → company.financials | Balanced: one at a time, hedged · Sync (one request) | — |
hiring-signals Hiring signals: Domain → open roles by department and hiring velocity. | Preview | domain | open_roles, roles_by_department, growth_rate, job_title | signals.hiring → jobs.company_postings | Balanced: one at a time, hedged · Sync (one request) | — |
intent-signals Intent surge by topic: Topic → accounts researching it more than usual this week. | Preview | topic | company_domain, score, surging, week | signals.intent | Balanced: one at a time, hedged · Async (poll or webhook) | — |
news-monitoring Company news: Domain or name → recent news mentions and events. | Preview | domain | title, url, published_at, source_name, summary | news.company_mentions | Balanced: one at a time, hedged · Sync (one request) | — |
reviews-reputation Reviews and reputation: Business domain or place → average rating, review count and recent reviews. | Preview | domain?, place_id? (Send domain or place_id.) | average_rating, review_count, text, platform | reviews.business | Balanced: one at a time, hedged · Sync (one request) | — |
kyb-verification KYB and sanctions screening: Company → registry record, officers and a sanctions/PEP screen. | Preview | name, jurisdiction? | registration_number, status, incorporation_date, registered_address, role, match_count, lists | registry.company_lookup → registry.officers → compliance.sanctions.screen | Thorough: cheapest first · Async (poll or webhook) | — |
local-business-lookup Local business lookup: Business name + area → address, phone, website, rating and hours. | Preview | query, near | name, address, phone, website, rating, opening_hours | places.search → places.details | Balanced: one at a time, hedged · Sync (one request) | — |
ads-intelligence Ads intelligence: Advertiser → what they run on Meta, Google and LinkedIn. | Preview | domain, query? | advertiser_name, headline, landing_url, first_seen, platform | ads.meta.search → ads.google.search → ads.linkedin.search | Fast: vendors race · Async (poll or webhook) | — |
seo-presence SEO and SERP presence: Domain → traffic, backlinks and where it ranks for a keyword. | Preview | domain, query? | visits, referring_domains, authority, position | seo.traffic → seo.backlinks → serp.google.search | Balanced: one at a time, hedged · Async (poll or webhook) | — |
ip-to-company IP to company: Visitor IP → the company behind it, with firmographics. | Preview | ip | company_name, company_domain, is_isp, confidence, employees, industry | ip.company_lookup → company.enrich | Fast: vendors race · Sync (one request) | — |
sandbox-company-enrichment Company enrichment (sandbox): Race all three sandbox vendors and merge field by field. | Sandbox | domain, scenario? | name, employees, industry, technologies | company.enrich | Fast: vendors race · Sync (one request) | $0.018 |
Composite
| Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run |
|---|---|---|---|---|---|---|
full-lead-enrichment Full lead enrichment: Name + domain → verified email, profile, title, mobile and company. | Ready | first_name, last_name, domain, profile_url? | email, confidence, status, mx_provider, profile_url, full_name, title, company_name, company_website, location, country, work_experience, mobile_number, name, employees, industry, website, description, founded_year, revenue, total_funding, technologies | people.email.find → email.verify → people.profile.find → people.enrich → phone.mobile.find → company.enrich | Balanced: one at a time, hedged · Async (poll or webhook) | $0.084–$0.282 |
account-research-brief Account research brief: Domain → firmographics, tech stack, hiring and news in one record. | Preview | domain | name, employees, industry, website, technologies, open_roles, title | company.enrich → company.technographics → signals.hiring → news.company_mentions | Balanced: one at a time, hedged · Async (poll or webhook) | — |
inbound-lead-enrichment Inbound lead enrichment: Form fill (email) → verified, with the person and company for routing. | Ready | email, domain? | status, mx_provider, profile_url, full_name, first_name, last_name, title, company_name, company_website, location, country, work_experience, name, employees, industry, website, description, founded_year, revenue, total_funding, technologies | email.verify → people.profile.find → people.enrich → company.enrich | Fast: vendors race · Sync (one request) | $0.120–$0.172 |
crm-hygiene CRM hygiene: CRM record → re-verified email, job change check and refreshed company. | Ready | email?, profile_url?, domain? (Send whichever of email, profile_url and domain the record has.) | status, mx_provider, job_change_detected, current_company, name, employees, industry, website | email.verify → signals.job_change → company.enrich | Thorough: cheapest first · Batch (lists) | $0–$0.064 |
decision-maker-emails Decision maker + verified email: Domain + job title → the role holder and their verified work email. | Ready | domain, job_title | name, profile_url, company_name, email, confidence, status, mx_provider | people.role.find → people.email.find → email.verify | Balanced: one at a time, hedged · Batch (lists) | $0.024–$0.102 |
sandbox-email-then-mobile Email, then mobile (sandbox): Two sandbox stages: find the work email, then feed it to a mobile waterfall. | Sandbox | first_name, last_name, domain, scenario? | email, mobile_number | people.email.find → phone.mobile.find | Balanced: one at a time, hedged · Sync (one request) | $0.004–$0.088 |
On the roadmap
These need a capability that no integrated vendor exposes through a public API yet, or an engine feature. They ship when one does.
| Template | Category | Waiting on |
|---|---|---|
personal-email Personal email finder: Profile URL → a personal address. | contacts | No catalog capability returns personal addresses, and no listed vendor documents a public API for it. |
company-domain-lookup Company name to domain: Company name → its website domain. | company | The catalog's company search filters by industry and size, not by name; no name-to-domain capability is defined yet. |
lookalike-companies Lookalike companies: Seed domain → companies like it. | company | No lookalike capability in the catalog; only one listed vendor documents lookalike search publicly, below the bar for a new capability. |
competitors Competitors: Domain → the company's direct competitors. | company | No competitor capability; listed vendors offer it behind sales-gated APIs or only as SEO keyword overlap. |
company-profile-firmographics Company profile URL → firmographics: B2B company page URL → firmographics. | company | Company enrichment takes a domain; no catalog capability takes a company profile URL as input yet. |
ecommerce-store-data E-commerce store data: Store domain → platform, apps, products and estimated sales. | company | commerce.store_lookup is in the catalog, but its one listed vendor has no public API docs. |
ai-lead-scoring AI lead scoring: Enriched lead → a fit score with reasons. | composite | A stage input maps one field, so a model step can't be given the whole enriched record as its prompt, and no model endpoint is routed yet. Score the Inbound lead enrichment output in your CRM for now. |
ai-account-brief AI-written account brief: Account research record → a five-line brief written by a model. | composite | Same gap as AI lead scoring: composing a prompt from several stages needs a prompt-template step the engine doesn't have yet. |
icp-list-building ICP list building: ICP filters → companies → people → verified emails. | composite | Company search is not routed yet and a run returns one record (no fan-out). Today: batch-run Decision maker + verified email over your target domains. |
crm-dedupe CRM dedupe and normalize: Merge duplicate records and normalize names, titles and domains. | composite | Dedupe works across rows and no capability does it; CRM hygiene covers the per-record re-verification. |
Use one
| Surface | Call |
|---|---|
| API | POST /v1/waterfalls/from-template {"template":"work-email","pins":{"email":["hunter"]},"speed":"balanced","max_cost_micro":100000} |
| MCP | waterfall_templates, waterfall_template_get, waterfall_create_from_template, waterfall_estimate, waterfall_run, waterfall_status |
| SDK | grid.waterfalls.templates.list(), grid.waterfalls.fromTemplate("work-email"), grid.waterfalls.run(id, input) |
| Dashboard | Waterfalls → Templates → Use template opens it in the builder with its sample input in the test runner |
pins maps a stage id to the vendor slugs tried first. The router still falls back to other vendors
unless pins_only is true. speed is fast (race), balanced (one at a time, hedged) or
thorough (cheapest first, 90 s deadline). The new waterfall is published as 1.0.0 unless you pass
"publish": false.