Happenstance

Happenstance

Search your network and get detailed research profiles on people using Happenstance.

Documentation: https://developer.happenstance.ai

Credits

• Search: 2 credits per search (including find-more)
• Research: 1 credit per completed research
• Always call get-credits before starting searches or research to check balance
• Use create-credits-checkout-session if the user needs more credits

Workflows

Search for People

Searches can pull from three sources, controlled by parameters:

• Groups (includeGroups): Search across the user's Happenstance groups. Searches all groups by default, or pass specific groups (array of group IDs) to narrow scope. Call get-groups to list available groups and their IDs.
• Connections (includeConnections): Search the user's direct connections.
• Friends (includeFriends): Search connections of the user's friends.

All three are enabled by default. The user may want to search only specific sources — for example, only within a particular group, or only their direct connections.

Steps:

1. If the user wants to search specific groups, call get-groups first to list available groups and get their IDs. Use get-group to see members of a specific group.
2. Call search-network with a natural language query and the desired source parameters — returns a searchId
3. Poll with get-search-results using the searchId until status is completed
4. If has_more is true and the user wants more, call find-more-results (not a new search) — returns a pageId
5. Poll with get-search-results using both the original searchId and the pageId

When a user asks "who do I know that..." set includeGroups: false, includeFriends: false, includeConnections: true.

Research a Person

1. Call research-person with a description including as many details as possible (full name, company, title, social handles) — returns a researchId
2. Poll with get-research-results using the researchId until status is completed

Use @Mentions for Targeted Search

To search a specific person's connections, @mention them in the query:

• First call get-groups and get-group to look up member names, or get-user for friends
• Then search with: "engineers @Jane Smith knows"

Presenting Results

Search Results

Each result includes name, current_title, current_company, summary, socials (with happenstance_url, linkedin_url, twitter_url), mutuals, and traits.

• Highlight mutual connections: Results include mutuals with relationship strength — surface the strongest mutual connections to help the user find the warmest intro path
• Include profile links: Always link to the person's Happenstance profile URL
• Show relevance: Include the person's summary and matching traits

Research Results

A completed research profile includes:

• person_metadata: full name, alternate names, profile URLs, locations, tagline
• employment: career history with companies, titles, dates, descriptions
• education: universities, degrees, dates
• projects: notable projects with descriptions and URLs
• writings: publications with titles, dates, URLs
• hobbies: personal interests
• summary: overall summary with supporting source URLs

Summarize the profile and link to sources when presenting.

Tips

• Search typically completes in 30-60 seconds. Research takes 1-3 minutes.
• Each search returns up to 30 results. Use find-more-results for additional pages.
• The more data sources the user connects, the better the search results.