Endpoint Selection for AI Agents

Fundable’s collection endpoints can apply similar filters while returning different entity types. Choose the endpoint based first on the result the user wants, then on whether funding-round filters should apply only to a company’s latest round or to its complete history.

​

Choose the result type first

​

Choose companies or deals

Use POST /companies for most company discovery. Each result includes company metadata such as its name and domain plus the full details of its latest funding round. Filters inside latest_deal apply only to that most recent round. Filters inside investors can match investor participation across all rounds.

Example: “Find AI companies in San Francisco whose latest round was Seed” should use POST /companies with company industry and location filters plus a latest_deal.financing_types filter.

Use POST /deals when the requested result is a set of rounds or the analysis must include historical rounds even when they are no longer a company’s latest.

Example: “Analyze every Seed round announced last year” should use POST /deals. A company that later raised Series A still belongs in this result.

Deal responses contain full round details, but related companies and investors are represented primarily by IDs. Follow a returned company ID with GET /company. Follow a deal ID with GET /deals/{id}/investors to retrieve firm investors, associated partners, angels, lead status, and profile links.

​

Choose investor firms or people

Use POST /investors when the desired output is investor firms. Conceptually, its company_investments filters identify qualifying portfolio companies and deals, then return the firms that participated in them.

Example: “Find San Francisco-based investors that participated in a Seed round during the last year” should use POST /investors. Put firm location filters under investor and round filters under company_investments.

When company_investments filters are active:

• filtered_deal_count is the number of deals that matched those filters.
• filtered_lead_count is the number of those matching deals the firm led.

Use POST /people when the desired output is individuals:

• person_type: company returns founders, executives, and employees based on their current employer. company.latest_deal filters apply only to the employer’s latest round, but the returned person record does not include the employer’s funding data.
• person_type: investor applies investment filters similarly to POST /investors, but returns individual angels or lead partners attached to their firms.

Example: “Find founders of AI companies in San Francisco whose latest round was Series A” should use POST /people with person_type: company, a founder role, current-employer filters, and company.latest_deal.financing_types.

​

Skip search when a stable identifier is known

A domain or LinkedIn URL is usually a stronger identifier than a name. Pass it directly to a detail endpoint instead of searching first: For batch lookup, pass arrays of known identifiers to the corresponding collection endpoint. Use the singular /search routes primarily for fuzzy name resolution or when an identifier might be ambiguous.

​

Resolve filters before discovery

Do not let an agent invent location or industry permalinks.

1. Resolve a location label with GET /location/search.
2. Resolve an industry or super category with GET /industry/search.
3. Pass the selected exact permalinks to the collection endpoint.

See Filtering & Permalinks for permalink behavior and round-type enum values.

​

When to use semantic search

Semantic search is a fallback for category intent that Fundable’s industry taxonomy cannot express precisely. It matches the meaning of a company’s product, technology, or business model rather than treating the query as a literal keyword filter. Use this decision sequence:

1. Call GET /industry/search with the user’s category.
2. If the taxonomy contains an appropriate industry or super category, use its permalink in the structured filter.
3. If no taxonomy result captures the requested niche, use search_query.
4. Apply location, stage, round date, funding, employee count, and other structured requirements through their dedicated fields alongside the semantic query.

Semantic searches return at most 150 matches. Results are relevance-ranked, and an optional min_relevance threshold from 0 to 1 can exclude weaker matches. On POST /companies and POST /people, semantic search overrides an explicit sort_by; POST /investors ranks firms by how closely their portfolios match the query. Do not include structured requirements such as “Seed,” “San Francisco,” “raised last year,” or “11-50 employees” inside search_query. Doing so makes the request less predictable and bypasses filters designed for those constraints.

​

Common endpoint sequences

​

Agent guardrails

• Keep the Fundable API key outside model context.
• Allowlist filters and round-type enum values.
• Cap page_size and automatic pagination.
• Log tool arguments, response status, credits used, and the requesting user.
• Call GET /person/email or GET /person/phone only when verified contact information is explicitly required; each new unlock consumes 5 credits.
• Require confirmation before writing to a CRM or sending outreach.

When wrapping the API in custom tools, expose narrow tools whose names reflect the returned entity, such as find_companies, find_deals, find_investor_firms, and find_people. This keeps permissions, return shapes, and tool selection predictable.