> ## Documentation Index > Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt > Use this file to discover all available pages before exploring further. # Expansion Search > Find companies expanding into one or more markets using firmographic and signal filters or a plain-language query, with optional AI match explanations grounded in each company's real signals. ## OpenAPI ````yaml en-openapi POST /expansions/search openapi: 3.0.0 info: description: >- The Pubrio API delivers market expansion intelligence — real-time signals that flag when a company enters a new market — alongside the company and people data beneath them. Search, look up, and enrich accounts and contacts, and subscribe to typed, dated movement signals across 200+ markets. version: 1.0.0 title: Pubrio OpenAPI termsOfService: https://pubrio.com/en/terms-of-service contact: email: king.lai@pubrio.com name: King Lai url: https://pubrio.com/en/get-in-touch license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.pubrio.com security: - pubrio_api_key: [] tags: - name: Profile description: Workspace profile information and usage statistics - name: Enrichment description: Enrich people and company records with detailed B2B data - name: Lookalike description: Find companies similar to a given company - name: Search description: Search for people, companies, jobs, news, and advertisements with filters - name: Lookup description: >- Look up detailed information for specific people, companies, jobs, news, advertisements, and technologies - name: LinkedIn description: Look up people and company data via LinkedIn profile URLs - name: Redeem description: Redeem credits to unlock people contact details (single and batch) - name: Channels description: Manage outreach channel templates (create, update, delete, list) - name: Monitor description: Create and manage data monitors with webhooks, statistics, and processing - name: Filters description: >- Retrieve available filter values for search parameters (technologies, locations, verticals, etc.) - name: API Keys description: List and inspect API request logs and usage analytics for API keys - name: Insights description: Aggregated signal insights for companies (jobs, news, advertisements). - name: Export description: Bulk data exports (credit-gated). - name: Expansion description: >- Company market-expansion intelligence: signals, stages, markets, and exports. externalDocs: description: >- The Pubrio API is used to search, preview and enrich Contacts and Accounts. Pubrio database provides extensive B2B contacts and sales intelligence data. url: https://docs.pubrio.com paths: /expansions/search: post: tags: - Expansion summary: Expansion Search description: >- Find companies expanding into one or more markets using firmographic and signal filters or a plain-language query, with optional AI match explanations grounded in each company's real signals. operationId: expansions_search requestBody: required: true content: application/json: schema: type: object properties: froms: $ref: '#/components/schemas/expansion_froms' tos: $ref: '#/components/schemas/expansion_tos' exclude_froms: $ref: '#/components/schemas/expansion_exclude_froms' exclude_tos: $ref: '#/components/schemas/expansion_exclude_tos' stages: $ref: '#/components/schemas/expansion_stages' momentum: $ref: '#/components/schemas/expansion_momentum' freshness: $ref: '#/components/schemas/expansion_freshness' scopes: $ref: '#/components/schemas/expansion_scopes' ahead_of_pace: type: boolean example: false description: >- Limit to pairs moving faster than the typical pace for that market. signal_types: $ref: '#/components/schemas/expansion_signal_type_slugs' signal_strengths: $ref: '#/components/schemas/signal_strengths' min_signal_count: type: integer example: 3 description: >- Minimum number of expansion signals a company must have in the window — "very active / heavy footprint". only_contraction: $ref: '#/components/schemas/only_contraction' min_markets: type: integer example: 3 description: >- Minimum number of new markets a company must have entered in the window. verticals: $ref: '#/components/schemas/verticals' vertical_categories: $ref: '#/components/schemas/vertical_categories' vertical_sub_categories: $ref: '#/components/schemas/vertical_sub_categories' technologies: $ref: '#/components/schemas/technologies' employees: $ref: '#/components/schemas/employees' revenues: $ref: '#/components/schemas/revenues' founded_dates: $ref: '#/components/schemas/founded_dates' keywords: $ref: '#/components/schemas/keywords' companies: $ref: '#/components/schemas/expansion_companies' job_locations: $ref: '#/components/schemas/locations' job_exclude_locations: $ref: '#/components/schemas/job_exclude_locations' job_posted_dates: $ref: '#/components/schemas/posted_dates' job_titles: $ref: '#/components/schemas/people_titles' advertisement_target_locations: $ref: '#/components/schemas/advertisement_target_locations' advertisement_exclude_target_locations: $ref: '#/components/schemas/advertisement_exclude_target_locations' advertisement_search_terms: $ref: '#/components/schemas/advertisement_search_terms' advertisement_start_dates: $ref: '#/components/schemas/advertisement_start_dates' advertisement_end_dates: $ref: '#/components/schemas/advertisement_end_dates' news_categories: $ref: '#/components/schemas/news_categories' news_published_dates: $ref: '#/components/schemas/published_dates' transitioned_dates: type: array items: type: string format: date example: - '2026-04-01' - '2026-06-29' description: >- ISO date range for the timeline window. Defaults to the last 90 days. A natural-language `query` may also set this from calendar phrases ("this year", "last year", "Q2 2026"). window_days: $ref: '#/components/schemas/window_days' query: type: string example: fintech companies expanding into the UK description: >- Natural-language query that Pubrio interprets into expansion + company filters. is_explain_match: type: boolean example: true description: >- Include AI-generated explanations of why each company matches the search, grounded in the company's real signals. Best paired with a natural-language query. The number of signals cited and the batch size both scale with `per_page`; high-volume sources (job postings, ad campaigns) are summarized as a window-scoped count (e.g. "12 job postings") rather than listed individually. sort_by: $ref: '#/components/schemas/expansion_sort_by' page: $ref: '#/components/schemas/page' per_page: $ref: '#/components/schemas/per_page' profile_id: $ref: '#/components/schemas/profile_id' responses: '200': description: >- Paginated list of companies expanding in the market(s). `filters` echoes the applied (or natural-language-interpreted) criteria; each company includes a `match_summary` when `is_explain_match` is true. content: application/json: schema: type: object properties: metadata: type: object description: >- Search metadata: the filters actually applied, plus the market rollup (aggregate, geo scope, top origins/destinations/industries, timeline) when metadata is requested. properties: filters: type: object description: >- Filters actually applied (echoes an interpreted natural-language query when `query` was used). relaxed_filters: type: array description: >- Soft filters auto-dropped when a natural-language query matched nothing; null otherwise. items: type: string aggregate: type: object description: >- Market-level rollup. Present when metadata is requested. country_code: type: string country_codes: type: array items: type: string direction: type: string is_global: type: boolean is_multi: type: boolean transitioned_dates: type: array items: type: string top_origins: type: array items: type: object top_destinations: type: array items: type: object top_industries: type: array items: type: object timeline: type: array items: type: object data: type: object description: >- Result container (standard search envelope): the company list plus pagination. properties: pagination: type: object companies: type: array description: >- The company list. Each item carries a nested `stage`; `match_summary` is included when `is_explain_match` is true. items: type: object example: metadata: filters: tos: - GB verticals: - Financial Services data: pagination: page: 1 per_page: 25 total_entries: 87 total_pages: 4 total_display_pages: 4 is_timeout: false companies: - expansion_id: '6845525' domain_search_id: 550e8400-e29b-41d4-a716-446655440002 country_code: GB target_country_code: GB domain: example.com company_name: Example Corp home_country_code: CN industry: Consumer Electronics founded_year: 2015 employees_count: 320 stage: slug: expanding expansion_score: 0.72 scope: entering_new_market direction: advancing freshness: fresh signal_count: 27 presence: level: detected local_people_count: 12 has_known_office: true matched_rule: people read: code: ok components: schemas: expansion_froms: type: array items: type: string example: - US - GB description: >- Origin markets (ISO 3166-1 alpha-2). Where a company is expanding FROM — its home / HQ countries. Use alone to find companies growing out of these markets; combine with `tos` for a specific from→to corridor. expansion_tos: type: array items: type: string example: - US - GB description: >- Target markets (ISO 3166-1 alpha-2). Where a company is expanding TO. Use alone to find every company entering these markets; combine with `froms` for a specific from→to corridor. expansion_exclude_froms: type: array items: type: string example: - US - GB description: Origin markets to exclude (ISO 3166-1 alpha-2). expansion_exclude_tos: type: array items: type: string example: - US - GB description: Target markets to exclude (ISO 3166-1 alpha-2). expansion_stages: type: array items: type: string enum: - exploring - committing - expanding - scaling - established example: - committing - expanding description: >- Filter to one or more expansion stages. See the Expansion Signals knowledge base for stage definitions. expansion_momentum: type: array items: type: string enum: - accelerating - advancing - steady - pulling_back example: - accelerating - advancing description: >- Filter by expansion momentum (trajectory through the stages): `accelerating` (advancing with a mode change), `advancing`, `steady`, or `pulling_back` (retreating or contracting). expansion_freshness: type: array items: type: string enum: - fresh - cooling - stale - cold example: - fresh - cooling description: >- Filter by evidence recency: fresh (~30d), cooling (~30-60d), stale (~60-90d), cold (>90d). expansion_scopes: type: array items: type: string enum: - entering_new_market - expanding_within_presence - established_only example: - entering_new_market description: Filter by market-entry scope. expansion_signal_type_slugs: type: array items: type: string enum: - AD - NEWS - INFRA - PARTNER - EVENT_PLUS - EXEC - OFFICE - HIRE - SCALE - PRODUCT example: - EXEC - HIRE description: Filter to specific signal types. signal_strengths: type: array items: type: string enum: - low - medium - high - very_high example: - high - very_high description: Filter by signal strength buckets. only_contraction: type: boolean example: false description: >- When true, return only contraction-flagged expansions (companies scaling back). verticals: type: array items: type: integer description: >- A list of `vertical_id` used to search for companies in a specific vertical or industry. To find the ID, call the `vertical` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["AI"]`. vertical_categories: type: array items: type: integer description: >- A list of `vertical_category_id` used to search for companies in a specific vertical category. To find the ID, call the `vertical category` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["Information Technology"]`. vertical_sub_categories: type: array items: type: integer description: >- A list of `vertical_sub_category_id` used to search for companies in a specific vertical sub-category. To find the ID, call the `vertical sub category` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["Software"]`. technologies: type: array items: type: integer description: >- A list of `tag_id` used to search for specific technologies used by companies. To find the ID, call the `technology` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["Shopify"]`. employees: type: array items: type: array items: type: string example: - - 1 - 10 - - 11 - 20 - - 10001 description: >- The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results. Check out `company size` endpoints under the Filters tab for more information. revenues: type: array items: type: integer example: - 0 - 100000 description: Minimum and maximum range of company revenue. founded_dates: type: array items: type: integer example: - 2018 - 2024 description: >- Years of company founded range. The maximum value founded is the current year. keywords: type: array items: type: string example: - ecommerce - ai - fintech description: >- A list of keywords to filter companies by relevance, specialties, or descriptions. expansion_companies: type: array items: type: string example: - stripe.com - https://www.linkedin.com/company/airbnb - 550e8400-e29b-41d4-a716-446655440000 description: >- Scope to specific companies by any mix of `domain_search_id`, company domain, or a company social media profile URL. Domains and URLs resolve to their best-ranked company. locations: type: array items: type: string example: - US - SG - CN description: >- ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out `location` endpoints under the Filters tab for more information. job_exclude_locations: $ref: '#/components/schemas/exclude_locations' description: Geographic locations to exclude from job posting results. posted_dates: type: array items: type: string example: - '2025-01-01' - '2025-01-10' description: Date range of the posted date. The maximum value is the current day. people_titles: type: array items: type: string example: - sales manager - marketing manager description: |- Job titles associated with the individuals you aim to locate. The results will also encompass job titles that include similar terminology, even if they do not match exactly. For instance, searching for `software engineer` may yield results for individuals with the title `senior software engineer`. advertisement_target_locations: $ref: '#/components/schemas/target_locations' description: Target geographic locations for advertisements. advertisement_exclude_target_locations: $ref: '#/components/schemas/exclude_target_locations' description: Geographic locations to exclude from advertisement targeting. advertisement_search_terms: type: array items: type: string example: - asus description: Keywords used to search within advertisement content or titles. advertisement_start_dates: type: array items: type: string format: date example: - '2025-12-25' - '2025-12-25' description: Start date range for advertisement filtering. advertisement_end_dates: type: array items: type: string format: date example: - '2025-12-25' - '2025-12-25' description: End date range for advertisement filtering. news_categories: type: array items: type: string example: - launches description: >- List of `category slugs` for searching for specific news categories. To find a slug, call the `news categories` endpoint under the Filters tab. published_dates: type: array items: type: string example: - '2025-01-01' - '2025-01-10' description: Date range of the published date. The maximum value is the current day. window_days: type: integer example: 90 description: >- Optional. Size of the rolling window in days. Used when an explicit `transitioned_dates` range is not supplied; if both are omitted, a default window is used. expansion_sort_by: type: string enum: - expansion_score - signal_count - company_ranking example: expansion_score description: >- Result ordering. Omit for the default (most recently transitioned first). `expansion_score` — highest expansion score first. `signal_count` — most signals in the pair first. `company_ranking` — Pubrio's overall company ranking (lower is more prominent), ascending. page: type: integer example: 1 description: The page number of the Pubrio data that you want to retrieve. per_page: type: integer example: 25 description: >- The number of search results that should be returned for each page. Limited the number of results per page improves the endpoint's performance. profile_id: type: integer description: >- Optional. An identifier for the user profile (workspace) making the request. This is no longer required as the API key already includes your workspace information. If provided, it helps in associating the lookup with a specific user, allowing for data retrieval and credit tracking. Check out `user details` endpoints under the Profile tab for more information. exclude_locations: type: array items: type: string example: - CN - US - RU - CA description: >- ISO 3166-1 alpha-2 (cca2) is used to filter out locations that does not need to be returned. Check out `location` endpoints under the Filters tab for more information. target_locations: type: array items: type: string example: - TW - AE - 'NO' description: >- Filter advertisements to include those targeting specific locations by country code. Use this to find ads that are being shown in specific countries. Combines with `filter_conditions` using OR operator - the advertisement must target at least one of the specified locations. exclude_target_locations: type: array items: type: string example: - IS - GB - FR - IE - ES description: >- Filter advertisements to exclude those targeting specific locations by country code. Use this to filter out ads that are being shown in specific countries. When specified in `filter_conditions` with operator 'or', the advertisement must not target any of the excluded locations. securitySchemes: pubrio_api_key: type: apiKey name: pubrio-api-key description: >- A unique API token that represents the actions you perform through the API and the corresponding permissions and operations. You can create it through the [Settings](https://dashboard.pubrio.com/#/settings/) section. in: header ````