Search warm paths

GET /api/v1/search/warm-paths

Find warm intro paths from anyone in your organization to a target person OR to anyone at a target company. Considers all path types: direct, 2nd-degree, advocate, and advocate 2nd-degree connections. Each path includes warmness breakdowns showing the factors behind the score.

Pass one target parameter: prospectLinkedinId, prospectName, or prospectCompany.

Connection types

direct: an org member is directly connected to the prospect.
second_degree: an org member knows someone who knows the prospect.
advocate: an advocate of an org member is directly connected to the prospect.
advocate_second_degree: an advocate of an org member knows someone who knows the prospect.

Results are ranked in this order: direct, advocate, 2nd-degree, advocate 2nd-degree. Within each tier, warmer paths appear first.

Query parameters

Name	Type	Required	Description
`prospectLinkedinId`	string	one of these	LinkedIn handle of the target person.
`prospectName`	string	one of these	Fuzzy name match if no LinkedIn handle is known.
`prospectCompany`	string	one of these	Company name. Returns paths to anyone at that company. Each path's `target` field shows the specific employee. Prefers exact name match.
`limit`	number	no	1-50, default 20.
`offset`	number	no	0-based offset for pagination. Use `nextOffset` from the previous response to fetch the next page.
`includeIntroRequested`	`"true"` \| `"false"`	no	Company mode only. Default `"false"`; include employees your organization has already requested an intro to.
`scope`	`"organization"` \| `"me"`	no	Whose networks to search. Default `"organization"`; `"me"` requires a user-scoped MCP token.
`fromUserIds`	string	no	Organization member ids, as repeated parameters or a comma-separated list. Accepts user ids and person ids.
`connectionTypes`	string	no	Path types as repeated parameters or a comma-separated list: `direct`, `second_degree`, `advocate`, `advocate_second_degree`.

Examples

Find warm paths to a specific person:

curl -H "Authorization: Bearer $KEY" \"https://app.usehomie.com/api/v1/search/warm-paths?prospectName=Jamie+Rivera&limit=5"

Find warm paths to anyone at a company:

curl -H "Authorization: Bearer $KEY" \"https://app.usehomie.com/api/v1/search/warm-paths?prospectCompany=Stripe&limit=10"

Response: person mode

{
  "data": {
    "prospect": {
      "id": "person_...",
      "name": "Jamie Rivera",
      "linkedinId": "jamierivera",
      "position": "CEO",
      "company": "Acme"
    },
    "company": null,
    "paths": [
      {
        "fromUserId": "user_...",
        "fromUserName": "Sarah Chen",
        "connector": {
          "id": "person_...",
          "name": "Dana Whitfield",
          "position": "Former CEO",
          "company": "Vertex"
        },
        "connectionType": "second_degree",
        "warmness": 78,
        "userToConnectorWarmness": 65,
        "userToConnectorBreakdown": {
          "pastCompanyOverlap": 50,
          "industryTypeMatch": 15
        },
        "userToConnectorSignals": [
          "Previously at Vertex",
          "3 mutual connections"
        ],
        "connectorToProspectWarmness": 78,
        "connectorToProspectBreakdown": {
          "currentCompanyMatch": 65,
          "sameCity": 5
        },
        "connectorToProspectSignals": ["Working together at Acme"]
      }
    ],
    "totalCount": 1,
    "returnedCount": 1,
    "limit": 5,
    "offset": 0,
    "hasMore": false,
    "excludedIntroRequested": 0,
    "coverage": {
      "capped": false,
      "candidatePeople": 1,
      "secondDegreeEdgesCapped": false
    }
  }
}

Response: company mode

{
  "data": {
    "prospect": null,
    "company": {
      "id": "company_...",
      "name": "Stripe",
      "companyId": "stripe",
      "industry": "Computer Software",
      "headquartersLocation": "South San Francisco"
    },
    "paths": [
      {
        "fromUserId": "user_...",
        "fromUserName": "Sarah Chen",
        "connector": {
          "id": "person_...",
          "name": "Maria Silva",
          "position": "Head of Partnerships",
          "company": "Northwind"
        },
        "connectionType": "advocate",
        "warmness": 68,
        "userToConnectorWarmness": 100,
        "connectorToProspectWarmness": 68,
        "connectorToProspectBreakdown": {
          "pastCompanyOverlap": 68,
          "pastCompanyName": "Salesforce"
        },
        "connectorToProspectSignals": ["Previously at Salesforce"],
        "target": {
          "id": "person_...",
          "name": "Alex Johnson",
          "linkedinId": "alexjohnson",
          "position": "Account Executive at Stripe",
          "company": "Stripe"
        }
      }
    ],
    "totalCount": 42,
    "returnedCount": 1,
    "limit": 10,
    "offset": 0,
    "nextOffset": 1,
    "hasMore": true,
    "excludedIntroRequested": 3,
    "coverage": {
      "capped": false,
      "candidatePeople": 46,
      "candidatePeopleCap": 500,
      "secondDegreeEdgesCapped": false
    }
  }
}

Notes

If the person or company is not found, prospect and company are both null and paths is empty. If the target is found but no paths exist, the matched prospect or company is still returned with an empty paths array and pagination fields.
For company mode, each path entry includes a target field identifying the specific employee being reached. For person mode, target is omitted (the prospect is the target).
Company mode excludes employees your organization has already requested an intro to unless includeIntroRequested=true; excludedIntroRequested reports how many were withheld. Person mode never filters the named person and instead annotates prospect with introRequested, introStatus, introRequestedBy, and introRequestedAt when a request exists.
Always check coverage.capped before treating the result as complete. It becomes true when the company employee scan or second-degree edge scan hits its bound.
On an advocate_second_degree path, viaAdvocate identifies the accepted advocate the organization member can ask first. connector is that advocate's connection to the target.
userToConnectorBreakdown / connectorToProspectBreakdown are free-form objects whose keys are warmness factor names (e.g. currentCompanyMatch, pastCompanyOverlap, sharedAccelerator, sameCity). New factors may be added over time, so treat the schema as open-ended.
userToConnectorSignals / connectorToProspectSignals are arrays of human-readable strings derived from the breakdown (e.g. "Working together at Acme", "3 mutual connections", "Both reacted to each other's posts"). Useful when handing paths to an LLM or rendering them directly in a UI. Omitted when no signals are available.