Expansion Signals: A Worked Example

This walkthrough follows a single question — “Which companies are expanding into the United Kingdom right now, and why?” — from the market dashboard down to the individual signals behind one company’s move. Every request and response below uses the live Expansion API shapes.

The scenario

You sell to companies setting up operations in the United Kingdom. You want the freshest inbound movers, then you want to understand why one of them is expanding so you can time your outreach.

Step 1 — Find fresh inbound movers into the UK

Set tos: ["GB"] to find every company expanding into the UK, plus a freshness filter so you only see companies actively arriving.

POST /expansions/search
{
  "tos": ["GB"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

The response summarizes the market and lists the companies expanding into it:

{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] },
    "aggregate": { "total_companies_with_signals": 64, "committing_count": 22, "expanding_count": 15 },
    "top_origins": [{ "home_country_code": "CN", "company_count": 18 }],
    "top_industries": [{ "industry": "Consumer Electronics", "count": 9 }]
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [
      {
        "expansion_id": "6845525",
        "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
        "company_name": "Example Corp",
        "domain": "example.com",
        "home_country_code": "CN",
        "country_code": "GB",
        "industry": "Consumer Electronics",
        "stage": { "slug": "expanding", "expansion_score": 0.72, "scope": "entering_new_market", "direction": "advancing", "freshness": "fresh", "signal_count": 7 }
      }
    ]
  }
}

Sort by expansion_score to put the most decisive movers first. Here, a China-based company (home_country_code: "CN") is at the Expanding stage (expanding) in GB with an advancing trajectory — a strong, fresh inbound move.

Ranked list of companies expanding into a market, each showing its stage, momentum arrow, freshness, and signal count — The same ranked list, in the product — stage, momentum, and freshness at a glance, for every company matching your filters.

Step 2 — See the company’s full market map

Take the domain_search_id and list every market that company is expanding into.

POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }

{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}

The company is expanding into the UK and committing resources in Germany — useful context for prioritizing the right region.

A single company's markets plotted on a world map, colored by stage, with a stage legend and recent-activity feed — One company, every market it's moving into, plotted — the same two rows the JSON above described.

Step 3 — Understand the UK move in depth

Drill into the company-and-market detail to see the current stage, the underlying signals, known presence, and the transition timeline.

POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "country_code": "GB" }

{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "country_code": "GB" },
  "data": {
    "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
    "country_code": "GB",
    "country_name": "United Kingdom",
    "stage_rank": 3,
    "stage_name": "Expanding",
    "stage": { "slug": "expanding", "expansion_score": 0.72, "scope": "entering_new_market", "direction": "advancing", "freshness": "fresh", "signal_count": 27 }
  },
  "signals": [
    {
      "signal_type_slug": "EXEC",
      "display_label": "Hired Regional VP for UK & Ireland",
      "polarity": "expansion",
      "event_date": "2026-06-20T14:00:00.000Z"
    }
  ],
  "presence": [
    { "presence_type": "office", "address": "London, UK", "known_since": "2026-03-15T00:00:00.000Z" }
  ]
}

The Expanding stage is backed by a senior UK hire and a London office — concrete evidence, not a guess.

Step 4 — Read the individual events

For the full, paginated list of events driving the move, call the signal-event endpoint with the signal types you care about.

POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC"],
  "window_days": 90,
  "page": 1
}

{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002" },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 42, "total_pages": 2, "total_display_pages": 2, "is_timeout": false },
    "events": [
      {
        "signal_type_slug": "EXEC",
        "country_code": "GB",
        "display_label": "Hired Regional VP for UK & Ireland",
        "evidence_url": "https://www.linkedin.com/company/example-corp",
        "event_date": "2026-06-20T14:00:00.000Z"
      }
    ]
  }
}

Use total_pages to drive a “load more” control by incrementing page until it reaches total_pages.

Feed of individual expansion signals for one company in one market, each with a signal type, evidence link, and date — The events themselves, each with its evidence — a cloud footprint detected, an executive hire, a run of geo-targeted ads.

What you just did

You went from a market → a ranked list of movers → one company’s full footprint → the exact signals behind its UK expansion. That is the core loop of the Expansion API: start broad, narrow to a company, then read the evidence.

Using the Expansion API

Authentication, pagination, and your first calls.

How Expansion Signals Work

The full catalog of values used above.

Knowledge Base

Guides

Concepts

Case Studies

Expansion Signals: A Worked Example

The scenario

Step 1 — Find fresh inbound movers into the UK

Step 2 — See the company’s full market map

Step 3 — Understand the UK move in depth

Step 4 — Read the individual events

What you just did

Using the Expansion API

How Expansion Signals Work

​The scenario

​Step 1 — Find fresh inbound movers into the UK

​Step 2 — See the company’s full market map

​Step 3 — Understand the UK move in depth

​Step 4 — Read the individual events

​What you just did

Using the Expansion API

How Expansion Signals Work

The scenario

Step 1 — Find fresh inbound movers into the UK

Step 2 — See the company’s full market map

Step 3 — Understand the UK move in depth

Step 4 — Read the individual events

What you just did