New to the concepts (stages, signals, momentum, freshness)? Start with What Are Expansion Signals? — this guide assumes you know them and focuses on endpoint selection.
Pick by task
| You want to… | Call |
|---|---|
| Find companies expanding into a market (by filters or a natural-language query) | Expansion Search |
| See market-level KPIs and flows (counts per stage, top corridors) | Expansion Overview |
| Get one company’s status in a market — stage, presence, history, and the signals behind it | Company Expansion Detail |
| Get the enriched, time-windowed feed of a company’s signal events | Company Signal Events |
| Compare several companies’ expansion side by side, seeded from a target company | Compare Company Expansions |
| Get ready-to-render comparison metrics (markets, momentum, expansion score) for a company set you already have — by domain, LinkedIn URL, or id | Batch Company Expansion Summaries |
| Plot ranked company/market points on a map or heatmap | Expansion Rankings |
| Resolve filter and enum values (stages, signal types, freshness…) | Expansion Reference |
The endpoints at a glance
Expansion Search
The discovery endpoint. Filter companies by expansion stage, freshness, market, and the full company firmographic suite — or pass a natural-language
query. Paginated company list.Expansion Overview
Market-level aggregates: per-stage counts, top cross-border flows, watched-company activity. No pagination — a dashboard snapshot.
Company Expansion Detail
One company in one market: current stage, score, presence, transition history, and the supporting signals. The per-market snapshot.
Company Signal Events
The enriched, paginated feed of a company’s signal events across signal types and a date window. The activity drill-down.
Compare Company Expansions
Several companies side by side in one call, with weekly signal series and optional peer seeding. Built for comparison grids.
Batch Company Expansion Summaries
Any mix of domain_search_id, domain, or LinkedIn URL, resolved and returned with the same data as Compare plus a computed summary block — no target company, no peer seeding.
Expansion Rankings
A lightweight, score-ranked list of company/market pairs — minimal fields, no pagination — for fast map and heatmap rendering.
”Detail” vs “Signal Events” — which one?
This is the most common point of confusion, because both involve signals. The difference is snapshot vs feed:| Company Expansion Detail | Company Signal Events | |
|---|---|---|
| Scope | one company × one market | one company, across all its foreign markets |
| Markets | a single market via country_code, or the whole company at once via is_all_markets | all foreign markets by default (home market excluded); narrow to specific ones with country_codes (array) |
| Returns | stage, score, presence, history + supporting signals | enriched signal events (evidence URLs, hiring rosters, labels) |
| Time | current standing | a date window you choose (window_days — defaults to 90 — or transitioned_dates) |
| Shape | a structured snapshot object | a paginated event feed (“load more”) |
| Use when | ”What’s this company’s status in one market, and why?" | "Show me the full stream across every market driving this company’s expansion” |
”Compare” vs “Summaries” — which one?
Both return the same per-company expansion data side by side. The difference is identifiers and framing:| Compare Company Expansions | Batch Company Expansion Summaries | |
|---|---|---|
| Input | domain_search_id only | any mix of domain_search_id, domain, or linkedin_url |
| Peer seeding | optional, via seed_target | none — every company is independent |
| Computed rollup | none (compute markets/momentum/score yourself) | summary block included per company (active/new markets, momentum, expansion score, stage mix) |
| Use when | you already have resolved ids and want to seed comparable peers for one target | you’re given companies by domain or LinkedIn URL and want ready-to-render comparison metrics in one call |
A typical workflow
Discover
Call Expansion Search with your filters (or a natural-language
query) to get the companies expanding into your target market. Set is_explain_match: true for AI “why it matches” summaries.Drill into a company
Take a
domain_search_id from the results and call Company Expansion Detail for the full read in a market — stage, presence, history, and signals.See the activity feed (optional)
For the rich, windowed event stream, call Company Signal Events with the signal types and date range you care about.
Shared filters
The discovery endpoints (Expansion Search, Expansion Overview, Expansion Rankings) accept the same filter vocabulary — expansion filters (stage, momentum, freshness, scope, signal types), the directed-geography pair (froms / tos), and the full company firmographic suite (industry, technologies, employee size, revenue, saved lists). Learn the filters once in the Filters Overview; the valid values live in Expansion Reference and the How Expansion Signals Work catalog.
Using the Expansion API
Auth, your first calls, pagination, and reading scores.
Worked Example
A full market-to-signal walkthrough.