Humans

A Human is the result of a search_humans call. It represents a real person found on the web, with their social network profiles, bio, location, and a confidence score indicating how reliably the profiles were matched.

Your agent finds the person first. Everything else — the event, the meeting, the relationship — starts here.

Overview

When your AI agent needs to find a person — whether for outbound sales, meeting preparation, or lead enrichment — it calls search_humans with a name and optional company or location info. HumanConnection searches across the open web using SearXNG (meta-search), crawls Linktree pages for handle discovery via Crawl4AI, and returns a structured result with the best matching profiles, optionally including email and company domain.

The Human type

1
interface Human {
2
  name: string;              // The person's name as searched
3
  email?: string;            // Email address (when provide_email is set)
4
  company_domain?: string;   // Company domain (e.g. "airbnb.com")
5
  bio?: string;              // Extracted bio from LinkedIn and other sources
6
  location?: string;         // Location extracted from LinkedIn (e.g. "New York, NY")
7
  profiles: HumanProfiles;   // Discovered social profile URLs
8
  confidence: number;        // Score from 0.0 to 1.0
9
}
10
11
interface HumanProfiles {
12
  linkedin_profile_url?: string;   // LinkedIn profile URL
13
  x_profile_url?: string;          // X/Twitter profile URL
14
  instagram_profile_url?: string;  // Instagram profile URL
15
  tiktok_profile_url?: string;     // TikTok profile URL
16
}

Example response

1
[
2
  {
3
    "name": "Brian Chesky",
4
    "email": "brian@airbnb.com",
5
    "company_domain": "airbnb.com",
6
    "bio": "Co-Founder & CEO at Airbnb.",
7
    "location": "San Francisco, CA",
8
    "profiles": {
9
      "linkedin_profile_url": "https://linkedin.com/in/brianchesky",
10
      "x_profile_url": "https://x.com/bchesky",
11
      "instagram_profile_url": "https://instagram.com/bchesky"
12
    },
13
    "confidence": 0.85
14
  }
15
]

search_humans parameters

search_humans supports two modes of operation. Provide either name OR (location + title_filters), not both.

Person lookup mode

Search for a specific person by name, with optional company and location context.

People search mode

Find professionals matching specific criteria by location and title.

1
import { search_humans } from '@humanconnection/toolkit';
2
3
// Basic search
4
const results = await search_humans({ name: "Elon Musk" });
5
6
// Search with company name for disambiguation
7
const results = await search_humans({
8
  name: "Brian Chesky",
9
  company_name: "Airbnb"
10
});
11
12
// Search with company domain for precise matching
13
const results = await search_humans({
14
  name: "Brian Chesky",
15
  company_domain: "airbnb.com"
16
});
17
18
// Search with location
19
const results = await search_humans({
20
  name: "Sara Blakely",
21
  company_name: "Spanx",
22
  location: "Atlanta"
23
});
24
25
// Get email address
26
const results = await search_humans({
27
  name: "David Solomon",
28
  company_domain: "goldmansachs.com",
29
  provide_email: true
30
});
31
32
// People search mode: find professionals by location and title
33
const results = await search_humans({
34
  location: "Austin",
35
  title_filters: "sales AND SaaS"
36
});
37
38
// People search with email
39
const results = await search_humans({
40
  location: "New York",
41
  title_filters: "engineer OR developer NOT intern",
42
  provide_email: true
43
});

How search works under the hood

Phase 1: Discover

Parallel SearXNG queries are fired for:

• "Name" company_name (general search)
• Name company_name site:linkedin.com/in (LinkedIn)
• Name site:instagram.com (Instagram)
• Name site:x.com OR site:twitter.com (X/Twitter)
• Name site:tiktok.com (TikTok)
• "company_name" site:linktr.ee (Linktree, if company info provided)

All results are deduplicated. LinkedIn post URLs are parsed to extract profile slugs for additional searches.

Phase 2: Scrape

Linktree pages found in results are crawled using Crawl4AI to discover non-obvious social handles. For example, searching for a person with their brand name discovers Linktree links to handles that would never be found by name alone.

Linktree-discovered handles are verified by checking if the linked Instagram account exists and matches the company context.

Phase 3: Compare

Candidates are scored per platform using:

• Handle matching: Does the LinkedIn slug match the person’s name? (e.g. linkedin.com/in/brianchesky for “Brian Chesky”)
• Keyword similarity: How much overlap is there between the candidate’s bio keywords and the company/location keywords?
• Context verification: Does the candidate’s bio mention the company name, domain, or location?

The best candidate per platform is selected. A minimum keyword intersection threshold prevents false positives.

Confidence scoring

Confidence is capped at 1.0. A score of 0.85 means three platforms were matched.

How humans relate to other resources

• Services: After finding a person with search_humans, create a service request to arrange a face-to-face meeting with them. Pass the discovered linkedin_profile_url in the guest info for better targeting.
• Events: Use search_events to find conferences and meetups near the person’s location — the most natural context for a first meeting.
• Meetings: A confirmed meeting links a human representative to the discovered person at an event or place.

Best practices

• Always provide company context. Common names like “John Smith” will produce unreliable results without company_name or company_domain.
• Prefer company_domain over company_name. Domains are unique identifiers — company_domain: "airbnb.com" is more precise than company_name: "Airbnb".
• Use location to disambiguate. When a company has offices in multiple cities, adding location narrows results to the right person.
• Use people search mode to find reps. Combine location and title_filters with boolean syntax (AND/OR/NOT) to find sales reps or other professionals near a lead.
• Use provide_email when you need contact info. Set provide_email: true to include email addresses in results — useful for sending meeting invites.
• Check confidence. Results with confidence below 0.4 (only one platform found) should be treated as low-certainty matches.
• Feed LinkedIn URL into search_interests. After finding a person, pass their linkedin_profile_url and x_profile_url to search_interests for meeting personalization.