---
title: "Intelligent network search"
method: POST
path: "/api/v1/search/network"
tags: ["Search"]
---

# Intelligent network search

`POST /api/v1/search/network`

## Request

- Base URL: `https://app.usehomie.com`
- URL: `https://app.usehomie.com/api/v1/search/network`
- Auth: HTTP bearer

Search across the organization's combined network with a natural-language query, structured criteria, or both. Supports the same filters as MCP search_network.

## Request body

- NetworkSearchRequest
  - `query` string: People criteria from the user's goal and context, e.g. 'seed investors in Nordic B2B software' or 'senior product designers in Helsinki'. Preserve requested roles, industries and locations; do not add sales ICP criteria to non-sales searches. Optional when titles, industries, locations, companyLocations or companySizes are given.
  - `titles` string[]: Job titles to match, e.g. ['CRO', 'VP of Sales', 'Head of Sales Enablement']. Added to whatever the query names; widened with similar titles unless similarTitles is false.
  - `industries` string[]: Current-company industries (LinkedIn names such as 'Software Development', 'IT Services and IT Consulting'); widened with related ones unless similarIndustries is false.
  - `locations` string[]: Where the person is based: countries, states, regions or cities, e.g. ['United States', 'Canada'] or ['San Francisco Bay Area', 'New York'].
  - `companyLocations` string[]: Where the person's current company is headquartered.
  - `companySizes` string[]: Company employee bands, e.g. ['201-500', '501-1000', '10001+']; several bands combine into one range.
  - `similarTitles` boolean: Widen titles with similar ones (VP Sales also finds Vice President of Sales, Head of Revenue). Default: on at strictness 1. true widens at any strictness; false keeps the given titles only.
  - `similarIndustries` boolean: Widen industries with related ones. Default true.
  - `networks` string[]: Which networks to include (default: all three)
  - `strictness` integer: 1=relaxed (default), 2=normal, 3=strict
  - `asUserId` string: Optional: org member whose perspective to use for user/advocate networks. Defaults to the authenticated MCP user when available, otherwise the oldest admin.
  - `limit` integer
  - `offset` integer: Pass the previous response's nextOffset to get the next page; omit for the first page.
  - `excludePersonIds` string[]: Person ids never to return, e.g. everyone already shown to the user in this conversation.
  - `excludeCompanies` string[]: Leave out people currently at these companies (case-insensitive name match), e.g. existing customers or competitors.
  - `excludeIndustries` string[]: Leave out people whose current company is in these industries, e.g. an ICP's exclusions such as ['Manufacturing', 'Retail', 'Transportation, Logistics'].
  - `excludePositions` string[]: Title keywords to leave out, matched on word boundaries, e.g. ['account executive'] when the ICP rules out individual sellers.
  - `directContacts` 'include' | 'exclude' | 'only': People the searching user already knows directly. include (default) keeps them; exclude leaves them out so every result needs an introduction (prospecting); only returns just them ('who do I already know who fits').
  - `excludeConnectorPersonIds` string[]: Person ids no intro route may pass through, e.g. a connector the user ruled out. People reachable only through them are left out.
  - `excludeConnectorNames` string[]: No intro route may pass through a connector with this name (case-insensitive substring), e.g. ['Celeste Berke'], with no id lookup needed.
  - `excludeConnectorCompanies` string[]: No intro route may pass through a connector currently at these companies (case-insensitive name match).
  - `mode` 'auto' | 'vector' | 'neo4j' | 'prisma': Search backend. Leave unset to select automatically and allow fallback.

## Response `200`

Ranked search results

- object
  - `data` NetworkSearchHit[], required
    - `id` string, required
    - `person` object, required
      - `id` string, required
      - `name` string, required
      - `position` string, nullable
      - `avatarUrl` string, nullable
      - `city` string, nullable
      - `country` string, nullable
      - `linkedinId` string, nullable
      - `email` string, nullable
    - `currentCompany` object
      - `id` string, required
      - `name` string, required
      - `industry` string, nullable
      - `logoUrl` string, nullable
      - `company_id` string, required
      - `minSize` number, nullable
      - `maxSize` number, nullable
    - `connectionSources` object[], required
      - `type` 'direct' | 'advocate' | 'organization' | 'peek' | 'second-degree', required
      - `name` string, required
      - `advocateId` string
      - `advocatePersonId` string, nullable
      - `warmness` number
      - `warmnessBreakdown` object: Free-form map of warmness factor names to values
      - `secondDegreeWarmness` number
      - `secondDegreeBreakdown` object: Free-form map of warmness factor names to values
      - `teamMemberId` string
      - `teamMemberName` string, nullable
      - `connectorToProspectSignals` string[]
      - `networkOwnerToConnectorSignals` string[]
    - `totalConnectorCount` number
    - `relevanceScore` number
    - `vectorSimilarity` number
    - `warmness` number
    - `warmnessBreakdown` object: Free-form map of warmness factor names to values
    - `matchedPositions` string[]
    - `searchMethod` 'keyword' | 'vector-industry'
    - `isPeek` boolean
    - `omittedRouteCount` number: MCP only: weaker routes to this person left out of connectionSources
  - `meta` object, required
    - `searchTerms` string[], required
    - `totalCount` number, required
    - `returnedCount` number, required
    - `nextOffset` integer
    - `backend` 'neo4j-vector' | 'neo4j-keyword' | 'prisma', required
    - `fallback` object
      - `from` 'neo4j-vector' | 'neo4j-keyword' | 'prisma', required
      - `reason` string, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Plan required or insufficient scope

---

[API](https://skmtc.dev/usehomie/apis/homie-api.md) - [All operations](https://skmtc.dev/usehomie/apis/homie-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usehomie/apis/homie-api/revisions/00ccf1c3b436?raw)