canonical: https://jentic.com/apis/happenstance.ai/happenstance # Happenstance API The Happenstance API searches people across your network and researches individuals in depth. An agent creates a search, reads its results, and asks for more matches, or starts a research job on a person and reads it back when ready. It also exposes the current user's profile, the groups a search can run against, and account usage, so an agent can pick the right network to search and track how much it has consumed. ## For AI agents Search for people across your network, request more matches, run in-depth research on a person, and read groups, profile, and usage. ## Scope Does not handle sending outreach, bulk CSV enrichment, or CRM sync. Use for person research and network people search only. ## Capabilities - Create a people search and read its results - Ask an existing search to find more matching people - Start an in-depth research job on a person and read it when ready - List the groups a search can run against - Read the current user profile and account usage ## Use cases ### Network People Search An agent finds the right people to reach out to across a user's network. It creates a search from a natural-language description, reads the ranked results, and calls find-more when it needs a deeper pool. Because a search is a stored resource with its own id, the agent can return to the same search and expand it rather than starting over. Example prompt: Create a search for people matching a description, read the results, and request more matches if fewer than five are returned ### Person Research Dossier An agent builds a research dossier on a person before a meeting. It starts a research job, then reads the research back by its id once it is ready. Keeping research as a separate job lets the agent kick it off and collect the result later instead of blocking on a single long call. Example prompt: Start a research job on a named person and poll the research endpoint until the result is ready ### Usage-Aware Automation An agent keeps its people-search automation within budget. It reads account usage before launching a batch of searches and picks the group to search against from the available groups. This lets a scheduled agent throttle itself and target the right network instead of searching blindly. Example prompt: Read account usage and the available groups, then create a search scoped to the chosen group ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/v1/search` | Create a people search | | GET | `/v1/search/{search_id}` | Read a search and its results | | POST | `/v1/search/{search_id}/find-more` | Find more matches for a search | | POST | `/v1/research` | Start a research job on a person | | GET | `/v1/research/{research_id}` | Read a research job result | | GET | `/v1/groups` | List searchable groups | ## Key resources - **Search** — Create a people search, read it, and find more matches - **Research** — Start an in-depth research job on a person and read it back - **Groups** — List the groups a search can run against and read one group - **Users** — Read the current user's profile - **Usage** — Read account usage ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 79 / 100 - **Maturity:** AI-Ready - **Dimensions:** - Foundational Compliance: 99 / 100 - Developer Experience & Jentic Compatibility: 69 / 100 - AI-Readiness & Agent Experience: 79 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 81 / 100 - **View full report:** https://jentic.com/apis/happenstance.ai/happenstance/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Happenstance by hand means handling its bearer token, running searches and research as asynchronous jobs you poll, and watching account usage yourself. Through Jentic you install once, import Happenstance from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Happenstance carries search and research ids in the URL path, so a rule can pin your agent to the search operations for one search. You choose the operations it may call, so research and account endpoints are not included unless you add them. - **Credential handling:** Your Happenstance token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'search people in my network' or 'research a person', and Jentic returns the matching Happenstance operation with its input schema so the agent calls the right endpoint without reading the reference docs. ## Related APIs - **People Data Labs** — People Data Labs enriches and resolves person records from a large data graph. - **Apollo** — Apollo offers a B2B contact database with search and outreach sequencing. - **Crunchbase** — Crunchbase adds company and funding context for the people a search surfaces. ## FAQ ### What authentication does the Happenstance API use? Per its OpenAPI spec, the Happenstance API authenticates with a bearer token sent in the Authorization header. Through Jentic the token is stored by your own self-hosted instance and injected when the agent calls an operation, so it never appears in the agent's prompt or logs. ### Can I search for people and run research with the Happenstance API? Yes. An agent creates a search from a description and reads the ranked results, then calls find-more to widen the pool. Separately it can start a research job on a person and read the research back by its id once it is ready, so discovery and deep research are two distinct flows. ### What are the rate limits for the Happenstance API? The OpenAPI spec does not state a numeric rate limit, but it does expose a usage endpoint an agent can read to track its own consumption. Add retry and backoff around 429 responses, and check the Happenstance documentation at https://developer.happenstance.ai for any published limits. ### Can I limit what my agent is allowed to do with the Happenstance API? Yes. Write a rule that allows the search create and read operations for one search id, so the agent can run and widen a specific search while the research and account operations stay out of reach until you add them, and every call it makes is logged. Happenstance carries search and research ids in the URL path, which is what makes that per-resource boundary possible. ### Is there a Happenstance MCP server? You do not need an MCP server to give your agent the Happenstance API. Jentic connects it directly from the Jentic API Directory: import Happenstance, store your token once, and your agent calls the search and research operations on demand without loading another server's tool definitions into its context. ### How do I search for people with the Happenstance API through Jentic? Search Jentic by intent such as 'search people in my network', and Jentic returns the Happenstance search operation with its input schema so the agent sends the right fields. To run it on your own infrastructure, install Jentic One from its GitHub repo with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, then add Happenstance from the directory.