---
title: "Search warm intro paths"
method: GET
path: "/api/v1/search/warm-paths"
tags: ["Search"]
---

# Search warm intro paths

`GET /api/v1/search/warm-paths`

## Request

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

Find warm intro paths from anyone in the organization to one target person or company. Pass prospectPersonId, prospectLinkedinId, prospectLinkedinUrl, prospectName (optionally with prospectCompany), prospectCompany, or prospectCompanyDomain. Domains match exact website hosts; ambiguous matches return 400. In company mode, people the organization has already requested an intro to are excluded by default and counted in `excludedIntroRequested`; pass includeIntroRequested=true to include them. Person mode never filters, but annotates the prospect.

## Query parameters

- `prospectPersonId` string
- `maxHops` integer
- `includePossiblePaths` 'true' | 'false'
- `prospectLinkedinId` string
- `prospectLinkedinUrl` string: LinkedIn /in/ profile URL. Mutually exclusive with other target parameters.
- `prospectName` string
- `prospectCompany` string
- `prospectCompanyDomain` string: Company domain or HTTP(S) website URL. Exact normalized host match; preserves subdomains other than www.
- `prospectRoles` string: Company searches only. Comma-separated job-title terms; OR-matched before candidate limits. Also accepts repeated parameters.
- `limit` integer
- `offset` integer, nullable
- `includeIntroRequested` 'true' | 'false': Company mode only. Default false.
- `scope` 'organization' | 'me': Whose networks to search from. Default organization. 'me' requires a user-scoped token.
- `fromUserIds` string: Comma-separated org member ids (user ids or person ids) to search from. Mutually exclusive with a non-default scope.
- `connectionTypes` string: Comma-separated path types to keep: direct, second_degree, third_degree, advocate, advocate_second_degree.

## Response `200`

Ranked list of warm paths to the prospect or company employees

- object
  - `data` WarmPathSearchResult, required
    - `outcome` 'found' | 'target_not_found' | 'no_paths' | 'incomplete'
    - `message` string: Human-readable summary of the outcome. Set when there is no warm path (or the target was not found) so you can explain the situation instead of implying the network is empty.
    - `fallbackConnections` object[]: Only set when outcome is no_paths or target_not_found: the organization's warmest reachable people, warmest first, as alternative starting points. These are NOT a path to the requested target — present them as the org's closest existing contacts.
      - `id` string, required
      - `name` string, required
      - `position` string
      - `company` string
      - `avatarUrl` string
      - `warmness` number, required
    - `prospect` object, nullable, required
      - `id` string, required
      - `name` string, required
      - `linkedinId` string
      - `position` string
      - `company` string
      - `avatarUrl` string
      - `introRequested` boolean: True when someone in the organization has already requested an intro to this person
      - `introStatus` string: IntroStatus of that request: ACTIVE, WON, LOST, or NOT_TRACKABLE
      - `introRequestedBy` string: Org member who asked
      - `introRequestedAt` string
    - `company` object, nullable, required
      - `id` string, required
      - `name` string, required
      - `companyId` string
      - `industry` string
      - `headquartersLocation` string
      - `logoUrl` string
    - `paths` object[], required
      - `hops` object[]
        - `from` object, required
          - `id` string, required
          - `name` string, required
          - `userId` string
        - `to` object, required
          - `id` string, required
          - `name` string, required
          - `userId` string
        - `warmness` number, nullable, required
        - `signals` string[], required
      - `fromUserId` string, required
      - `fromUserName` string, required
      - `connector` object, required
        - `id` string, required
        - `name` string, required
        - `position` string
        - `company` string
        - `avatarUrl` string
      - `viaAdvocate` object
        - `id` string, required
        - `name` string, required
        - `position` string
        - `company` string
        - `avatarUrl` string
        - `userId` string, required
        - `warmness` number, required
        - `warmnessBreakdown` object: Free-form map of warmness factor names to values
      - `connectionType` 'direct' | 'second_degree' | 'third_degree' | 'advocate' | 'advocate_second_degree', required
      - `warmness` number, required
      - `userToConnectorWarmness` number, required
      - `userToConnectorBreakdown` object: Free-form map of warmness factor names to values
      - `userToConnectorSignals` string[]
      - `connectorToProspectWarmness` number
      - `connectorToProspectBreakdown` object: Free-form map of warmness factor names to values
      - `connectorToProspectSignals` string[]
      - `target` object
        - `id` string, required
        - `name` string, required
        - `linkedinId` string
        - `position` string
        - `company` string
        - `avatarUrl` string
        - `introRequested` boolean: True when someone in the organization has already requested an intro to this person
        - `introStatus` string: IntroStatus of that request: ACTIVE, WON, LOST, or NOT_TRACKABLE
        - `introRequestedBy` string: Org member who asked
        - `introRequestedAt` string
    - `totalCount` number, required
    - `returnedCount` number, required
    - `limit` number, required
    - `offset` number, required
    - `nextOffset` number
    - `hasMore` boolean, required
    - `excludedIntroRequested` number, required: Company mode: how many employees were withheld because an intro was already requested. Always 0 in person mode.
    - `coverage` object, required
      - `capped` boolean, required: True when bounded employee or graph scans may have omitted paths
      - `candidatePeople` number, required
      - `candidatePeopleCap` number
      - `secondDegreeEdgesCapped` boolean, required
      - `thirdDegreeEdgesCapped` boolean

## 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)