Happenstance

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

Documentation: https://developer.happenstance.ai

Authentication

All requests require the HAPPENSTANCE_API_KEY environment variable. Pass it as a Bearer token:

CODEBLOCK0

Base URL: INLINECODE1

Billing

• - Search: 2 credits per search (including find-more)
• Research: 1 credit per completed research
• Check balance with INLINECODE2
• Purchase credits at https://happenstance.ai/settings/api

Available Operations

1. Search Your Network

Search for people across groups and connections. Searches run asynchronously.

Start a search:

CODEBLOCK1

You can also search within specific groups by adding "group_ids": ["uuid1", "uuid2"]. Get group IDs from GET /v1/groups.

At least one search source is required: group_ids, include_my_connections: true, or include_friends_connections: true.

Response:

CODEBLOCK2

Poll for results (every 5-10 seconds until status is COMPLETED or FAILED):

CODEBLOCK3

Completed response includes:

• - status: RUNNING, COMPLETED, or INLINECODE13
• INLINECODE14: array of people, each with id, name, current_title, current_company, summary, weighted_traits_score, socials (with happenstance_url, linkedin_url, twitter_url), mutuals, and INLINECODE26
• INLINECODE27: boolean indicating if more results are available
• INLINECODE28: top-level array of mutual connections (results reference these by index)
• INLINECODE29: top-level array of trait definitions (results reference these by index)

2. Find More Results

When has_more is true on a completed search, get additional results that exclude all previously returned people. Costs 2 credits.

CODEBLOCK4

Response:

CODEBLOCK5

Then poll with the page_id:

CODEBLOCK6

3. Research a Person

Get a detailed professional profile for a specific person. Runs asynchronously.

Start research:

CODEBLOCK7

Include as many details as possible (full name, company, title, location, social handles) for best results.

Response:

CODEBLOCK8

Poll for results (every 5-10 seconds until status is COMPLETED, FAILED, or FAILED_AMBIGUOUS):

CODEBLOCK9

Completed response includes a profile object with:

• - person_metadata: full_name, alternate_names, profile_urls, current_locations, INLINECODE41
• INLINECODE42: array of jobs with company_name, job_title, start_date, end_date, INLINECODE47
• INLINECODE48: array with university_name, degree, start_date, INLINECODE52
• INLINECODE53: array with title, description, INLINECODE56
• INLINECODE57: array of publications with title, description, date, INLINECODE61
• INLINECODE62: array with INLINECODE63
• INLINECODE64: overall text summary with supporting INLINECODE66

4. List Groups

Get the groups you can search within:

CODEBLOCK10

Returns {"groups": [{"id": "uuid", "name": "Group Name"}, ...]}.

5. Check Credits and Usage

CODEBLOCK11

Returns balance_credits, has_credits, purchases, usage history, and auto_reload settings.

Error Handling

Errors use RFC 7807 format:

CODEBLOCK12

Key status codes:

• - 401: Invalid or missing API key
• INLINECODE74: Insufficient credits
• INLINECODE75: Too many concurrent requests (max 10 running searches or research requests)
• INLINECODE76/503: Server error, retry with backoff

Tips

• - Always check credits before starting multiple searches or research requests.
• Search typically completes in 30-60 seconds. Research takes 1-3 minutes.
• Each search returns up to 30 results. Use find-more for additional pages.
• When presenting search results, include the person's name, title, company, summary, and Happenstance profile link.
• When presenting research, summarize the profile and link to sources.
• The more data sources the user connects, the better the search results.