Happenstance

搜索您的社交网络，并通过 Happenstance API 获取人员的详细调研档案。

文档地址：https://developer.happenstance.ai

认证

所有请求均需设置 HAPPENSTANCE_API_KEY 环境变量，并以 Bearer Token 方式传递：

Authorization: Bearer $HAPPENSTANCE_API_KEY

基础 URL：https://api.happenstance.ai

计费说明

• 搜索：每次搜索（含 find-more）消耗 2 个积分
• 调研：每次完成的调研消耗 1 个积分
• 使用 GET /v1/usage 查询当前余额
• 在 https://happenstance.ai/settings/api 购买积分

可用操作

1. 搜索您的社交网络

跨群组及联系人关系搜索人员。搜索任务异步执行。

发起搜索：

curl -s -X POST https://api.happenstance.ai/v1/search 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "text": "engineers who have worked on AI infrastructure",
    "include_my_connections": true,
    "include_friends_connections": true
  }'

您还可通过添加 "group_ids": ["uuid1", "uuid2"] 限定在特定群组内搜索。群组 ID 可通过 GET /v1/groups 获取。

至少需指定一项搜索来源：group_ids、include_my_connections: true 或 include_friends_connections: true。

响应示例：

{"id": "search-uuid", "url": "https://happenstance.ai/search/search-uuid"}

轮询结果（每 5–10 秒一次，直至状态变为 COMPLETED 或 FAILED）：

curl -s https://api.happenstance.ai/v1/search/SEARCH_ID 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

完成后的响应包含以下字段：

• status：状态值为 RUNNING、COMPLETED 或 FAILED
• results：人员数组，每个对象包含 id、name、current_title、current_company、summary、weighted_traits_score、socials（含 happenstance_url、linkedin_url、twitter_url）、mutuals（共同联系人索引）和 traits（特质索引）
• has_more：布尔值，表示是否还有更多结果可获取
• mutuals：顶层共同联系人数组（results 中通过索引引用）
• traits：顶层特质定义数组（results 中通过索引引用）

2. 获取更多结果（find-more）

当已完成搜索的响应中 has_more 为 true 时，可调用此接口获取排除所有已返回人员的新一批结果。每次调用消耗 2 个积分。

curl -s -X POST https://api.happenstance.ai/v1/search/SEARCH_ID/find-more 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

响应示例：

{"page_id": "page-uuid", "parent_search_id": "search-uuid"}

随后使用 page_id 轮询结果：

curl -s "https://api.happenstance.ai/v1/search/SEARCH_ID?page_id=PAGE_ID" 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

3. 调研某位人员

为特定人员生成详细的职场档案。该操作异步执行。

发起调研：

curl -s -X POST https://api.happenstance.ai/v1/research 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"description": "Garry Tan, CEO of Y Combinator, @garrytan on Twitter"}'

为获得最佳效果，请尽可能提供完整信息（如全名、公司、职位、所在地、社交账号等）。

响应示例：

{"id": "research-uuid"}

轮询结果（每 5–10 秒一次，直至状态变为 COMPLETED、FAILED 或 FAILED_AMBIGUOUS）：

curl -s https://api.happenstance.ai/v1/research/RESEARCH_ID 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

完成后的响应中包含 profile 对象，其字段如下：

• person_metadata：含 full_name、alternate_names、profile_urls、current_locations、tagline
• employment：工作经历数组，每项含 company_name、job_title、start_date、end_date、description
• education：教育经历数组，每项含 university_name、degree、start_date、end_date
• projects：项目数组，每项含 title、description、urls
• writings：出版物数组，每项含 title、description、date、urls
• hobbies：兴趣爱好数组，每项含 description
• summary：整体摘要文本 text，并附带支撑性链接 urls

4. 列出群组

获取您有权搜索的群组列表：

curl -s https://api.happenstance.ai/v1/groups 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

响应格式：{"groups": [{"id": "uuid", "name": "Group Name"}, ...]}

5. 查询积分余额与使用情况

curl -s https://api.happenstance.ai/v1/usage 
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

返回字段包括：balance_credits（当前余额）、has_credits（是否有可用积分）、purchases（购买记录）、usage（使用历史）以及 auto_reload（自动续充设置）。

错误处理

错误响应遵循 RFC 7807 标准格式：

{"type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Description must not be empty", "instance": "/v1/research"}

关键状态码说明：

• 401：API 密钥无效或缺失
• 402：积分不足
• 429：并发请求数超限（最多同时运行 10 个搜索或调研任务）
• 500/503：服务端错误，建议采用退避策略重试

使用提示

• 批量发起搜索或调研前，请务必确认账户积分充足。
• 搜索通常耗时 30–60 秒；调研通常耗时 1–3 分钟。
• 单次搜索最多返回 30 条结果；如需更多结果，请使用 find-more 接口分页获取。
• 展示搜索结果时，建议呈现人员姓名、职位、公司、摘要及 Happenstance 档案链接。
• 展示调研结果时，建议对档案内容进行概括性总结，并附上原始信息来源链接。
• 用户接入的数据源越多，搜索结果质量越高。