Skip to main content
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/lookup
{
  "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.

​
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.

​
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.

​
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.