{ "openapi": "3.0.3", "info": { "title": "Fundable API", "description": "Canonical OpenAPI specification for the Fundable API. Choose the collection endpoint whose return type matches the requested result: POST /companies for company discovery (the default for most sourcing workflows), POST /deals for round-level analysis across complete company histories, POST /investors for investor firms, and POST /people for founders, employees, angels, or lead partners. Use singular detail endpoints when a stable identifier such as a domain or LinkedIn URL is already known; use /search endpoints for fuzzy names or uncertain identifiers. Resolve human-readable locations and industries with their search endpoints before applying permalink filters. Operation descriptions contain the route-specific selection rules.", "version": "2.0.0", "contact": { "name": "Fundable API Support", "url": "mailto:jacob@tryfundable.ai" }, "license": { "name": "Proprietary", "url": "https://www.tryfundable.ai/terms/privacy/" } }, "servers": [ { "url": "https://www.tryfundable.ai/api/v1", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/deals": { "post": { "summary": "Find funding rounds across complete company histories", "description": "Use this endpoint when the requested result is a set of funding rounds, or when\ndeal criteria must match any historical round rather than only each company's\nlatest round. It supports round-level analysis across the full deal history.\n\nFor most company-sourcing requests, prefer `POST /companies`: it returns company\nmetadata together with the full latest deal. Its `latest_deal` filters apply only\nto each company's most recent round. For example, use `/companies` for \"find AI\ncompanies in San Francisco whose latest round was Seed,\" but use `/deals` for\n\"analyze every Seed round announced last year.\"\n\nDeal records contain full round details, but related companies and investors are\nidentified by IDs instead of full entity profiles. Use `GET /company?id=...` to\nretrieve company metadata and `GET /deals/{id}/investors` to retrieve the full\ninvestor lineup for a returned deal.\n\n## Request Body Structure\nSend a JSON body with up to 4 filter sections plus pagination/sort at the top level:\n- `identifiers` - Look up specific deals by UUID\n- `deal` - Filter by deal attributes (financing type, size, date)\n- `company` - Filter by company attributes (location, industry, size)\n- `investors` - Filter by investor participation (firms or people, by UUID)\n", "operationId": "searchDeals", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "page_size": 10 }, "properties": { "identifiers": { "type": "object", "description": "Look up specific deals by identifier", "properties": { "deal_ids": { "type": "array", "description": "Deal UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "550e8400-e29b-41d4-a716-446655440000" ] } } }, "deal": { "type": "object", "description": "Deal attribute filters", "properties": { "financing_types": { "type": "array", "description": "Financing types with optional modifiers (pre, extension)", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND" ] }, "pre": { "type": "boolean", "default": false, "description": "Pre-round modifier (e.g., Pre-Seed, Pre-Series A)" }, "extension": { "type": "boolean", "default": false, "description": "Extension round modifier" } } }, "example": [ { "type": "SEED", "pre": true }, { "type": "SERIES_A" } ] }, "size_min": { "type": "number", "minimum": 0, "description": "Minimum deal size (USD)", "example": 1000000 }, "size_max": { "type": "number", "minimum": 0, "description": "Maximum deal size (USD)", "example": 100000000 }, "date_start": { "type": "string", "format": "date", "description": "Filter deals announced after this date (ISO 8601)", "example": "2024-01-01" }, "date_end": { "type": "string", "format": "date", "description": "Filter deals announced before this date (ISO 8601)", "example": "2024-12-31" }, "created_start": { "type": "string", "format": "date", "description": "Filter deals added to the system after this date (ISO 8601)", "example": "2024-01-01" }, "created_end": { "type": "string", "format": "date", "description": "Filter deals added to the system before this date (ISO 8601)", "example": "2024-12-31" } } }, "company": { "type": "object", "description": "Company attribute filters", "properties": { "company_ids": { "type": "array", "description": "Company UUIDs - filter deals by specific companies", "items": { "type": "string", "format": "uuid" }, "example": [ "550e8400-e29b-41d4-a716-446655440001" ] }, "locations": { "type": "array", "description": "Location permalinks. Use /location/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "san-francisco-california", "california" ] }, "industries": { "type": "array", "description": "Industry permalinks. Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "artificial-intelligence", "fintech-e067" ] }, "super_categories": { "type": "array", "description": "Super category permalinks (automatically includes related industries). Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "artificial-intelligence-e551" ] }, "employee_count": { "type": "array", "description": "Employee count ranges. Valid: 1-10, 11-50, 51-100, 101-250, 251-500, 501-1000, 1001-5000, 5001-10000, 10001+", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "1-10", "11-50" ] }, "ipo_status": { "type": "array", "description": "IPO status filter. Valid: public, private", "items": { "type": "string", "enum": [ "public", "private" ] }, "example": [ "private" ] }, "total_raised_min": { "type": "number", "minimum": 0, "description": "Minimum total raised (USD)", "example": 10000000 }, "total_raised_max": { "type": "number", "minimum": 0, "description": "Maximum total raised (USD)", "example": 500000000 } } }, "investors": { "type": "object", "description": "Filter by investor participation (firms or people)", "properties": { "investor_ids": { "type": "array", "description": "Investor UUIDs (firms)", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" ] }, "people_ids": { "type": "array", "description": "Person UUIDs \u2014 matches deals where any of these people participated as an\n**angel investor** OR as a **lead partner** of an investing firm.\nResolve via `/people/{id}`.\n", "items": { "type": "string", "format": "uuid" }, "example": [ "b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a" ] } } }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Page number (0-based)" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10, "description": "Number of results per page" }, "sort_by": { "type": "string", "enum": [ "most_recent_deal", "oldest_deal", "largest_raise", "smallest_raise" ], "default": "most_recent_deal", "description": "Sort order for results" } } }, "examples": { "empty": { "summary": "Empty request (no filters)", "value": { "page_size": 5 } }, "filter_by_financing": { "summary": "Filter by financing type", "value": { "deal": { "financing_types": [ { "type": "SERIES_A" }, { "type": "SERIES_B" } ] }, "page_size": 10 } }, "filter_pre_seed": { "summary": "Filter for pre-seed deals", "value": { "deal": { "financing_types": [ { "type": "SEED", "pre": true } ] }, "page_size": 10 } }, "filter_by_company": { "summary": "Filter by company attributes", "value": { "company": { "industries": [ "artificial-intelligence" ], "ipo_status": [ "private" ] }, "deal": { "size_min": 5000000, "size_max": 100000000 }, "page_size": 10 } }, "lookup_by_ids": { "summary": "Look up specific deals", "value": { "identifiers": { "deal_ids": [ "550e8400-e29b-41d4-a716-446655440000" ] } } } } } } }, "responses": { "200": { "description": "Successful response with deals data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of deals matching the filter criteria", "example": 1547 }, "page": { "type": "integer", "description": "Current page number (0-based)", "example": 0 }, "page_size": { "type": "integer", "description": "Number of results per page", "example": 10 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid parameter types or malformed JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "422": { "description": "Unprocessable Entity - Parameter validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/deals/{id}": { "get": { "summary": "Get a specific deal by ID", "description": "Use this endpoint when a deal UUID is already known and full details for that one\nfunding round are required. The response identifies related entities by ID rather\nthan embedding their full profiles. Use `GET /company?id=...` for company metadata\nand `GET /deals/{id}/investors` for the complete investor lineup.\n", "operationId": "getDealById", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier for the deal (UUID format)", "required": true, "schema": { "type": "string", "format": "uuid", "example": "4b20cafe-c22b-441a-8378-53436e1d9edf" } } ], "responses": { "200": { "description": "Successful response with deal data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deal": { "$ref": "#/components/schemas/Deal" } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 1 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid deal ID format or unsupported query parameters", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_DEAL_ID" }, "message": { "type": "string", "example": "Deal ID must be a valid UUID" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please provide a valid UUID format for the deal ID" } } } } }, "statusCode": { "type": "integer", "example": 400 } } }, { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_PARAMETERS" }, "message": { "type": "string", "example": "Query parameters are not supported for this endpoint" }, "details": { "type": "object", "properties": { "providedParameters": { "type": "array", "items": { "type": "string" }, "example": [ "page", "sort_by" ] }, "help": { "type": "string", "example": "This endpoint only accepts a deal ID in the path. Remove all query parameters." } } } } }, "statusCode": { "type": "integer", "example": 400 } } } ] } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "DEAL_NOT_FOUND" }, "message": { "type": "string", "example": "Deal not found" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please check the deal ID and try again" } } } } }, "statusCode": { "type": "integer", "example": 404 } } } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/deals/{id}/investors": { "get": { "summary": "Get investors for a specific deal", "description": "Use this endpoint after identifying a deal when investor IDs in the deal record\nneed to be resolved into the complete investor lineup. It returns firm investors,\nassociated people, angel investors, lead status, and profile links for one deal.\n\nDo not use this endpoint to discover investors across many deals. Use\n`POST /investors` when the desired result is a list of firms, or `POST /people`\nwith investor filters when the desired result is individual investors.\n", "operationId": "getDealInvestors", "parameters": [ { "name": "id", "in": "path", "description": "Unique identifier for the deal (UUID format)", "required": true, "schema": { "type": "string", "format": "uuid", "example": "4b20cafe-c22b-441a-8378-53436e1d9edf" } } ], "responses": { "200": { "description": "Successful response with deal investors", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "investors": { "type": "array", "description": "Firm investors on this deal. Angels are surfaced separately in `angel_investors`.", "items": { "$ref": "#/components/schemas/DealInvestor" } }, "angel_investors": { "type": "array", "description": "Angel investors (individuals) on this deal. Empty array when no angels.", "items": { "$ref": "#/components/schemas/AngelInvestor" } } }, "required": [ "investors", "angel_investors" ] }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 1 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid deal ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "DEAL_NOT_FOUND" }, "message": { "type": "string", "example": "Deal not found" } } } } } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/company": { "get": { "summary": "Get company details and recent funding by identifier", "description": "Use this endpoint when one company is already identified and its full profile and\nlatest funding round are required. Prefer a domain or LinkedIn URL when available;\nthey can be passed directly here without calling `/company/search` first.\n\nUse `/company/search` for fuzzy company-name resolution or an uncertain identifier.\nUse `POST /companies` to discover or batch-retrieve multiple companies.\n\nProvide ONE of the following query parameters to identify the company:\n- `id` - Company UUID\n- `domain` - Company domain or full URL (e.g., \"stripe.com\" or \"https://stripe.com\")\n- `linkedin` - LinkedIn company URL\n- `crunchbase` - Crunchbase organization URL\n\nThe response includes the company's latest funding round details with participating investors.\n", "operationId": "getCompany", "parameters": [ { "name": "id", "in": "query", "description": "Company UUID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "domain", "in": "query", "description": "Company domain or full URL (e.g., \"stripe.com\" or \"https://stripe.com\") \u2014 URLs are automatically parsed to extract the domain", "required": false, "schema": { "type": "string" }, "example": "stripe.com" }, { "name": "linkedin", "in": "query", "description": "LinkedIn company URL", "required": false, "schema": { "type": "string" }, "example": "https://linkedin.com/company/stripe" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase organization URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/organization/stripe" } ], "responses": { "200": { "description": "Successful response with company data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/CompanyDetails" } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Bad request - missing identifier or invalid format", "content": { "application/json": { "schema": { "type": "object", "description": "Missing identifier error", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "MISSING_IDENTIFIER" }, "message": { "type": "string", "example": "Company identifier is required" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Provide an identifier using one of the query parameters: id, domain, linkedin, or crunchbase" }, "examples": { "type": "object", "properties": { "byDomain": { "type": "string", "example": "/api/v1/company?domain=stripe.com" }, "byLinkedIn": { "type": "string", "example": "/api/v1/company?linkedin=https://linkedin.com/company/stripe" }, "byCrunchbase": { "type": "string", "example": "/api/v1/company?crunchbase=https://crunchbase.com/organization/stripe" }, "byId": { "type": "string", "example": "/api/v1/company?id=550e8400-e29b-41d4-a716-446655440000" } } } } } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/company/deals": { "get": { "summary": "Get deals for a company by identifier", "description": "Use this endpoint when a company is already identified and its complete funding\nhistory is required. Prefer a domain or LinkedIn URL when available; it can be\npassed directly without first calling `/company/search`.\n\nThis route retrieves history for one identified company. Use `POST /deals` instead\nto discover rounds across the market with deal, company, or investor filters.\n\nProvide ONE of the following query parameters to identify the company:\n- `id` - Company UUID\n- `domain` - Company domain or full URL (e.g., \"stripe.com\" or \"https://stripe.com\")\n- `linkedin` - LinkedIn company URL\n- `crunchbase` - Crunchbase organization URL\n\nThe response includes the company's deals with pagination. If the identifier matches multiple companies, deals from all matches are returned.\n", "operationId": "getCompanyDeals", "parameters": [ { "name": "id", "in": "query", "description": "Company UUID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "domain", "in": "query", "description": "Company domain or full URL (e.g., \"stripe.com\" or \"https://stripe.com\") \u2014 URLs are automatically parsed to extract the domain", "required": false, "schema": { "type": "string" }, "example": "stripe.com" }, { "name": "linkedin", "in": "query", "description": "LinkedIn company URL", "required": false, "schema": { "type": "string" }, "example": "https://linkedin.com/company/stripe" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase organization URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/organization/stripe" }, { "name": "page", "in": "query", "description": "Page number (0-based)", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 0 }, { "name": "page_size", "in": "query", "description": "Number of results per page (1-500)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10 }, "example": 10 } ], "responses": { "200": { "description": "Successful response with deals for the company", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyDeal" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of deals for this company", "example": 11 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 10 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (missing, multiple, or invalid identifier)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_IDENTIFIER", "MULTIPLE_IDENTIFIERS", "INVALID_PARAMETER", "INVALID_DOMAIN", "INVALID_LINKEDIN_URL", "INVALID_CRUNCHBASE_URL", "INVALID_PAGE", "INVALID_PAGE_SIZE" ], "example": "MISSING_IDENTIFIER" }, "message": { "type": "string", "example": "An identifier parameter is required" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Provide one of: domain, linkedin, or crunchbase. Example: ?domain=stripe.com" } } } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "404": { "description": "No company found matching the provided identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ], "example": "NOT_FOUND" }, "message": { "type": "string", "example": "No company found matching the provided identifier" }, "details": { "type": "object", "properties": { "identifier_type": { "type": "string", "example": "domain" }, "identifier_value": { "type": "string", "example": "nonexistent.com" } } } } } } } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/company/search": { "get": { "summary": "Search for a company by name, domain, LinkedIn, or Crunchbase", "description": "Use this endpoint primarily to resolve a fuzzy company name or an uncertain\nidentifier into matching company records. If a reliable domain or LinkedIn URL is\nalready available, skip this search and pass it directly to `GET /company` for one\nfull profile or to `POST /companies` for a batch lookup.\n\nExactly one parameter must be provided.\n\n**Search types:**\n- `name` \u2014 Fuzzy name search with relevance scoring\n- `domain` \u2014 Company domain or full URL\n- `linkedin` \u2014 LinkedIn company URL\n- `crunchbase` \u2014 Crunchbase organization URL\n\nExamples:\n- `?linkedin=https://linkedin.com/company/stripe`\n- `?crunchbase=https://crunchbase.com/organization/notion`\n", "operationId": "searchCompany", "parameters": [ { "name": "name", "in": "query", "description": "Fuzzy search by company name", "required": false, "schema": { "type": "string" }, "example": "stripe" }, { "name": "domain", "in": "query", "description": "Company domain or full URL (e.g., \"stripe.com\" or \"https://stripe.com\") \u2014 URLs are automatically parsed to extract the domain", "required": false, "schema": { "type": "string" }, "example": "stripe.com" }, { "name": "linkedin", "in": "query", "description": "LinkedIn company URL", "required": false, "schema": { "type": "string" }, "example": "https://linkedin.com/company/stripe" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase organization URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/organization/notion" } ], "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySearchResult" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Number of companies returned", "example": 1 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 0 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (missing, multiple, or invalid parameters)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_SEARCH_PARAMS", "MULTIPLE_SEARCH_PARAMS", "EMPTY_SEARCH_TERM", "INVALID_DOMAIN", "INVALID_LINKEDIN_URL", "INVALID_CRUNCHBASE_URL" ], "example": "MULTIPLE_SEARCH_PARAMS" }, "message": { "type": "string", "example": "Only one search parameter is allowed at a time" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "You provided: name, domain. Please use only one of: name, domain, linkedin, or crunchbase" } } } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/companies": { "post": { "summary": "Discover companies with metadata and full latest-deal details", "description": "Use this endpoint by default for company sourcing and discovery. It returns company\nmetadata such as name and domain together with the full details of each company's\nlatest funding round.\n\nFilters inside `latest_deal` apply only to the company's most recent round. Use\n`POST /deals` instead when deal criteria must match any round in a company's history.\nFor example, `/companies` is appropriate for \"find AI companies in San Francisco\nwhose latest round was Seed\"; `/deals` is appropriate for \"analyze all Seed rounds\nannounced last year,\" regardless of whether Seed is now the company's latest round.\n\nFilters inside `investors` can match investor participation across all rounds.\n\n## Request Body Structure\nSend a JSON body with up to 4 filter sections plus pagination/sort at the top level:\n- `identifiers` - Look up specific companies by UUID, domain, LinkedIn, or Crunchbase\n- `company` - Filter by company attributes (search, location, industry, size, etc.)\n- `latest_deal` - Filter by latest funding round attributes (type, size, date, investors)\n- `investors` - Filter by investors (firms or people) across all rounds\n", "operationId": "searchCompanies", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "example": { "page_size": 10 }, "properties": { "identifiers": { "type": "object", "description": "Look up specific companies by identifier", "properties": { "ids": { "type": "array", "description": "Company UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "97ae048e-77bc-471b-821a-f9decb373689" ] }, "domains": { "type": "array", "description": "Company domains (max 100)", "items": { "type": "string" }, "example": [ "stripe.com", "airbnb.com" ] }, "linkedin_urls": { "type": "array", "description": "LinkedIn company URLs (max 100)", "items": { "type": "string" }, "example": [ "https://linkedin.com/company/stripe", "https://linkedin.com/company/airbnb" ] }, "crunchbase_urls": { "type": "array", "description": "Crunchbase organization URLs (max 100)", "items": { "type": "string" }, "example": [ "https://crunchbase.com/organization/stripe", "https://crunchbase.com/organization/airbnb" ] } } }, "company": { "type": "object", "description": "Company attribute filters", "properties": { "search_query": { "type": "string", "description": "AI-powered semantic search \u2014 a flexible replacement for an industry tag. First use /industry/search and apply an `industries` or `super_categories` filter when the taxonomy contains the intended category. Use semantic search only for a niche industry or specific product type the taxonomy cannot express, describing what the company does \u2014 its product, technology, or business model (e.g. \"AI-powered medical imaging diagnostics\" or \"vertical SaaS for dental practices\"). Do NOT use it for other attributes like stage, location, funding, or employee count \u2014 apply those with the dedicated filter fields instead. Results include a similarity score, are sorted by relevance, and are capped at 150 semantic matches.", "example": "AI-powered medical imaging diagnostics software" }, "min_relevance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity threshold (0-1). Only applies with search_query.", "example": 0.5 }, "locations": { "type": "array", "description": "Location permalinks. Use /location/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "san-francisco-california", "california" ] }, "industries": { "type": "array", "description": "Industry permalinks. Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "artificial-intelligence", "fintech-e067" ] }, "super_categories": { "type": "array", "description": "Super category permalinks (automatically includes related industries). Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "artificial-intelligence-e551" ] }, "employee_count": { "type": "array", "description": "Employee count ranges. Valid: 1-10, 11-50, 51-100, 101-250, 251-500, 501-1000, 1001-5000, 5001-10000, 10001+", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "1-10", "11-50" ] }, "ipo_status": { "type": "array", "description": "IPO status filter. Valid: public, private", "items": { "type": "string", "enum": [ "public", "private" ] }, "example": [ "private" ] }, "total_raised_min": { "type": "number", "minimum": 0, "description": "Minimum total raised (USD)", "example": 10000000 }, "total_raised_max": { "type": "number", "minimum": 0, "description": "Maximum total raised (USD)", "example": 500000000 } } }, "latest_deal": { "type": "object", "description": "Latest funding round filters", "properties": { "financing_types": { "type": "array", "description": "Financing types with optional modifiers (pre, extension)", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND" ] }, "pre": { "type": "boolean", "default": false, "description": "Pre-round modifier (e.g., Pre-Seed, Pre-Series A)" }, "extension": { "type": "boolean", "default": false, "description": "Extension round modifier" } } }, "example": [ { "type": "SEED", "pre": true }, { "type": "SERIES_A" } ] }, "size_min": { "type": "number", "minimum": 0, "description": "Minimum deal size (USD)", "example": 1000000 }, "size_max": { "type": "number", "minimum": 0, "description": "Maximum deal size (USD)", "example": 100000000 }, "date_start": { "type": "string", "format": "date", "description": "Latest deal after this date (ISO 8601)", "example": "2024-01-01" }, "date_end": { "type": "string", "format": "date", "description": "Latest deal before this date (ISO 8601)", "example": "2024-12-31" }, "created_start": { "type": "string", "format": "date", "description": "Latest deal record added to the system on or after this date (ISO 8601). Filters by ingestion date (`created_at`), not the announcement date \u2014 useful for finding rounds newly added to Fundable.", "example": "2024-01-01" }, "created_end": { "type": "string", "format": "date", "description": "Latest deal record added to the system on or before this date (ISO 8601). Filters by ingestion date (`created_at`), not the announcement date.", "example": "2024-12-31" }, "investor_ids": { "type": "array", "description": "Filter by investors who participated in the latest deal only", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" ] } } }, "investors": { "type": "object", "description": "Filter by investors (firms or people) across all funding rounds", "properties": { "investor_ids": { "type": "array", "description": "Investor UUIDs \u2014 matches companies where these investors participated in any round ever", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" ] }, "people_ids": { "type": "array", "description": "Person UUIDs \u2014 matches companies where any of these people participated in any round\nas an **angel investor** OR as a **lead partner** of an investing firm.\nResolve via `/people/{id}`.\n", "items": { "type": "string", "format": "uuid" }, "example": [ "b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a" ] } } }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Page number (0-based)" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10, "description": "Number of results per page" }, "sort_by": { "type": "string", "enum": [ "most_recent_raise", "oldest_raise", "most_recent_founded", "oldest_founded", "largest_valuation", "smallest_valuation", "largest_total_raise", "smallest_total_raise", "most_funding_rounds", "most_investors" ], "default": "most_recent_raise", "description": "Sort order. Ignored when search_query is provided (sorted by relevance)." } } }, "examples": { "empty": { "summary": "Empty request (no filters)", "value": { "page_size": 5 } }, "filter_only": { "summary": "Filter by IPO status and industry", "value": { "company": { "ipo_status": [ "private" ], "industries": [ "artificial-intelligence" ] }, "latest_deal": { "financing_types": [ { "type": "SERIES_A" }, { "type": "SERIES_B" } ] }, "page_size": 10 } }, "semantic_search": { "summary": "AI-powered semantic search", "value": { "company": { "search_query": "AI healthcare diagnostics startups" }, "page_size": 5 } }, "batch_lookup": { "summary": "Look up specific companies by domain", "value": { "identifiers": { "domains": [ "stripe.com", "airbnb.com", "notion.so" ] } } } } } } }, "responses": { "200": { "description": "Successful response with companies data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyListItem" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of companies matching the filter criteria", "example": 1547 }, "page": { "type": "integer", "description": "Current page number (0-based)", "example": 0 }, "page_size": { "type": "integer", "description": "Number of results per page", "example": 10 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Bad Request - Invalid parameter types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesValidationError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "422": { "description": "Unprocessable Entity - Unknown parameter provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesValidationError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/investors": { "post": { "summary": "Discover investor firms by their attributes and investments", "description": "Use this endpoint when the requested result is a list of investor firms. Filters\nunder `company_investments` identify qualifying portfolio companies and deals, then\nreturn the firms that participated in those deals. For example, use this route to\nfind San Francisco-based investors that participated in a Seed round during the\nlast year.\n\nUse `POST /people` with investor filters instead when the desired result is an\nindividual angel investor or lead partner attached to a firm. Use `POST /deals`\nwhen the desired result is the matching funding rounds themselves.\n\n## Request Body Structure\nSend a JSON body with up to 3 filter sections plus pagination/sort at the top level:\n- `identifiers` - Look up specific investors by UUID, domain, LinkedIn, or Crunchbase\n- `investor` - Filter by investor entity attributes (location, employee count)\n- `company_investments` - Filter by portfolio (industries, deal characteristics, etc.). Supports semantic search via `search_query` + `min_relevance`.\n\nWhen `company_investments` filters are active, `filtered_deal_count` is the number\nof deals that matched those filters and `filtered_lead_count` is the number of those\nmatched deals the investor led.\n", "operationId": "listInvestors", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "example": { "page_size": 10 }, "properties": { "identifiers": { "type": "object", "description": "Investor lookup filters (OR'd together)", "properties": { "ids": { "type": "array", "description": "Investor UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" ] }, "domains": { "type": "array", "description": "Investor domains (max 100)", "items": { "type": "string" }, "example": [ "sequoiacap.com", "a16z.com" ] }, "linkedin_urls": { "type": "array", "description": "Investor LinkedIn URLs (max 100)", "items": { "type": "string" }, "example": [ "https://linkedin.com/company/sequoia-capital", "https://linkedin.com/company/andreessen-horowitz" ] }, "crunchbase_urls": { "type": "array", "description": "Investor Crunchbase URLs (max 100)", "items": { "type": "string" }, "example": [ "https://crunchbase.com/organization/sequoia-capital", "https://crunchbase.com/organization/andreessen-horowitz" ] } } }, "investor": { "type": "object", "description": "Investor entity-level filters", "properties": { "locations": { "type": "array", "description": "Investor HQ location permalinks. Use /location/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "san-francisco-california", "menlo-park-california" ] }, "employee_count": { "type": "array", "description": "Investor firm employee count ranges", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "11-50", "51-100" ] } } }, "company_investments": { "type": "object", "description": "Portfolio filters (filter by companies the investor has invested in)", "properties": { "company_ids": { "type": "array", "description": "Portfolio company UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "97ae048e-77bc-471b-821a-f9decb373689" ] }, "search_query": { "type": "string", "description": "AI-powered semantic search matched against each investor's\nportfolio companies \u2014 a flexible replacement for an industry tag.\nFirst use /industry/search and apply an `industries` or\n`super_categories` filter when the taxonomy contains the intended\ncategory. Use semantic search only for a niche industry or specific\nproduct type the taxonomy cannot express, describing what those\ncompanies do \u2014 their product, technology, or business model (e.g.\n\"climate-focused carbon capture hardware\"). Do NOT use it for other\nattributes like stage, location, or funding \u2014 apply those with the\ndedicated `company_investments` and `investor` filter fields instead.\nResults are ranked by portfolio relevance and capped at 150 semantic\nmatches.\n", "example": "climate-focused carbon capture hardware" }, "min_relevance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum relevance score threshold (0\u20131) for the portfolio-based\nsemantic search. Only applies when `search_query` is provided.\nInvestors whose portfolio match score falls below this threshold\nare excluded. Defaults to 0 (return all results).\n", "example": 0.5 }, "locations": { "type": "array", "description": "Portfolio company location permalinks. Use /location/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "san-francisco-california" ] }, "industries": { "type": "array", "description": "Portfolio company industry permalinks. Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "artificial-intelligence", "fintech-e067" ] }, "super_categories": { "type": "array", "description": "Broad industry super-category permalinks. Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "financial-services-d7b6" ] }, "employee_count": { "type": "array", "description": "Portfolio company employee count ranges", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "11-50", "51-100" ] }, "ipo_status": { "type": "array", "description": "Portfolio company IPO status", "items": { "type": "string", "enum": [ "public", "private" ] }, "example": [ "private" ] }, "total_raised_min": { "type": "number", "minimum": 0, "description": "Minimum total raised by portfolio companies (USD)", "example": 10000000 }, "total_raised_max": { "type": "number", "minimum": 0, "description": "Maximum total raised by portfolio companies (USD)", "example": 500000000 }, "financing_types": { "type": "array", "description": "Financing types with optional modifiers (pre, extension)", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND" ] }, "pre": { "type": "boolean", "default": false, "description": "Pre-round modifier (e.g., Pre-Seed, Pre-Series A)" }, "extension": { "type": "boolean", "default": false, "description": "Extension round modifier" } } }, "example": [ { "type": "SERIES_A" }, { "type": "SERIES_B" } ] }, "deal_size_min": { "type": "number", "minimum": 0, "description": "Minimum deal size (USD)", "example": 1000000 }, "deal_size_max": { "type": "number", "minimum": 0, "description": "Maximum deal size (USD)", "example": 100000000 }, "deal_start_date": { "type": "string", "format": "date", "description": "Filter deals on or after this date (ISO 8601)", "example": "2023-01-01" }, "deal_end_date": { "type": "string", "format": "date", "description": "Filter deals on or before this date (ISO 8601)", "example": "2024-12-31" }, "only_lead_deals": { "type": "boolean", "default": false, "description": "When true, only count deals where investor was lead" }, "min_matching_deals": { "type": "integer", "minimum": 1, "description": "Minimum number of deals matching the portfolio filters", "example": 3 } } }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Page number (0-based)" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10, "description": "Number of results per page (max 500)" }, "sort_by": { "type": "string", "enum": [ "most_recent_deal", "recent_deals", "deals_led_ltm", "total_deals", "matching_deals" ], "default": "most_recent_deal", "description": "Sort order for results.\n- **most_recent_deal** \u2014 Date of most recent investment (newest first)\n- **recent_deals** \u2014 Deals in last 12 months (highest first)\n- **deals_led_ltm** \u2014 Lead deals in last 12 months (highest first)\n- **total_deals** \u2014 All-time deal count (highest first)\n- **matching_deals** \u2014 Deals matching portfolio filters (highest first)\n" } } }, "examples": { "empty": { "summary": "Empty request (no filters)", "value": { "page_size": 5 } }, "filter_only": { "summary": "Investors in SF investing in AI Series A/B rounds", "value": { "investor": { "locations": [ "san-francisco-california" ] }, "company_investments": { "industries": [ "artificial-intelligence" ], "financing_types": [ { "type": "SERIES_A" }, { "type": "SERIES_B" } ], "deal_start_date": "2023-01-01" }, "page": 0, "page_size": 25, "sort_by": "most_recent_deal" } }, "batch_lookup": { "summary": "Look up specific investors by domain", "value": { "identifiers": { "domains": [ "sequoiacap.com", "a16z.com" ] } } }, "semantic_search": { "summary": "Semantic search for climate-focused investors with AI portfolio", "value": { "company_investments": { "search_query": "climate-focused deep tech startups" }, "page": 0, "page_size": 25 } }, "lead_investors_recent": { "summary": "Active lead investors with at least 3 matching deals", "value": { "company_investments": { "industries": [ "fintech" ], "only_lead_deals": true, "min_matching_deals": 3, "deal_start_date": "2024-01-01" }, "sort_by": "deals_led_ltm", "page_size": 50 } } } } } }, "responses": { "200": { "description": "Successful response with paginated investor list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "investors": { "type": "array", "items": { "$ref": "#/components/schemas/InvestorListItem" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of investors matching filters", "example": 142 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 25 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (invalid values)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParameterValidationError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "422": { "description": "Unknown parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParameterValidationError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/investor": { "get": { "summary": "Get investor details and statistics by identifier", "description": "Use this endpoint when one investor firm is already identified and its full profile,\nstatistics, and portfolio summary are required. Prefer a domain or LinkedIn URL when\navailable; it can be passed directly without calling `/investor/search` first.\n\nUse `/investor/search` for fuzzy firm-name resolution or an uncertain identifier.\nUse `POST /investors` to discover or batch-retrieve multiple investor firms.\n\nProvide ONE of the following query parameters to identify the investor:\n- `id` - Investor UUID\n- `domain` - Investor domain or full URL (e.g., \"sequoiacap.com\" or \"https://sequoiacap.com\")\n- `linkedin` - LinkedIn company URL\n- `crunchbase` - Crunchbase organization URL\n\nThe response includes the investor's statistics, portfolio summary, and profile links.\n", "operationId": "getInvestorByIdentifier", "parameters": [ { "name": "id", "in": "query", "description": "Investor UUID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "domain", "in": "query", "description": "Investor domain or full URL (e.g., \"sequoiacap.com\" or \"https://sequoiacap.com\") \u2014 URLs are automatically parsed to extract the domain", "required": false, "schema": { "type": "string" }, "example": "sequoiacap.com" }, { "name": "linkedin", "in": "query", "description": "LinkedIn company URL", "required": false, "schema": { "type": "string" }, "example": "https://linkedin.com/company/sequoia-capital" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase organization URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/organization/sequoia-capital" } ], "responses": { "200": { "description": "Successful response with investor data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "investor": { "$ref": "#/components/schemas/Investor" } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (missing or invalid identifier)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParameterValidationError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "404": { "description": "Investor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestorsNotFoundError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/investor/deals": { "get": { "summary": "Get deals for an investor by identifier", "description": "Use this endpoint when an investor firm is already identified and its complete deal\nhistory is required. Prefer a domain or LinkedIn URL when available; it can be passed\ndirectly without calling `/investor/search` first.\n\nUse `POST /investors` instead to discover firms from investment criteria, or\n`POST /deals` when the desired result is a filtered list of funding rounds.\n\nProvide ONE of the following query parameters to identify the investor:\n- `id` - Investor UUID\n- `domain` - Investor domain or full URL (e.g., \"sequoiacap.com\" or \"https://sequoiacap.com\")\n- `linkedin` - LinkedIn company URL\n- `crunchbase` - Crunchbase organization URL\n\nThe response includes the investor's deals with pagination. If the identifier matches multiple investors (e.g., a16z has multiple firms), deals from all matches are returned together.\n", "operationId": "getInvestorDeals", "parameters": [ { "name": "id", "in": "query", "description": "Investor UUID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "domain", "in": "query", "description": "Investor domain or full URL (e.g., \"sequoiacap.com\" or \"https://sequoiacap.com\") \u2014 URLs are automatically parsed to extract the domain", "required": false, "schema": { "type": "string" }, "example": "sequoiacap.com" }, { "name": "linkedin", "in": "query", "description": "LinkedIn company URL", "required": false, "schema": { "type": "string" }, "example": "https://linkedin.com/company/sequoia-capital" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase organization URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/organization/sequoia-capital" }, { "name": "page", "in": "query", "description": "Page number (0-based)", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 0 }, { "name": "page_size", "in": "query", "description": "Number of results per page (1-500)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10 }, "example": 10 } ], "responses": { "200": { "description": "Successful response with deals for the investor", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/InvestorDeal" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of deals for this investor", "example": 247 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 10 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 10 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (missing, multiple, or invalid identifier)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_IDENTIFIER", "MULTIPLE_IDENTIFIERS", "INVALID_PARAMETER", "INVALID_DOMAIN", "INVALID_LINKEDIN_URL", "INVALID_CRUNCHBASE_URL", "INVALID_PAGE", "INVALID_PAGE_SIZE" ], "example": "MISSING_IDENTIFIER" }, "message": { "type": "string", "example": "An identifier parameter is required" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Provide one of: domain, linkedin, or crunchbase. Example: ?domain=sequoiacap.com" } } } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "404": { "description": "No investor found matching the provided identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND" ], "example": "NOT_FOUND" }, "message": { "type": "string", "example": "No investor found matching the provided identifier" }, "details": { "type": "object", "properties": { "identifier_type": { "type": "string", "example": "domain" }, "identifier_value": { "type": "string", "example": "nonexistent.com" } } } } } } } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/investor/search": { "get": { "summary": "Search investors by name, domain, LinkedIn, or Crunchbase", "description": "Use this endpoint primarily to resolve a fuzzy investor-firm name or an uncertain\nidentifier. If a reliable domain or LinkedIn URL is already available, skip this\nsearch and pass it directly to `GET /investor` for one full profile or to\n`POST /investors` for a batch lookup.\n\nExactly one parameter must be provided.\n\n**Search types:**\n- `name` \u2014 Fuzzy name search with relevance scoring\n- `domain` \u2014 Investor domain or full URL\n- `linkedin` \u2014 LinkedIn company URL\n- `crunchbase` \u2014 Crunchbase organization URL\n\nIdentifier lookups (`domain`, `linkedin`, `crunchbase`) return `relevance_score: 1`.\nExamples:\n- `?linkedin=https://linkedin.com/company/sequoia-capital`\n- `?crunchbase=https://crunchbase.com/organization/sequoia-capital`\n", "operationId": "searchInvestors", "parameters": [ { "name": "name", "in": "query", "description": "Investor name (fuzzy search with relevance scoring)", "required": false, "schema": { "type": "string" }, "example": "sequoia" }, { "name": "domain", "in": "query", "description": "Investor domain or full URL (e.g., \"sequoiacap.com\" or \"https://sequoiacap.com\") \u2014 URLs are automatically parsed to extract the domain", "required": false, "schema": { "type": "string" }, "example": "sequoiacap.com" }, { "name": "linkedin", "in": "query", "description": "LinkedIn company URL", "required": false, "schema": { "type": "string" }, "example": "https://linkedin.com/company/sequoia-capital" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase organization URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/organization/sequoia-capital" } ], "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "investors": { "type": "array", "items": { "$ref": "#/components/schemas/InvestorSearchResult" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Number of investors returned", "example": 8 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 0 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] }, "example": { "success": true, "data": { "investors": [ { "id": "770e8400-e29b-41d4-a716-446655440000", "guru_permalink": "acme-ventures", "name": "Acme Ventures", "description": "Early-stage venture capital firm focused on AI startups", "image": "https://example.com/acme-ventures-logo.png", "relevance_score": 0.92, "domain": "acmeventures.com", "website": "https://acmeventures.com" }, { "id": "880e8400-e29b-41d4-a716-446655440001", "guru_permalink": "acme-capital", "name": "Acme Capital", "description": "Growth-stage investment firm", "image": "https://example.com/acme-capital-logo.png", "relevance_score": 0.85, "domain": "acmecap.com", "website": "https://acmecap.com" } ] }, "meta": { "total_count": 2, "page": 0, "page_size": 1, "credits_used": 0 } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_SEARCH_PARAMS", "MULTIPLE_SEARCH_PARAMS", "EMPTY_SEARCH_TERM", "INVALID_DOMAIN", "INVALID_LINKEDIN_URL", "INVALID_CRUNCHBASE_URL" ], "example": "MISSING_SEARCH_PARAMS" }, "message": { "type": "string", "example": "At least one search parameter is required" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Provide one of: name, domain, linkedin, or crunchbase. Example: ?name=sequoia or ?domain=sequoiacap.com" }, "provided": { "type": "string", "nullable": true }, "examples": { "type": "object", "nullable": true, "properties": { "valid": { "type": "array", "items": { "type": "string" } }, "invalid": { "type": "array", "items": { "type": "string" } } } } } } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/people": { "post": { "summary": "Discover founders, employees, angels, and lead investors", "description": "Use this endpoint when the requested result is a list of people.\n\nWith `person_type: company`, it returns founders, executives, or employees based on\ntheir current employer. Filters under `company.latest_deal` apply only to that\nemployer's latest funding round, like `POST /companies`; funding information is used\nfor filtering but is not included in the returned person record. For example, use\nthis mode to find founders of AI companies in San Francisco whose latest round was\nSeries A.\n\nWith `person_type: investor`, it applies investment and portfolio filters in the same\nway that `POST /investors` does, but returns individual angel investors or lead\npartners attached to their firms rather than firm records. Use `POST /investors`\nwhen the desired result is firms, and `POST /deals` when it is funding rounds.\n\n## Request Body Structure\nSend a JSON body with up to 4 filter sections plus pagination/sort at the top level:\n- `identifiers` - Look up specific people by UUID, LinkedIn, Crunchbase, or Twitter\n- `person` - Filter by person attributes (role, contact info, job title, education, prior employers)\n- `company` - Filter by current employer attributes (industry, location, funding, IPO status, etc.)\n- `investor` - Filter by investor activity (firm, deal characteristics, portfolio companies)\n", "operationId": "searchPeople", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "example": { "page_size": 10 }, "properties": { "person_type": { "type": "string", "enum": [ "company", "investor", "any" ], "default": "any", "description": "Restrict results to one population. `company` returns only people with a\ncurrent employer (founders, executives, employees). `investor` returns only\npeople who invest. `any` (default) returns the union \u2014 anyone matching the\nother filter blocks regardless of population.\n", "example": "company" }, "identifiers": { "type": "object", "description": "Look up specific people by identifier", "properties": { "ids": { "type": "array", "description": "Person UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "550e8400-e29b-41d4-a716-446655440000" ] }, "linkedin_urls": { "type": "array", "description": "LinkedIn person URLs (max 100)", "items": { "type": "string" }, "example": [ "https://linkedin.com/in/jane-doe-12345", "https://linkedin.com/in/john-smith" ] }, "crunchbase_urls": { "type": "array", "description": "Crunchbase person URLs (max 100)", "items": { "type": "string" }, "example": [ "https://crunchbase.com/person/jane-doe", "https://www.crunchbase.com/person/john-smith" ] }, "twitter_urls": { "type": "array", "description": "Twitter/X URLs (max 100)", "items": { "type": "string" }, "example": [ "https://x.com/janedoe", "https://x.com/johnsmith" ] } } }, "person": { "type": "object", "description": "Person attribute filters", "properties": { "roles": { "type": "array", "description": "Person's role at their current employer", "items": { "type": "string", "enum": [ "founder", "ceo", "key_person" ] }, "example": [ "founder", "ceo" ] }, "contact_types": { "type": "array", "description": "Available contact info on the person", "items": { "type": "string", "enum": [ "linkedin", "email", "phone", "twitter" ] }, "example": [ "email", "linkedin" ] }, "job_titles": { "type": "array", "description": "Normalized job-title keys", "items": { "type": "string" }, "example": [ "ceo", "cto", "vp-engineering" ] }, "education_schools": { "type": "array", "description": "Education institution IDs", "items": { "type": "string" }, "example": [ "stanford-university", "mit" ] }, "linkedin_companies": { "type": "array", "description": "Filter by previous/current employer LinkedIn company IDs", "items": { "type": "string" }, "example": [ "google", "meta" ] } } }, "company": { "type": "object", "description": "Current-employer attribute filters. Setting any field implicitly requires the person to have a current employer.", "properties": { "search_query": { "type": "string", "description": "AI-powered semantic search against the person's current employer \u2014 a flexible replacement for an industry tag. First use /industry/search and apply an `industries` or `super_categories` filter when the taxonomy contains the intended category. Use semantic search only for a niche industry or product type the taxonomy cannot express, describing what that company does \u2014 its product, technology, or business model (e.g. \"climate tech carbon accounting software\"). Do NOT use it for stage, location, or funding \u2014 apply dedicated filters instead. Results are ordered by relevance and capped at 150 semantic matches.", "example": "climate tech carbon accounting software" }, "min_relevance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity threshold (0-1). Only applies with search_query.", "example": 0.5 }, "ids": { "type": "array", "description": "Filter by current-employer UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "660e8400-e29b-41d4-a716-446655440000" ] }, "locations": { "type": "array", "description": "Location permalinks. Use /location/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "san-francisco-california", "new-york-new-york" ] }, "industries": { "type": "array", "description": "Industry permalinks. Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "artificial-intelligence", "fintech-e067" ] }, "super_categories": { "type": "array", "description": "Super category permalinks (auto-includes related industries). Use /industry/search to find permalinks. A value that is not an exact permalink is silently ignored (returns zero results, no error).", "items": { "type": "string" }, "example": [ "financial-services-d7b6" ] }, "employee_count": { "type": "array", "description": "Current-employer headcount ranges", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "11-50", "51-100" ] }, "ipo_status": { "type": "array", "description": "Current-employer IPO status", "items": { "type": "string", "enum": [ "public", "private", "acquired", "delisted" ] }, "example": [ "private" ] }, "total_raised_min": { "type": "number", "minimum": 0, "description": "Minimum total raised by current employer (USD)", "example": 1000000 }, "total_raised_max": { "type": "number", "minimum": 0, "description": "Maximum total raised by current employer (USD)", "example": 100000000 }, "investor_people_ids": { "type": "array", "description": "Person UUIDs \u2014 filter to people whose current employer has ever raised\nfrom any of these people as an **angel investor** OR as a **lead partner**\nof an investing firm. Resolve via `/people/{id}`.\n", "items": { "type": "string", "format": "uuid" }, "example": [ "b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a" ] }, "latest_deal": { "type": "object", "description": "Nested. Filters on the current employer's most recent funding round.", "properties": { "financing_types": { "type": "array", "description": "Financing types with optional modifiers (pre, extension)", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND" ] }, "pre": { "type": "boolean", "default": false }, "extension": { "type": "boolean", "default": false } } }, "example": [ { "type": "SEED", "pre": true }, { "type": "SERIES_A" } ] }, "size_min": { "type": "number", "minimum": 0, "description": "Minimum latest-deal size (USD)", "example": 1000000 }, "size_max": { "type": "number", "minimum": 0, "description": "Maximum latest-deal size (USD)", "example": 50000000 }, "date_start": { "type": "string", "format": "date", "example": "2024-01-01" }, "date_end": { "type": "string", "format": "date", "example": "2024-12-31" }, "investor_ids": { "type": "array", "description": "Filter to deals where these investor UUIDs participated", "items": { "type": "string", "format": "uuid" }, "example": [ "770e8400-e29b-41d4-a716-446655440000" ] }, "investor_locations": { "type": "array", "description": "Filter to deals with investors HQ'd in these locations", "items": { "type": "string" }, "example": [ "san-francisco-california" ] } } } } }, "investor": { "type": "object", "description": "Filters on the investor entity (firm) and on the person's deal activity.\nSetting any field (including any nested `deals.*` field) implicitly requires\nthe person to be an investor.\n", "properties": { "ids": { "type": "array", "description": "Firm (parent investor) UUIDs", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" ] }, "domains": { "type": "array", "description": "Firm domains (max 100)", "items": { "type": "string" }, "example": [ "sequoiacap.com", "a16z.com" ] }, "linkedin_urls": { "type": "array", "description": "Firm LinkedIn URLs (max 100)", "items": { "type": "string" }, "example": [ "https://linkedin.com/company/sequoia-capital" ] }, "crunchbase_urls": { "type": "array", "description": "Firm Crunchbase URLs (max 100)", "items": { "type": "string" }, "example": [ "https://crunchbase.com/organization/sequoia-capital" ] }, "permalinks": { "type": "array", "description": "Fundable firm permalinks (max 100)", "items": { "type": "string" }, "example": [ "sequoia-capital", "andreessen-horowitz" ] }, "locations": { "type": "array", "description": "Firm HQ location permalinks", "items": { "type": "string" }, "example": [ "menlo-park-california" ] }, "employee_count": { "type": "array", "description": "Firm headcount ranges", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] } }, "deals": { "type": "object", "description": "Nested. Combined deal-activity and portfolio-company filters. Includes:\ndeal-level controls (`investment_type`, `min_matching_deals`, `only_lead_deals`),\nround-level filters (`financing_types`, `size_min/max`, `date_start/end`), and\nportfolio-company attributes (`industries`, `super_categories`,\n`portfolio_locations`, `portfolio_employee_count`, `ipo_status`,\n`total_raised_min/max`, plus semantic `search_query` / `min_relevance`).\n", "properties": { "search_query": { "type": "string", "description": "AI-powered semantic search against the person's portfolio companies \u2014 a flexible replacement for an industry tag. First use /industry/search and apply an `industries` or `super_categories` filter when the taxonomy contains the intended category. Use semantic search only for a niche industry or product type the taxonomy cannot express, describing what those companies do (e.g. \"AI infrastructure for model training\"). Do NOT use it for stage, location, or funding \u2014 apply dedicated filters instead. Results are ordered by relevance and capped at 150 semantic matches.", "example": "AI infrastructure for model training" }, "min_relevance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum similarity threshold (0-1). Only applies with search_query.", "example": 0.5 }, "investment_type": { "type": "string", "enum": [ "all", "angel", "institutional" ], "default": "all", "description": "Filter by whether the person invests as an angel, under a firm, or both", "example": "angel" }, "only_lead_deals": { "type": "boolean", "default": false, "description": "Only count deals where the person/firm was a lead investor" }, "min_matching_deals": { "type": "integer", "minimum": 1, "description": "Require at least this many deals to match the deal filters", "example": 3 }, "financing_types": { "type": "array", "description": "Financing types for the person's investment activity", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND" ] }, "pre": { "type": "boolean", "default": false }, "extension": { "type": "boolean", "default": false } } } }, "size_min": { "type": "number", "minimum": 0, "description": "Minimum deal size (USD) for the person's deal activity", "example": 500000 }, "size_max": { "type": "number", "minimum": 0, "description": "Maximum deal size (USD) for the person's deal activity", "example": 10000000 }, "date_start": { "type": "string", "format": "date", "example": "2023-01-01" }, "date_end": { "type": "string", "format": "date", "example": "2024-12-31" }, "industries": { "type": "array", "description": "Portfolio company industry permalinks", "items": { "type": "string" }, "example": [ "artificial-intelligence" ] }, "super_categories": { "type": "array", "description": "Portfolio company super-category permalinks", "items": { "type": "string" } }, "portfolio_locations": { "type": "array", "description": "Portfolio company location permalinks", "items": { "type": "string" } }, "portfolio_employee_count": { "type": "array", "description": "Portfolio company headcount ranges", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] } }, "ipo_status": { "type": "array", "description": "Portfolio company IPO status", "items": { "type": "string", "enum": [ "public", "private" ] } }, "total_raised_min": { "type": "number", "minimum": 0, "description": "Minimum total raised by the portfolio company (USD)", "example": 1000000 }, "total_raised_max": { "type": "number", "minimum": 0, "description": "Maximum total raised by the portfolio company (USD)" } } } } }, "page": { "type": "integer", "minimum": 0, "default": 0, "description": "Page number (0-based)" }, "page_size": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10, "description": "Number of results per page (max 500)" }, "sort_by": { "type": "string", "enum": [ "most_recent_deal_date", "total_raised", "latest_deal_size", "name", "total_deal_count", "deal_count_last_12_months", "lead_deal_count", "lead_deal_count_last_12_months", "filtered_deal_count" ], "default": "most_recent_deal_date", "description": "Sort order. All values are universally accepted \u2014 non-applicable values (e.g. `lead_deal_count`\nwhen no investor filter is set) resolve to 0 / null via COALESCE and naturally sort to the bottom (DESC).\nIgnored when `company.search_query` or `investor.deals.search_query` is set (results are then\nordered by semantic relevance).\n" } } }, "examples": { "empty": { "summary": "Empty request (no filters)", "value": { "page_size": 5 } }, "filter_only": { "summary": "Founders at private financial-services companies", "value": { "person": { "roles": [ "founder" ] }, "company": { "ipo_status": [ "private" ], "super_categories": [ "financial-services-d7b6" ] }, "page_size": 25 } }, "batch_lookup": { "summary": "Look up specific people by LinkedIn URL", "value": { "identifiers": { "linkedin_urls": [ "https://www.linkedin.com/in/joshua-kushner-711b45230/", "https://www.linkedin.com/in/eladgil/" ] } } }, "angel_investors_active_2024": { "summary": "People who made at least 3 angel investments in 2024", "value": { "investor": { "deals": { "investment_type": "angel", "min_matching_deals": 3, "date_start": "2024-01-01", "date_end": "2024-12-31" } }, "sort_by": "lead_deal_count", "page_size": 50 } } } } } }, "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "description": "Optional friendly message (e.g. \"No people found matching your filters\" when empty)" }, "data": { "type": "object", "properties": { "people": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSearchResult" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of people matching the filter criteria", "example": 1250 }, "page": { "type": "integer", "description": "Current page number (0-based)", "example": 0 }, "page_size": { "type": "integer", "description": "Number of results per page", "example": 25 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request", "example": 25 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Source of credits used (only included for non-API tier keys)", "example": "monthly" }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining monthly credits (only included for non-API tier keys)", "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (invalid types, dates, enums, or empty `search_query`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleValidationError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleAuthError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleInsufficientCreditsError" } } } }, "422": { "description": "Unknown parameter (per-block whitelist enforced)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnknownParamError" } } } }, "429": { "description": "Two distinct cases share this status:\n- `RATE_LIMIT_EXCEEDED` \u2014 per-minute API rate limit\n- `USAGE_LIMIT_EXCEEDED` \u2014 semantic-search monthly usage limit (only when `company.search_query` or `investor.deals.search_query` was set)\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PeopleRateLimitError" }, { "$ref": "#/components/schemas/SemanticUsageLimitError" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying (sent for `RATE_LIMIT_EXCEEDED` only)", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleServerError" } } } }, "504": { "description": "Semantic search timed out (only when `company.search_query` or `investor.deals.search_query` was set)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SemanticTimeoutError" } } } } } } }, "/person": { "get": { "summary": "Get person details by identifier", "description": "Use this endpoint when one person is already identified and their full profile is\nrequired. Prefer a LinkedIn URL when available; it can be passed directly without\ncalling `/person/search` first.\n\nUse `/person/search` for fuzzy name resolution or an uncertain identifier. Use\n`POST /people` to discover or batch-retrieve multiple people.\n\nProvide ONE of the following query parameters to identify the person:\n- `id` - Person UUID\n- `linkedin` - LinkedIn person URL\n- `crunchbase` - Crunchbase person URL\n- `twitter` - Twitter/X URL\n\nReturns the same constant unified shape as the list endpoint, with **full**\nemployment and education history (no per-section limit).\n", "operationId": "getPerson", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Person UUID", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "linkedin", "in": "query", "required": false, "description": "LinkedIn person URL", "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/eladgil/" }, { "name": "crunchbase", "in": "query", "required": false, "description": "Crunchbase person URL", "schema": { "type": "string" }, "example": "https://crunchbase.com/person/jane-doe" }, { "name": "twitter", "in": "query", "required": false, "description": "Twitter/X URL", "schema": { "type": "string" }, "example": "https://x.com/janedoe" } ], "responses": { "200": { "description": "Successful response with person data", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "required": [ "person" ], "properties": { "person": { "$ref": "#/components/schemas/PersonDetail" } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 1 }, "credits_used": { "type": "integer", "example": 1 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ] }, "monthly_credits_remaining": { "type": "integer", "nullable": true }, "purchased_credits_remaining": { "type": "integer", "nullable": true } } } } } } } }, "400": { "description": "Missing or invalid identifier (no query param provided, or invalid UUID / URL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidIdentifierError" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleAuthError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleInsufficientCreditsError" } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleNotFoundError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleRateLimitError" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleServerError" } } } } } } }, "/person/email": { "get": { "summary": "Unlock a person's verified email by identifier", "description": "Use this endpoint only when a verified email is explicitly required for an identified\nperson. Return a verified email for a person identified by UUID, LinkedIn, Crunchbase,\nor Twitter/X. Provide one identifier. If multiple identifiers are supplied, the\nendpoint uses the first non-empty value in this order: `id`, `linkedin`,\n`crunchbase`, `twitter`.\n\nA newly created unlock costs 5 credits. Repeating the request for an email the\nsame user already unlocked costs 0 credits. Unlock ownership persists across API\nkeys belonging to that user. Provider attribution is internal and is not returned.\n\nAvailable on non-trial Pro+ and Enterprise plans.\n", "operationId": "getPersonEmail", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Fundable person UUID", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "linkedin", "in": "query", "required": false, "description": "LinkedIn person URL, slug, or supported normalized identifier", "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/eladgil/" }, { "name": "crunchbase", "in": "query", "required": false, "description": "Crunchbase person URL or supported normalized identifier", "schema": { "type": "string" }, "example": "https://www.crunchbase.com/person/jane-doe" }, { "name": "twitter", "in": "query", "required": false, "description": "Twitter/X URL or handle", "schema": { "type": "string" }, "example": "https://x.com/janedoe" } ], "responses": { "200": { "description": "Verified email returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEmailResponse" } } } }, "400": { "description": "Missing or invalid person identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEmailError" }, "example": { "success": false, "error": { "code": "MISSING_IDENTIFIER", "message": "Person identifier is required", "details": { "help": "Provide id, linkedin, crunchbase, or twitter." } }, "statusCode": 400 } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleAuthError" } } } }, "402": { "description": "Insufficient credits or monthly email-unlock allowance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEmailError" }, "example": { "success": false, "error": { "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits to unlock this email", "details": { "credits_needed": 5, "monthly_credits_remaining": 0, "purchased_credits_remaining": 0 } }, "statusCode": 402 } } } }, "403": { "description": "Current subscription or trial status cannot unlock emails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEmailError" }, "example": { "success": false, "error": { "code": "UPGRADE_REQUIRED", "message": "Email unlocks require a Pro+ or Enterprise plan.", "details": { "current_tier": "Pro" } }, "statusCode": 403 } } } }, "404": { "description": "Person not found or no verified email available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEmailError" }, "examples": { "person_not_found": { "summary": "Person not found", "value": { "success": false, "error": { "code": "PERSON_NOT_FOUND", "message": "Person not found" }, "statusCode": 404 } }, "email_not_found": { "summary": "No verified email found", "value": { "success": false, "error": { "code": "EMAIL_NOT_FOUND", "message": "No verified email was found for this person" }, "statusCode": 404 } } } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleRateLimitError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleServerError" } } } } } } }, "/person/deals": { "get": { "summary": "Get deals a person participated in (as an investor) by identifier", "description": "Use this endpoint when a person is already identified and their investment history\nis required. It returns deals the person joined as an angel plus lead or firm deals.\nPrefer a LinkedIn URL when available; it can be passed directly without first calling\n`/person/search`.\n\nProvide ONE of the following query parameters to identify the person:\n- `id` - Person UUID\n- `linkedin` - LinkedIn person URL\n- `crunchbase` - Crunchbase person URL\n- `twitter` - Twitter/X URL\n\nThe response includes the person's investment deals with pagination.\n", "operationId": "getPersonDeals", "parameters": [ { "name": "id", "in": "query", "description": "Person UUID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "linkedin", "in": "query", "description": "LinkedIn person URL", "required": false, "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/eladgil/" }, { "name": "crunchbase", "in": "query", "description": "Crunchbase person URL", "required": false, "schema": { "type": "string" }, "example": "https://crunchbase.com/person/jane-doe" }, { "name": "twitter", "in": "query", "description": "Twitter/X URL", "required": false, "schema": { "type": "string" }, "example": "https://x.com/janedoe" }, { "name": "page", "in": "query", "description": "Page number (0-based)", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "example": 0 }, { "name": "page_size", "in": "query", "description": "Number of results per page (1-500)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 10 }, "example": 10 } ], "responses": { "200": { "description": "Successful response with the person's deals", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/PersonDeal" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "example": 11 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 10 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (missing or invalid identifier)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_IDENTIFIER", "INVALID_ID" ], "example": "MISSING_IDENTIFIER" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleAuthError" } } } }, "404": { "description": "No person found matching the provided identifier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PERSON_NOT_FOUND" ], "example": "PERSON_NOT_FOUND" }, "message": { "type": "string", "example": "Person not found" } } } } } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleInsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleRateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleServerError" } } } } } } }, "/person/search": { "get": { "summary": "Search for a person by name or identifier", "description": "Use this endpoint primarily to resolve a fuzzy person name or uncertain identifier.\nIf a reliable LinkedIn URL is already available, skip this search and pass it directly\nto `GET /person` for one full profile or to `POST /people` for a batch lookup.\n\nExactly one parameter must be provided.\n\n**Search types:**\n- `name` \u2014 Fuzzy name search across both investors AND non-investor people (founders, employees). Returns up to 10 results.\n- `id` \u2014 Person UUID lookup (returns 0 or 1)\n- `linkedin` \u2014 LinkedIn person URL or slug\n- `crunchbase` \u2014 Crunchbase person URL or slug\n- `twitter` \u2014 Twitter/X URL or handle\n\n`person_type` on each result indicates which pool the row came from\n(`investor` wins when a person is in both). For full person detail, use `/person`.\n", "operationId": "searchPerson", "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Fuzzy search by person name", "schema": { "type": "string" }, "example": "jane doe" }, { "name": "id", "in": "query", "required": false, "description": "Person UUID", "schema": { "type": "string", "format": "uuid" }, "example": "550e8400-e29b-41d4-a716-446655440000" }, { "name": "linkedin", "in": "query", "required": false, "description": "LinkedIn person URL", "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/eladgil/" }, { "name": "crunchbase", "in": "query", "required": false, "description": "Crunchbase person URL", "schema": { "type": "string" }, "example": "https://crunchbase.com/person/jane-doe" }, { "name": "twitter", "in": "query", "required": false, "description": "Twitter/X URL", "schema": { "type": "string" }, "example": "https://x.com/janedoe" }, { "name": "person_type", "in": "query", "required": false, "description": "Optional filter restricting results to one pool. `investor` keeps only\npeople tracked as investors/angels; `company` keeps only non-investor\npeople (founders, CEOs, employees). Omit to search both. Applies to\nboth name and identifier modes \u2014 identifier lookups return empty if\nthe resolved person doesn't match the requested type.\n", "schema": { "type": "string", "enum": [ "investor", "company" ] }, "example": "investor" } ], "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "linkedin_url": { "type": "string", "nullable": true, "format": "uri" }, "crunchbase_url": { "type": "string", "nullable": true, "format": "uri" }, "twitter_url": { "type": "string", "nullable": true, "format": "uri" }, "person_type": { "type": "string", "enum": [ "investor", "company" ], "description": "Which pool the result came from. Mirrors the request-body discriminator on POST /people." } } } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "example": 7 } } } }, "required": [ "success", "data", "meta" ] } } } }, "400": { "description": "Validation error (missing or multiple parameters)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_SEARCH_PARAMS", "MULTIPLE_SEARCH_PARAMS", "INVALID_ID" ], "example": "MISSING_SEARCH_PARAMS" }, "message": { "type": "string" }, "details": { "type": "object" } } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleAuthError" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleInsufficientCreditsError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleRateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleServerError" } } } } } } }, "/alerts": { "get": { "summary": "Get alert data with deals", "description": "Retrieve saved alert data including all deals that matched the alert criteria within the specified date range.\nResults include a flattened array of deals sorted by date (newest first) with duplicates removed.\n\nAvailable on Pro+ and Enterprise plans. This endpoint does not consume credits.\n\n**Multiple Alerts Support:**\n- Query multiple alerts in a single request (up to 10)\n- Each alert returns its own flattened deals array\n- Different alerts can have different frequencies (e.g., one daily, one weekly)\n- Successful requests report `credits_used: 0`, regardless of deal count\n\n**Important Notes:**\n- All alert_ids must belong to alerts you have access to\n- Deals are flattened from all time periods and sorted by date DESC (newest first)\n- Duplicate deals are automatically removed\n- Each deal includes AI-generated reasoning for why it matched the alert criteria\n- Deal structure is simplified with flattened company information for easier integration\n", "operationId": "getAlerts", "tags": [ "alerts" ], "parameters": [ { "name": "alert_ids", "in": "query", "description": "Comma-separated list of alert UUIDs (up to 10 alerts per request).\nAll alerts must be associated with your API key's account.\nExample: \"uuid1,uuid2,uuid3\"\n", "required": true, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001" } }, { "name": "start_date", "in": "query", "description": "Start date for the alert data range (ISO 8601 format).\nResults will include deals from this date onwards.\n", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00.000Z" } }, { "name": "end_date", "in": "query", "description": "End date for the alert data range (ISO 8601 format).\nResults will include deals up to and including this date.\n\n**Note:** All dates are processed in UTC timezone. Deals are grouped into time periods based on UTC date boundaries.\n", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59.999Z" } } ], "responses": { "200": { "description": "Successful response with alert data organized by time periods", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "alerts": { "type": "array", "description": "Array of alert configurations with their timeline data", "items": { "$ref": "#/components/schemas/Alert" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number (always 0 for alerts endpoint)", "example": 0 }, "page_size": { "type": "integer", "description": "Number of alerts queried in this request", "example": 2 }, "credits_used": { "type": "integer", "enum": [ 0 ], "description": "Alert endpoints do not consume credits", "example": 0 } } } }, "required": [ "success", "data", "meta" ] }, "examples": { "multipleAlerts": { "summary": "Multiple alerts with different frequencies", "value": { "success": true, "data": { "alerts": [ { "alertId": "550e8400-e29b-41d4-a716-446655440000", "alertName": "Weekly AI Funding Deals", "alertFrequency": "WEEKLY", "totalDealCount": 25, "deals": [ { "id": "deal1", "company_id": "comp1", "company_name": "Acme AI Corp", "company_guru_permalink": "acme-ai-corp", "round_type": "SERIES_A", "total_round_raised": 25, "date": "2024-01-15T00:00:00.000Z", "company_website": "acme.com", "company_linkedin": "https://linkedin.com/company/acme", "location": { "city": "San Francisco", "state": "California", "country": "United States", "region": "North America" }, "deal_short_description": "Series A funding round", "deal_long_description": "Acme AI Corp raised $25M in Series A funding", "reasoning": "Matches AI startups criteria with focus on artificial intelligence", "articles": [ { "link": "https://techcrunch.com/article1", "is_primary": true, "publishedDate": "2024-01-15T00:00:00.000Z" } ] }, { "id": "deal3", "company_id": "comp3", "company_name": "ML Solutions Inc", "company_guru_permalink": "ml-solutions-inc", "round_type": "SERIES_B", "total_round_raised": 40, "date": "2024-01-10T00:00:00.000Z", "company_website": "mlsolutions.com", "company_linkedin": null, "location": { "city": "London", "state": null, "country": "United Kingdom", "region": "Europe" }, "deal_short_description": "Series B funding", "deal_long_description": "ML Solutions raised $40M in Series B", "reasoning": "Machine learning focus aligns with your alert criteria", "articles": [] } ] }, { "alertId": "660e8400-e29b-41d4-a716-446655440001", "alertName": "Monthly Healthcare Seed Deals", "alertFrequency": "MONTHLY", "totalDealCount": 22, "deals": [ { "id": "deal2", "company_id": "comp2", "company_name": "HealthTech Startup", "company_guru_permalink": "healthtech-startup", "round_type": "SEED", "total_round_raised": 5, "date": "2024-01-10T00:00:00.000Z", "company_website": "healthtech.io", "company_linkedin": "https://linkedin.com/company/healthtech", "location": { "city": "Boston", "state": "Massachusetts", "country": "United States", "region": "North America" }, "deal_short_description": "Seed funding round", "deal_long_description": "HealthTech Startup raised $5M in seed funding", "reasoning": "Healthcare focus matches your seed round criteria", "articles": [ { "link": "https://healthcarevc.com/article", "is_primary": true, "publishedDate": "2024-01-10T00:00:00.000Z" } ] } ] } ] }, "meta": { "page": 0, "page_size": 2, "credits_used": 0 } } }, "noDealsFound": { "summary": "Valid alert IDs but no deals in date range", "value": { "success": true, "data": { "alerts": [] }, "meta": { "page": 0, "page_size": 1, "credits_used": 0 } } } } } } }, "400": { "description": "Bad Request - Invalid parameters or validation failed", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AlertsValidationError" }, { "$ref": "#/components/schemas/MissingParametersError" } ] }, "examples": { "missingParameters": { "summary": "Missing required parameters", "value": { "success": false, "error": { "code": "MISSING_PARAMETERS", "message": "Missing required parameters", "details": { "missingParams": [ "alert_ids", "start_date" ], "help": "Please provide all required parameters: alert_ids, start_date, end_date" } }, "statusCode": 400 } }, "invalidAlertId": { "summary": "Invalid alert ID format", "value": { "success": false, "error": { "code": "INVALID_ALERT_ID", "message": "Invalid alert ID(s): not-a-uuid, invalid-id. All alert IDs must be valid UUIDs.", "details": { "provided": "not-a-uuid,invalid-id", "help": "Please provide valid UUID format for all alert IDs" } }, "statusCode": 400 } }, "invalidDateFormat": { "summary": "Invalid date format", "value": { "success": false, "error": { "code": "INVALID_DATE_FORMAT", "message": "Invalid date format", "details": { "field": "start_date", "provided": "2024-01-01", "expected": "ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ)", "help": "Please provide dates in ISO 8601 format, e.g., 2024-01-01T00:00:00.000Z" } }, "statusCode": 400 } }, "dateRangeTooLarge": { "summary": "Date range exceeds maximum allowed", "value": { "success": false, "error": { "code": "DATE_RANGE_TOO_LARGE", "message": "Date range cannot exceed 1 year", "details": { "providedRange": "400 days", "maxRange": "365 days", "help": "Please reduce the date range to 1 year or less" } }, "statusCode": 400 } }, "futureStartDate": { "summary": "Start date in the future", "value": { "success": false, "error": { "code": "FUTURE_DATE", "message": "Start date cannot be in the future", "details": { "field": "start_date", "provided": "2025-12-01T00:00:00.000Z", "help": "Please provide a start date that is not in the future" } }, "statusCode": 400 } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "403": { "description": "A Pro+ or Enterprise plan is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierAccessError" } } } }, "404": { "description": "Alert ID not found or access denied.\n\n**Note:** If alert IDs are valid but have no deals in the date range, the endpoint returns 200 with an empty `alerts` array.\n404 is only returned when the alert IDs don't exist or you lack permission to access them.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ALERT_NOT_FOUND" }, "message": { "type": "string", "example": "Alert(s) not found or you do not have permission to access them" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please verify the alert IDs belong to your account" } } } } }, "statusCode": { "type": "integer", "example": 404 } } }, "examples": { "alertNotFound": { "summary": "Alert ID(s) not found or access denied", "value": { "success": false, "error": { "code": "ALERT_NOT_FOUND", "message": "Alert(s) not found or you do not have permission to access them", "details": { "help": "Please verify the alert IDs exist and belong to your account. If IDs are valid but have no deals, you'll receive a 200 response with empty alerts array." } }, "statusCode": 404 } } } } } }, "422": { "description": "Unprocessable Entity - Parameter validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertsValidationError" }, "examples": { "unknownParameter": { "summary": "Unknown parameter provided", "value": { "success": false, "error": { "code": "UNKNOWN_PARAMETER", "message": "Invalid request parameters", "details": { "errors": [ { "field": "invalidParam", "value": "someValue", "message": "Unknown parameter: invalidParam. Allowed parameters: alert_ids, start_date, end_date", "code": "UNKNOWN_PARAMETER", "validOptions": [ "alert_ids", "start_date", "end_date" ] } ], "help": "Please check your request parameters and ensure they meet the required format and constraints." } }, "statusCode": 422 } } } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/alerts/configurations": { "get": { "summary": "Get alert configurations for authenticated user", "description": "Retrieve all alert configurations for the authenticated user (identified by API key).\nReturns configuration metadata including filters, frequency, and descriptions.\n\nAvailable on Pro+ and Enterprise plans. This endpoint does not consume credits.\n\n**Important Notes:**\n- This endpoint does NOT consume usage credits (actualUsageCount: 0)\n- Returns only configuration metadata, not deal data\n- Does not require any query parameters - user is identified by API key\n- All configurations for the authenticated user are returned (no pagination)\n\n**Authentication:**\n- User identity is automatically determined from the API key\n- No email or user_id parameter needed\n\n**Use Cases:**\n- Look up what alerts are configured for the authenticated user\n- Retrieve alert filter settings for external integrations\n- Audit alert configurations programmatically\n", "operationId": "getAlertConfigurations", "tags": [ "alerts" ], "parameters": [], "responses": { "200": { "description": "Successful response with alert configurations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "configurations": { "type": "array", "description": "Array of alert configurations for this email", "items": { "$ref": "#/components/schemas/AlertConfiguration" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number (always 0 for this endpoint)", "example": 0 }, "page_size": { "type": "integer", "description": "Number of configurations returned", "example": 3 }, "credits_used": { "type": "integer", "enum": [ 0 ], "description": "Alert endpoints do not consume credits", "example": 0 } } } }, "required": [ "success", "data", "meta" ] }, "examples": { "withConfigurations": { "summary": "User with multiple alert configurations", "value": { "success": true, "data": { "configurations": [ { "configuration_id": "550e8400-e29b-41d4-a716-446655440000", "configuration_name": "AI Startups Series A", "frequency": "WEEKLY", "description": "Track AI and ML startups raising Series A funding", "filters": { "industries": [ "artificial-intelligence", "machine-learning" ], "financing_types": [ "Series A" ], "deal_size_min": 1000000, "deal_size_max": 10000000, "locations": [ "san-francisco-bay-area", "new-york-new-york" ], "investors": [], "companies": [] } }, { "configuration_id": "660e8400-e29b-41d4-a716-446655440001", "configuration_name": "Healthcare Seed Rounds", "frequency": "DAILY", "description": "Daily alerts for healthcare seed funding", "filters": { "industries": [ "health-care" ], "super_categories": [ "biotechnology" ], "financing_types": [ "Seed" ], "deal_size_min": 500000, "deal_size_max": 5000000, "num_employees": [ "1-10", "11-50" ], "investors": [ { "id": "sequoia-capital", "name": "Sequoia Capital" } ], "companies": [] } }, { "configuration_id": "770e8400-e29b-41d4-a716-446655440002", "configuration_name": "Fintech Tracker", "frequency": "MONTHLY", "description": "Monthly roundup of fintech funding activity", "filters": { "industries": [ "financial-services", "fintech" ], "financing_types": [ "Series A", "Series B", "Series C" ], "locations": [ "united-states" ], "companies": [ { "id": "stripe", "name": "Stripe" }, { "id": "plaid", "name": "Plaid" } ] } } ] }, "meta": { "page": 0, "page_size": 3, "credits_used": 0 } } }, "noConfigurations": { "summary": "User with no configurations", "value": { "success": true, "data": { "configurations": [] }, "meta": { "page": 0, "page_size": 0, "credits_used": 0 } } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" } } } }, "403": { "description": "A Pro+ or Enterprise plan is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TierAccessError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/location/search": { "get": { "summary": "Search locations by name and optionally filter by type", "description": "Use this endpoint to resolve a human-readable city, state, country, or region into\nthe exact permalink required by location filters on discovery endpoints. Agents\nshould not guess permalinks. Select the result that matches the user's intended\ngeography, then pass its permalink to the relevant filter.\n\nThe `name` parameter is required; `type` is optional.\n\n**Search types:**\n- `name` \u2014 Fuzzy name search with relevance scoring (required)\n- `type` \u2014 Optional filter by location type: `CITY`, `STATE`, `REGION`, or `COUNTRY`\n- `location_type` \u2014 Alias for `type`\n\nExamples:\n- `?name=san francisco`\n- `?name=california&type=STATE`\n", "operationId": "searchLocations", "parameters": [ { "name": "name", "in": "query", "description": "Location name to search for", "required": true, "schema": { "type": "string", "example": "san francisco" } }, { "name": "type", "in": "query", "description": "Filter by specific location type", "required": false, "schema": { "type": "string", "enum": [ "CITY", "STATE", "REGION", "COUNTRY" ], "example": "CITY" } }, { "name": "location_type", "in": "query", "description": "Alias for 'type' parameter", "required": false, "schema": { "type": "string", "enum": [ "CITY", "STATE", "REGION", "COUNTRY" ], "example": "CITY" } } ], "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LocationSearchResult" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Number of locations returned", "example": 3 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 3 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request (always 0 for search endpoints)", "example": 0 } } } }, "required": [ "success", "data", "meta" ] }, "examples": { "all_types": { "summary": "Search without type filter", "description": "Returns all location types matching the search term", "value": { "success": true, "data": { "locations": [ { "permalink": "san-francisco-california", "name": "San Francisco", "location_type": "CITY" }, { "permalink": "san-francisco-bay-area", "name": "San Francisco Bay Area", "location_type": "REGION" }, { "permalink": "california", "name": "California", "location_type": "STATE" } ] }, "meta": { "total_count": 3 } } }, "cities_only": { "summary": "Search filtered by CITY type", "description": "Returns only cities matching the search term", "value": { "success": true, "data": { "locations": [ { "permalink": "san-francisco-california", "name": "San Francisco", "location_type": "CITY" }, { "permalink": "san-jose-california", "name": "San Jose", "location_type": "CITY" } ] }, "meta": { "total_count": 2 } } } } } } }, "400": { "description": "Search parameter validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_SEARCH_PARAMS", "INVALID_LOCATION_TYPE", "MULTIPLE_LOCATION_TYPE_PARAMS" ], "example": "MISSING_SEARCH_PARAMS" }, "message": { "type": "string", "example": "The \"name\" search parameter is required" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Provide a name parameter. Example: ?name=san+francisco" } } } } } } }, "examples": { "missing_params": { "value": { "success": false, "error": { "code": "MISSING_SEARCH_PARAMS", "message": "The \"name\" search parameter is required", "details": { "help": "Provide a name parameter. Example: ?name=san+francisco" } }, "statusCode": 400 } }, "invalid_location_type": { "value": { "success": false, "error": { "code": "INVALID_LOCATION_TYPE", "message": "Invalid location type. Must be one of: CITY, STATE, REGION, COUNTRY", "details": { "help": "Provided type: 'INVALID'. Valid types are: CITY, STATE, REGION, COUNTRY" } }, "statusCode": 400 } }, "multiple_location_type_params": { "value": { "success": false, "error": { "code": "MULTIPLE_LOCATION_TYPE_PARAMS", "message": "Cannot specify both type and location_type parameters", "details": { "help": "Use either type or location_type parameter, not both" } }, "statusCode": 400 } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtherAuthError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/industry/search": { "get": { "summary": "Search industries and super categories by name", "description": "Use this endpoint before semantic search to resolve a human-readable category into\nan exact `INDUSTRY` or `SUPER_CATEGORY` permalink. Agents should not guess permalinks.\nIf the taxonomy has an appropriate result, use its permalink in the structured\nindustry filter. Use `search_query` only when the requested niche is not represented\nby the taxonomy.\n\nThe `name` parameter is required; `type` is optional.\n\n**Search types:**\n- `name` \u2014 Fuzzy name search with relevance scoring (required)\n- `type` \u2014 Optional filter by industry type: `INDUSTRY` or `SUPER_CATEGORY`\n- `industry_type` \u2014 Alias for `type`\n\nExamples:\n- `?name=artificial intelligence`\n- `?name=fintech&type=INDUSTRY`\n", "operationId": "searchIndustries", "parameters": [ { "name": "name", "in": "query", "description": "Industry name to search for", "required": true, "schema": { "type": "string", "example": "artificial intelligence" } }, { "name": "type", "in": "query", "description": "Filter by specific industry type", "required": false, "schema": { "type": "string", "enum": [ "INDUSTRY", "SUPER_CATEGORY" ], "example": "INDUSTRY" } }, { "name": "industry_type", "in": "query", "description": "Alias for 'type' parameter", "required": false, "schema": { "type": "string", "enum": [ "INDUSTRY", "SUPER_CATEGORY" ], "example": "INDUSTRY" } } ], "responses": { "200": { "description": "Successful search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "industries": { "type": "array", "items": { "$ref": "#/components/schemas/IndustrySearchResult" } } } }, "meta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Number of industries returned", "example": 3 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 3 }, "credits_used": { "type": "integer", "description": "Number of credits consumed by this request (always 0 for search endpoints)", "example": 0 } } } }, "required": [ "success", "data", "meta" ] }, "examples": { "all_types": { "summary": "Search without type filter", "description": "Returns both industries and super categories matching the search term", "value": { "success": true, "data": { "industries": [ { "permalink": "artificial-intelligence", "name": "Artificial Intelligence", "industry_type": "INDUSTRY" }, { "permalink": "machine-learning", "name": "Machine Learning", "industry_type": "INDUSTRY" } ] }, "meta": { "total_count": 2 } } }, "industries_only": { "summary": "Search filtered by INDUSTRY type", "description": "Returns only industries matching the search term", "value": { "success": true, "data": { "industries": [ { "permalink": "fintech-e067", "name": "FinTech", "industry_type": "INDUSTRY" } ] }, "meta": { "total_count": 1 } } } } } } }, "400": { "description": "Search parameter validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "MISSING_SEARCH_PARAMS", "INVALID_INDUSTRY_TYPE", "MULTIPLE_INDUSTRY_TYPE_PARAMS" ], "example": "MISSING_SEARCH_PARAMS" }, "message": { "type": "string", "example": "The \"name\" search parameter is required" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Provide a name parameter. Example: ?name=artificial+intelligence" } } } } } } }, "examples": { "missing_params": { "value": { "success": false, "error": { "code": "MISSING_SEARCH_PARAMS", "message": "The \"name\" search parameter is required", "details": { "help": "Provide a name parameter. Example: ?name=artificial+intelligence" } }, "statusCode": 400 } }, "invalid_industry_type": { "value": { "success": false, "error": { "code": "INVALID_INDUSTRY_TYPE", "message": "Invalid industry type. Must be one of: INDUSTRY, SUPER_CATEGORY", "details": { "help": "Provided type: 'INVALID'. Valid types are: INDUSTRY, SUPER_CATEGORY" } }, "statusCode": 400 } }, "multiple_industry_type_params": { "value": { "success": false, "error": { "code": "MULTIPLE_INDUSTRY_TYPE_PARAMS", "message": "Cannot specify both type and industry_type parameters", "details": { "help": "Use either type or industry_type parameter, not both" } }, "statusCode": 400 } } } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtherAuthError" } } } }, "429": { "description": "Rate limit exceeded (per-minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "headers": { "Retry-After": { "description": "Number of seconds to wait before retrying", "schema": { "type": "integer", "example": 60 } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key provided as a Bearer token" } }, "schemas": { "Deal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the deal", "example": "550e8400-e29b-41d4-a716-446655440000" }, "round_type": { "type": "string", "nullable": true, "description": "Type of funding round", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND" ], "example": "SERIES_A" }, "extension": { "type": "boolean", "nullable": true, "description": "Whether this is an extension round", "example": false }, "intermediate": { "type": "string", "nullable": true, "description": "Intermediate round designation", "enum": [ "PLUS", "NONE", "ONE", "TWO", "THREE", "FOUR", "FIVE", "SIX", "SEVEN", "EIGHT" ], "example": "NONE" }, "pre": { "type": "boolean", "nullable": true, "description": "Whether this is a pre-round (e.g., Pre-Series A)", "example": false }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Announcement date of the funding round", "example": "2024-01-15T00:00:00Z" }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Date the deal was added to the system", "example": "2024-01-16T12:30:00Z" }, "total_round_raised": { "type": "number", "nullable": true, "description": "Total amount raised in the round (USD)", "example": 25000000 }, "deal_descriptions": { "type": "object", "nullable": true, "properties": { "short_description": { "type": "string", "nullable": true, "description": "Brief description of the deal" }, "long_description": { "type": "string", "nullable": true, "description": "Detailed description of the deal" } } }, "company_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "550e8400-e29b-41d4-a716-446655440001" }, "investor_ids": { "type": "array", "description": "UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" ] }, "angel_investor_ids": { "type": "array", "description": "UUIDs of angel investors (people) who participated in this deal. Resolve via `/people/{id}`. Empty array when no angels.", "items": { "type": "string", "format": "uuid" }, "example": [ "b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a" ] }, "financings": { "type": "array", "description": "Detailed financing information for deals that have multiple financing types", "items": { "$ref": "#/components/schemas/Financing" } }, "valuation": { "nullable": true, "description": "Valuation information for this deal", "$ref": "#/components/schemas/Valuation" }, "articles": { "type": "array", "description": "Related articles/sources for this deal.\nAlways included for every API tier. Empty when the deal has no related sources.\n", "items": { "$ref": "#/components/schemas/DealArticle" } } }, "required": [ "id", "round_type", "extension", "intermediate", "pre", "date", "created_at", "total_round_raised", "deal_descriptions", "company_id", "investor_ids", "angel_investor_ids", "financings", "valuation", "articles" ] }, "DealInvestor": { "type": "object", "description": "A firm investor on a deal. Angels are returned separately in the `angel_investors` array on /deals/{id}/investors.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the firm investor (parent_investor UUID)", "example": "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82" }, "name": { "type": "string", "description": "Investor name", "example": "Sequoia Capital" }, "lead_investor": { "type": "boolean", "nullable": true, "description": "Whether this investor led the round", "example": true }, "personnel": { "type": "array", "description": "Key personnel (partners) at this firm involved in this deal. Each entry is a person record joinable to /people/{id}.", "items": { "$ref": "#/components/schemas/PersonnelMember" }, "example": [ { "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890", "name": "John Smith", "linkedin": "https://linkedin.com/in/johnsmith", "crunchbase": "https://crunchbase.com/person/john-smith", "twitter": "https://x.com/johnsmith" } ] }, "financing_type": { "type": "string", "nullable": true, "description": "The financing type this investor participated in", "example": "SERIES_A" }, "domain": { "type": "string", "nullable": true, "description": "Investor's website domain", "example": "sequoiacap.com" }, "linkedin": { "type": "string", "nullable": true, "description": "Investor's LinkedIn URL", "example": "https://linkedin.com/company/sequoia-capital" }, "crunchbase": { "type": "string", "nullable": true, "description": "Investor's Crunchbase URL", "example": "https://crunchbase.com/organization/sequoia-capital" } }, "required": [ "id", "name" ] }, "PersonnelMember": { "type": "object", "description": "A person (partner) at a firm investor associated with a deal.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Person UUID. Resolves via /people/{id}." }, "name": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true, "description": "LinkedIn URL." }, "crunchbase": { "type": "string", "nullable": true, "description": "Crunchbase URL." }, "twitter": { "type": "string", "nullable": true, "description": "Twitter/X URL." } }, "required": [ "id" ] }, "AngelInvestor": { "type": "object", "description": "An angel (individual) investor on a deal. Returned in the `angel_investors` array on /deals/{id}/investors.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Person UUID for the angel. Resolves via /people/{id}." }, "name": { "type": "string", "nullable": true }, "financing_type": { "type": "string", "nullable": true, "description": "The financing type this angel participated in.", "example": "SEED" }, "linkedin": { "type": "string", "nullable": true }, "crunchbase": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true } }, "required": [ "id" ] }, "DealArticle": { "type": "object", "description": "An article or source related to a deal", "properties": { "link": { "type": "string", "nullable": true, "description": "URL of the article", "example": "https://techcrunch.com/2024/01/15/company-raises-series-a" }, "date": { "type": "string", "nullable": true, "description": "Date of the article", "example": "2024-01-15" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary source article for the deal", "example": true } }, "required": [ "is_primary" ] }, "Financing": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the financing" }, "type": { "type": "string", "description": "Type of financing", "enum": [ "SEED", "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_L", "SERIES_M", "CONVERTIBLE_NOTE", "CROWDFUNDING", "DEBT_FINANCING", "EQUITY", "FUNDING_ROUND", "GRANT", "INITIAL_COIN_OFFERING", "NON_EQUITY_ASSISTANCE", "PREFERRED", "SAFE", "SECONDARY_MARKET" ], "example": "SERIES_A" }, "size_usd": { "type": "number", "nullable": true, "description": "Financing amount (USD)", "example": 25000000 }, "size_native": { "type": "number", "nullable": true, "description": "Financing amount in native currency", "example": 25000000 }, "currency": { "type": "string", "nullable": true, "description": "Currency of the original financing amount", "example": "USD" } }, "required": [ "id", "type" ] }, "Valuation": { "type": "object", "nullable": true, "properties": { "valuation_currency": { "type": "string", "nullable": true, "description": "Currency of the valuation", "example": "USD" }, "valuation_usd": { "type": "number", "nullable": true, "description": "Valuation amount (USD)", "example": 100000000 }, "valuation_native": { "type": "number", "nullable": true, "description": "Valuation amount in native currency", "example": 100000000 }, "type": { "type": "string", "description": "Type of valuation", "enum": [ "DEFAULT", "POST_MONEY", "PRE_MONEY" ], "example": "POST_MONEY" } }, "required": [ "type" ] }, "AuthError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "AUTH_ERROR", "INVALID_API_KEY", "INACTIVE_API_KEY" ], "example": "AUTH_ERROR" }, "message": { "type": "string", "example": "API key not provided" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please provide your API key in the Authorization header" }, "format": { "type": "string", "example": "Bearer vg_your_api_key_here" } } } } } }, "required": [ "error" ] }, "RateLimitError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "message": { "type": "string", "example": "Rate limit exceeded. Maximum 200 requests per minute." }, "details": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Maximum requests allowed per window", "example": 200 }, "window": { "type": "string", "description": "Rate limit window duration", "example": "60 seconds" }, "help": { "type": "string", "example": "Please reduce your request frequency and try again." } } } } } }, "required": [ "error" ] }, "InsufficientCreditsError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INSUFFICIENT_CREDITS" }, "message": { "type": "string", "example": "Not enough credits to complete this request. Visit https://www.tryfundable.ai/api-access to purchase more." }, "details": { "type": "object", "properties": { "credits_needed": { "type": "integer", "nullable": true, "description": "Number of credits required (included when known post-execution)", "example": 25 }, "monthly_credits_remaining": { "type": "integer", "description": "Remaining monthly credits", "example": 0 }, "purchased_credits_remaining": { "type": "integer", "description": "Remaining purchased credits", "example": 0 }, "help": { "type": "string", "example": "Purchase additional credits at https://www.tryfundable.ai/api-access or upgrade your plan." } } } } } }, "required": [ "error" ] }, "ValidationError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ], "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Invalid request parameters" }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The parameter name that failed validation", "example": "deal.financing_types" }, "value": { "type": "string", "description": "The invalid value provided", "example": "series-a" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid financing type(s): series-a. Valid options are: SERIES_A, SERIES_B, SEED, ..." }, "code": { "type": "string", "description": "Machine-readable error code", "example": "INVALID_FINANCING_TYPE" }, "validOptions": { "type": "array", "items": { "type": "string" }, "description": "List of valid values for enum parameters", "example": [ "SERIES_A", "SERIES_B", "SEED" ] } } } }, "help": { "type": "string", "example": "Please check your request parameters and ensure they meet the required format and constraints." } } } } } }, "required": [ "error" ] }, "ServerError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" }, "message": { "type": "string", "example": "An unexpected error occurred" }, "details": { "type": "string", "nullable": true, "description": "Error details (only in development mode)" } } } }, "required": [ "error" ] }, "CompanyDetails": { "type": "object", "description": "Full company details returned by the /company endpoint", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "nullable": true, "description": "Company name", "example": "Acme Corporation" }, "legal_name": { "type": "string", "nullable": true, "description": "Legal name of the company", "example": "Acme Corporation Inc." }, "guru_permalink": { "type": "string", "nullable": true, "description": "Fundable permalink for the company", "example": "acme-corporation" }, "domain": { "type": "string", "nullable": true, "description": "Company website domain", "example": "acme.com" }, "region": { "type": "string", "nullable": true, "description": "Company region", "example": "San Francisco Bay Area" }, "short_description": { "type": "string", "nullable": true, "description": "Brief description of the company" }, "long_description": { "type": "string", "nullable": true, "description": "Full description of the company. Available on /company endpoint; may be null on /companies list endpoint." }, "num_employees": { "type": "string", "nullable": true, "description": "Number of employees range", "example": "11-50" }, "linkedin": { "type": "string", "nullable": true, "format": "uri", "description": "LinkedIn profile URL" }, "twitter": { "type": "string", "nullable": true, "format": "uri", "description": "Twitter profile URL" }, "facebook": { "type": "string", "nullable": true, "format": "uri", "description": "Facebook profile URL" }, "pitchbook": { "type": "string", "nullable": true, "format": "uri", "description": "PitchBook profile URL" }, "crunchbase": { "type": "string", "nullable": true, "format": "uri", "description": "Crunchbase profile URL" }, "address": { "type": "string", "nullable": true, "description": "Company address" }, "ipo_status": { "type": "string", "nullable": true, "description": "IPO status of the company", "enum": [ "public", "private" ], "example": "private" }, "num_funding_rounds": { "type": "integer", "nullable": true, "description": "Number of funding rounds", "example": 11 }, "num_investors": { "type": "integer", "nullable": true, "description": "Number of investors", "example": 14 }, "total_raised": { "type": "number", "nullable": true, "description": "Total amount raised (USD)", "example": 2834940000 }, "latest_valuation_usd": { "type": "number", "nullable": true, "description": "Latest valuation (USD)", "example": 31000000000 }, "latest_valuation_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date of latest valuation", "example": "2017-03-09T00:00:00.000Z" }, "industries": { "type": "array", "description": "Industries the company operates in", "items": { "type": "object", "properties": { "permalink": { "type": "string", "description": "Industry permalink", "example": "artificial-intelligence" }, "name": { "type": "string", "description": "Industry name", "example": "Artificial Intelligence" } } } }, "location": { "type": "object", "description": "Company location hierarchy", "properties": { "region": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "Region name", "example": "San Francisco Bay Area" }, "permalink": { "type": "string", "description": "Region permalink", "example": "san-francisco-bay-area" } } }, "country": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "Country name", "example": "United States" }, "permalink": { "type": "string", "description": "Country permalink", "example": "united-states" } } }, "state": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "State name", "example": "California" }, "permalink": { "type": "string", "description": "State permalink", "example": "california" } } }, "city": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "City name", "example": "San Francisco" }, "permalink": { "type": "string", "description": "City permalink", "example": "san-francisco-california" } } } } }, "latest_deal": { "$ref": "#/components/schemas/LatestDeal" }, "all_investor_ids": { "type": "array", "nullable": true, "description": "UUIDs of all parent investors across all funding rounds for this company", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82", "c6bc63af-cb37-453d-9c20-35f56fb87ee9" ] }, "similarity": { "type": "number", "nullable": true, "description": "Semantic similarity score (0-1). Only present when using search_query parameter.", "example": null } } }, "CompanyListItem": { "type": "object", "description": "Company object returned by the /companies list endpoint. Same shape as CompanyDetails.", "allOf": [ { "$ref": "#/components/schemas/CompanyDetails" } ] }, "LatestDeal": { "type": "object", "nullable": true, "description": "Details of the company's most recent funding round", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true, "description": "Unique identifier for the deal" }, "type": { "type": "string", "nullable": true, "description": "Type of funding round", "enum": [ "SERIES_A", "SERIES_B", "SERIES_C", "SERIES_D", "SERIES_E", "SERIES_F", "SERIES_G", "SERIES_H", "SERIES_I", "SERIES_J", "SERIES_K", "SERIES_M", "SEED", "SAFE", "CONVERTIBLE_NOTE", "EQUITY", "PREFERRED", "SECONDARY_MARKET", "DEBT_FINANCING", "GRANT", "NON_EQUITY_ASSISTANCE", "CROWDFUNDING", "INITIAL_COIN_OFFERING", "FUNDING_ROUND", "HYBRID", "HYBRID_SEED", "HYBRID_SERIES_A", "HYBRID_SERIES_B", "HYBRID_SERIES_C", "HYBRID_SERIES_D", "HYBRID_SERIES_E", "HYBRID_SERIES_F", "HYBRID_SERIES_G", "HYBRID_SERIES_H", "HYBRID_SERIES_I", "HYBRID_SERIES_J", "HYBRID_SERIES_K", "HYBRID_SERIES_M" ], "example": "SERIES_B" }, "total_round_raised": { "type": "number", "nullable": true, "description": "Total amount raised in the round (USD)", "example": 25000000 }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date of the funding round", "example": "2024-01-15T00:00:00Z" }, "extension": { "type": "boolean", "nullable": true, "description": "Whether this is an extension round", "example": false }, "pre": { "type": "boolean", "nullable": true, "description": "Whether this is a pre-round (e.g., Pre-Series A)", "example": false }, "intermediate": { "type": "string", "nullable": true, "description": "Intermediate round designation", "enum": [ "PLUS", "NONE", "ONE", "TWO", "THREE", "FOUR", "FIVE", "SIX", "SEVEN", "EIGHT" ], "example": "NONE" }, "description": { "type": "object", "nullable": true, "properties": { "short_description": { "type": "string", "nullable": true, "description": "Brief description of the deal" }, "long_description": { "type": "string", "nullable": true, "description": "Detailed description of the deal" } } }, "investors": { "type": "array", "description": "UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.", "items": { "type": "string", "format": "uuid" }, "example": [ "c5a3f6ac-f6c9-4686-aa6e-12aeb7419b82", "c6bc63af-cb37-453d-9c20-35f56fb87ee9" ] }, "angel_investor_ids": { "type": "array", "description": "UUIDs of angel investors (people) on this latest deal. Resolve via `/people/{id}`. Empty array when no angels.", "items": { "type": "string", "format": "uuid" }, "example": [ "b3e9c7d1-2f4a-4d5e-9c1b-7a8f3e2d1c6a" ] }, "financings": { "type": "array", "description": "Individual financing tranches in this deal", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the financing" }, "type": { "type": "string", "description": "Type of financing" }, "size_usd": { "type": "number", "nullable": true, "description": "Financing amount in USD", "example": 25000000 }, "size_native": { "type": "number", "nullable": true, "description": "Financing amount in native currency", "example": 25000000 }, "currency": { "type": "string", "nullable": true, "description": "Currency code for size_native", "example": "USD" } } } }, "articles": { "type": "array", "description": "Related articles/sources for the latest deal. Always included; empty when no sources exist.", "items": { "$ref": "#/components/schemas/DealArticle" } } }, "required": [ "id", "type", "total_round_raised", "date", "extension", "pre", "intermediate", "description", "investors", "angel_investor_ids", "financings", "articles" ] }, "LocationInfo": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "description": "Location name" }, "permalink": { "type": "string", "description": "Location permalink" } } }, "CompanySearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "550e8400-e29b-41d4-a716-446655440000" }, "guru_permalink": { "type": "string", "nullable": true, "description": "Fundable permalink for the company", "example": "acme-corporation" }, "name": { "type": "string", "description": "Company name", "example": "Acme Corporation" }, "short_description": { "type": "string", "nullable": true, "description": "Brief description of the company", "example": "AI-powered solutions for modern enterprises" }, "relevance_score": { "type": "number", "description": "Search relevance score (0-1)", "example": 0.95 }, "domain": { "type": "string", "nullable": true, "description": "Company website domain", "example": "acme.com" }, "linkedin": { "type": "string", "nullable": true, "description": "LinkedIn profile URL" }, "crunchbase": { "type": "string", "nullable": true, "description": "Crunchbase profile URL" } } }, "CompanyDeal": { "type": "object", "description": "Deal returned by the /company/deals endpoint. Same shape as the Deal schema in the Deals API.", "properties": { "id": { "type": "string", "format": "uuid" }, "round_type": { "type": "string", "nullable": true }, "extension": { "type": "boolean", "nullable": true }, "intermediate": { "type": "string", "nullable": true }, "pre": { "type": "boolean", "nullable": true }, "date": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "total_round_raised": { "type": "number", "nullable": true }, "deal_descriptions": { "type": "object", "nullable": true, "properties": { "short_description": { "type": "string", "nullable": true }, "long_description": { "type": "string", "nullable": true } } }, "company_id": { "type": "string", "format": "uuid" }, "investor_ids": { "type": "array", "description": "UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.", "items": { "type": "string", "format": "uuid" } }, "angel_investor_ids": { "type": "array", "description": "UUIDs of angel investors (people) on this deal. Resolve via `/people/{id}`. Empty array when no angels.", "items": { "type": "string", "format": "uuid" } }, "financings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "size_usd": { "type": "number", "nullable": true }, "size_native": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true } } } }, "valuation": { "type": "object", "nullable": true, "properties": { "valuation_currency": { "type": "string", "nullable": true }, "valuation_usd": { "type": "number", "nullable": true }, "valuation_native": { "type": "number", "nullable": true }, "type": { "type": "string" } } }, "articles": { "type": "array", "description": "Related articles/sources for this deal. Always included; empty when no sources exist.", "items": { "$ref": "#/components/schemas/DealArticle" } } }, "required": [ "id", "round_type", "extension", "intermediate", "pre", "date", "created_at", "total_round_raised", "deal_descriptions", "company_id", "investor_ids", "angel_investor_ids", "financings", "valuation", "articles" ] }, "CompaniesValidationError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ], "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Invalid request parameters" }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The parameter name that failed validation", "example": "financing_types" }, "value": { "type": "string", "description": "The invalid value provided", "example": "series-a" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid financing type(s): series-a. Valid options are: SERIES_A, SERIES_B, SEED, ..." }, "code": { "type": "string", "description": "Machine-readable error code", "example": "INVALID_FINANCING_TYPE" }, "validOptions": { "type": "array", "items": { "type": "string" }, "description": "List of valid values for enum parameters", "example": [ "SERIES_A", "SERIES_B", "SEED" ] } } } }, "help": { "type": "string", "example": "Please check your request parameters and ensure they meet the required format and constraints." } } } } } }, "required": [ "error" ] }, "NotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "COMPANY_NOT_FOUND" ], "example": "COMPANY_NOT_FOUND" }, "message": { "type": "string", "example": "Company not found" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please check the company identifier (ID, domain, LinkedIn URL, or Crunchbase URL) and try again" } } } } } }, "required": [ "error" ] }, "Investor": { "type": "object", "description": "Full investor profile", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the investor" }, "name": { "type": "string", "description": "Investor name" }, "total_deal_count": { "type": "integer", "description": "Total number of deals" }, "lead_deal_count": { "type": "integer", "description": "Number of deals where investor was lead" }, "deal_count_last_12_months": { "type": "integer", "description": "Deals in the last 12 months" }, "lead_deal_count_last_12_months": { "type": "integer", "description": "Lead deals in the last 12 months" }, "most_recent_deal_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date of the most recent deal" }, "guru_permalink": { "type": "string", "description": "Fundable permalink for the investor" }, "domain": { "type": "string", "nullable": true, "description": "Investor domain" }, "website": { "type": "string", "nullable": true, "format": "uri", "description": "Investor website URL" }, "linkedin": { "type": "string", "nullable": true, "format": "uri", "description": "Investor LinkedIn URL" }, "pitchbook": { "type": "string", "nullable": true, "format": "uri", "description": "Investor PitchBook URL" }, "crunchbase": { "type": "string", "nullable": true, "format": "uri", "description": "Investor Crunchbase URL" }, "description": { "type": "string", "nullable": true, "description": "Description of the investor" }, "legal_name": { "type": "string", "nullable": true, "description": "Legal name of the investor" }, "num_employees": { "type": "string", "nullable": true, "description": "Employee count range", "example": "101-250" }, "investment_stage": { "type": "string", "nullable": true, "description": "Investment stage focus", "example": "Series A" }, "contact_email": { "type": "string", "nullable": true, "format": "email", "description": "Contact email (when available)" }, "contact_phone": { "type": "string", "nullable": true, "description": "Contact phone number (when available)" }, "location": { "$ref": "#/components/schemas/InvestorsLocationInfo" }, "top_industries": { "type": "array", "description": "Top industries invested in", "items": { "type": "object", "properties": { "name": { "type": "string" }, "permalink": { "type": "string" }, "count": { "type": "integer" } } } }, "top_locations": { "type": "array", "description": "Top portfolio company locations", "items": { "type": "object", "properties": { "name": { "type": "string" }, "full_name": { "type": "string" }, "permalink": { "type": "string" }, "type": { "type": "string" }, "count": { "type": "integer" } } } }, "top_round_types": { "type": "array", "description": "Most common round types", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "required": [ "id", "name", "guru_permalink", "total_deal_count", "lead_deal_count", "deal_count_last_12_months" ] }, "InvestorListItem": { "description": "Investor with optional portfolio filter counts, returned from the POST /investors endpoint", "allOf": [ { "$ref": "#/components/schemas/Investor" }, { "type": "object", "properties": { "filtered_deal_count": { "type": "integer", "nullable": true, "description": "Number of deals matching the active `company_investments` filters" }, "filtered_lead_count": { "type": "integer", "nullable": true, "description": "Of the deals matching the active `company_investments` filters, how many the investor led" } } } ] }, "InvestorsLocationInfo": { "type": "object", "description": "Investor location details", "properties": { "region": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "North America" }, "permalink": { "type": "string", "example": "north-america" } } }, "country": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "United States" }, "permalink": { "type": "string", "example": "united-states" } } }, "state": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "California" }, "permalink": { "type": "string", "example": "california" } } }, "city": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "example": "San Francisco" }, "permalink": { "type": "string", "example": "san-francisco-california" } } } } }, "InvestorDeal": { "type": "object", "description": "Deal returned by the /investor/deals endpoint. Same shape as the Deal schema in the Deals API.", "properties": { "id": { "type": "string", "format": "uuid" }, "round_type": { "type": "string", "nullable": true }, "extension": { "type": "boolean", "nullable": true }, "intermediate": { "type": "string", "nullable": true }, "pre": { "type": "boolean", "nullable": true }, "date": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "total_round_raised": { "type": "number", "nullable": true }, "deal_descriptions": { "type": "object", "nullable": true, "properties": { "short_description": { "type": "string", "nullable": true }, "long_description": { "type": "string", "nullable": true } } }, "company_id": { "type": "string", "format": "uuid" }, "investor_ids": { "type": "array", "description": "UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.", "items": { "type": "string", "format": "uuid" } }, "angel_investor_ids": { "type": "array", "description": "UUIDs of angel investors (people) on this deal. Resolve via `/people/{id}`. Empty array when no angels.", "items": { "type": "string", "format": "uuid" } }, "financings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "size_usd": { "type": "number", "nullable": true }, "size_native": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true } } } }, "valuation": { "type": "object", "nullable": true, "properties": { "valuation_currency": { "type": "string", "nullable": true }, "valuation_usd": { "type": "number", "nullable": true }, "valuation_native": { "type": "number", "nullable": true }, "type": { "type": "string" } } }, "articles": { "type": "array", "description": "Related articles/sources for this deal. Always included; empty when no sources exist.", "items": { "$ref": "#/components/schemas/DealArticle" } } }, "required": [ "id", "round_type", "extension", "intermediate", "pre", "date", "created_at", "total_round_raised", "deal_descriptions", "company_id", "investor_ids", "angel_investor_ids", "financings", "valuation", "articles" ] }, "ParameterValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Invalid request parameters" }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string", "nullable": true }, "message": { "type": "string" }, "code": { "type": "string" }, "validOptions": { "type": "array", "items": { "type": "string" } } } } }, "help": { "type": "string" } } } } } }, "required": [ "success", "error" ] }, "InvestorSearchResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the investor", "example": "550e8400-e29b-41d4-a716-446655440000" }, "guru_permalink": { "type": "string", "nullable": true, "description": "Fundable permalink for the investor", "example": "acme-ventures" }, "name": { "type": "string", "description": "Investor name", "example": "Acme Ventures" }, "description": { "type": "string", "nullable": true, "description": "Brief description of the investor", "example": "Early-stage venture capital firm focused on AI startups" }, "relevance_score": { "type": "number", "description": "Search relevance score (0-1)", "example": 0.92 }, "domain": { "type": "string", "nullable": true, "description": "Investor website domain", "example": "acmeventures.com" }, "website": { "type": "string", "nullable": true, "format": "uri", "description": "Investor website URL" }, "linkedin": { "type": "string", "nullable": true, "description": "LinkedIn profile URL" }, "crunchbase": { "type": "string", "nullable": true, "description": "Crunchbase profile URL" } } }, "InvestorsNotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVESTOR_NOT_FOUND" ], "example": "INVESTOR_NOT_FOUND" }, "message": { "type": "string", "example": "Investor not found" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please check the investor identifier (ID, domain, LinkedIn URL, or Crunchbase URL) and try again" } } } } } }, "required": [ "error" ] }, "PersonSearchResult": { "type": "object", "description": "Constant unified person shape \u2014 every row carries every field. Investor aggregates live\nunder `investor_highlights` (null for non-investors); discriminator flags `is_investor` /\n`is_angel` / `has_led_deal` and `investment_firms` stay top-level. `employment_history`\nand `education_history` are capped at 3 in the search response; the detail endpoint\nreturns the full lists.\n", "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "nullable": true, "example": "Jane Doe" }, "title": { "type": "string", "nullable": true, "description": "Current job title", "example": "CEO" }, "linkedin_url": { "type": "string", "nullable": true, "format": "uri", "description": "Canonical LinkedIn person URL" }, "crunchbase_url": { "type": "string", "nullable": true, "format": "uri", "description": "Canonical Crunchbase person URL" }, "twitter_url": { "type": "string", "nullable": true, "format": "uri", "description": "Canonical Twitter/X profile URL" }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "city": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "example": "US" }, "about": { "type": "string", "nullable": true, "description": "LinkedIn bio/about section" }, "is_founder": { "type": "boolean" }, "current_company": { "$ref": "#/components/schemas/PersonCurrentCompany" }, "employment_history": { "type": "array", "description": "Recent employment (max 3 items in search; full list on detail endpoint)", "maxItems": 3, "items": { "$ref": "#/components/schemas/EmploymentRecord" } }, "education_history": { "type": "array", "description": "Education records (max 3 items in search; full list on detail endpoint)", "maxItems": 3, "items": { "$ref": "#/components/schemas/EducationRecord" } }, "is_investor": { "type": "boolean", "description": "Whether the person has any tracked investment activity" }, "is_angel": { "type": "boolean", "description": "Whether the person makes angel investments" }, "has_led_deal": { "type": "boolean", "description": "Whether the person has ever led a deal" }, "investment_firms": { "type": "array", "description": "Firms the person invests under (empty for pure angels)", "items": { "$ref": "#/components/schemas/Firm" } }, "investor_highlights": { "nullable": true, "description": "Aggregated investor activity. Null when `is_investor` is false.", "$ref": "#/components/schemas/InvestorHighlights" }, "filtered_deal_count": { "type": "integer", "nullable": true, "description": "Count of deals matching the `investor.deals.*` filters. Populated only when any `investor.deals.*` filter is present; otherwise null." }, "filtered_lead_count": { "type": "integer", "nullable": true, "description": "Of the matching deals, how many the person/firm led. Populated only when any `investor.deals.*` filter is present." }, "filtered_most_recent_date": { "type": "string", "format": "date", "nullable": true, "description": "Most recent matching-deal date. Populated only when any `investor.deals.*` filter is present." } } }, "PersonDetail": { "allOf": [ { "$ref": "#/components/schemas/PersonSearchResult" }, { "type": "object", "description": "Detail endpoint returns the same shape as search but with full (unbounded) employment and education history.", "properties": { "employment_history": { "type": "array", "description": "Full employment history (no item cap)", "items": { "$ref": "#/components/schemas/EmploymentRecord" } }, "education_history": { "type": "array", "description": "Full education history (no item cap)", "items": { "$ref": "#/components/schemas/EducationRecord" } } } } ] }, "PersonEmailResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": { "type": "object", "required": [ "person_id", "email", "already_unlocked" ], "properties": { "person_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "already_unlocked": { "type": "boolean", "description": "True when this user previously unlocked the same email.", "example": false } } }, "meta": { "type": "object", "required": [ "page", "page_size", "credits_used" ], "properties": { "page": { "type": "integer", "enum": [ 0 ] }, "page_size": { "type": "integer", "enum": [ 1 ] }, "credits_used": { "type": "integer", "enum": [ 0, 5 ], "description": "Five for a new unlock; zero when already unlocked." }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ], "description": "Omitted for API-tier keys." }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "description": "Omitted for API-tier keys." }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Omitted for API-tier keys." } } } } }, "PersonEmailError": { "type": "object", "required": [ "success", "error", "statusCode" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "MISSING_IDENTIFIER", "INVALID_ID", "INVALID_IDENTIFIER", "INSUFFICIENT_CREDITS", "UPGRADE_REQUIRED", "PERSON_NOT_FOUND", "EMAIL_NOT_FOUND" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true, "properties": { "help": { "type": "string" }, "current_tier": { "type": "string" }, "credits_needed": { "type": "integer", "nullable": true }, "monthly_credits_remaining": { "type": "integer", "nullable": true }, "purchased_credits_remaining": { "type": "integer", "nullable": true }, "email_unlock_limit_exceeded": { "type": "boolean" }, "email_unlock_limit": { "type": "integer", "nullable": true }, "email_unlock_used": { "type": "integer", "nullable": true } } } } }, "statusCode": { "type": "integer", "enum": [ 400, 402, 403, 404 ] } } }, "PersonCurrentCompany": { "type": "object", "nullable": true, "description": "Current employer summary. Null when the person has no current employer.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "permalink": { "type": "string", "nullable": true, "description": "Fundable permalink for the company" }, "domain": { "type": "string", "nullable": true } } }, "EmploymentRecord": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "company_id": { "type": "string", "nullable": true }, "company_url": { "type": "string", "nullable": true, "format": "uri" }, "location": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "start_date": { "type": "string", "format": "date", "nullable": true }, "end_date": { "type": "string", "format": "date", "nullable": true, "description": "null if current position" }, "is_current": { "type": "boolean" } } }, "EducationRecord": { "type": "object", "properties": { "school_name": { "type": "string", "nullable": true }, "school_id": { "type": "string", "nullable": true }, "school_url": { "type": "string", "nullable": true, "format": "uri" }, "degree": { "type": "string", "nullable": true }, "field_of_study": { "type": "string", "nullable": true }, "start_date": { "type": "string", "nullable": true }, "end_date": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } } }, "Firm": { "type": "object", "description": "Firm (parent investor) the person invests under", "properties": { "id": { "type": "string", "nullable": true, "format": "uuid" }, "name": { "type": "string", "nullable": true }, "permalink": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "deal_count": { "type": "integer", "description": "Number of deals this person has done under this firm" }, "last_deal_date": { "type": "string", "format": "date", "nullable": true } } }, "InvestorHighlights": { "type": "object", "description": "Aggregated investor activity. Counts dedupe by deal across angel + firm contributions.", "properties": { "total_deal_count": { "type": "integer", "description": "Total tracked deals for this person", "example": 12 }, "lead_deal_count": { "type": "integer", "description": "Total deals the person led" }, "deal_count_last_12_months": { "type": "integer", "description": "Deals in the last 12 months (any role)" }, "lead_deal_count_last_12_months": { "type": "integer", "description": "Lead deals in the last 12 months" }, "most_recent_deal_date": { "type": "string", "format": "date", "nullable": true }, "top_industries": { "type": "array", "description": "Top portfolio industries by deal count (max 5)", "items": { "type": "object", "properties": { "name": { "type": "string" }, "permalink": { "type": "string" }, "count": { "type": "integer" } } } }, "top_locations": { "type": "array", "description": "Top portfolio company cities by deal count (max 5)", "items": { "type": "object", "properties": { "name": { "type": "string" }, "full_name": { "type": "string" }, "permalink": { "type": "string" }, "type": { "type": "string", "example": "CITY" }, "count": { "type": "integer" } } } }, "top_round_types": { "type": "array", "description": "Top financing round types by deal count (max 5)", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "SERIES_A" }, "count": { "type": "integer" } } } } } }, "PersonDeal": { "type": "object", "description": "Deal returned by the /person/deals endpoint. Same shape as deals returned by /company/deals.", "properties": { "id": { "type": "string", "format": "uuid" }, "round_type": { "type": "string", "nullable": true }, "extension": { "type": "boolean", "nullable": true }, "intermediate": { "type": "string", "nullable": true }, "pre": { "type": "boolean", "nullable": true }, "date": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "total_round_raised": { "type": "number", "nullable": true }, "deal_descriptions": { "type": "object", "nullable": true, "properties": { "short_description": { "type": "string", "nullable": true }, "long_description": { "type": "string", "nullable": true } } }, "company_id": { "type": "string", "format": "uuid" }, "investor_ids": { "type": "array", "description": "UUIDs of firm investors participating in this deal. Angels are surfaced separately in `angel_investor_ids`.", "items": { "type": "string", "format": "uuid" } }, "angel_investor_ids": { "type": "array", "description": "UUIDs of angel investors (people) on this deal. Resolve via `/people/{id}`. Empty array when no angels.", "items": { "type": "string", "format": "uuid" } }, "financings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "size_usd": { "type": "number", "nullable": true }, "size_native": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true } } } }, "valuation": { "type": "object", "nullable": true, "properties": { "valuation_currency": { "type": "string", "nullable": true }, "valuation_usd": { "type": "number", "nullable": true }, "valuation_native": { "type": "number", "nullable": true }, "type": { "type": "string" } } }, "articles": { "type": "array", "description": "Related articles/sources for this deal. Always included; empty when no sources exist.", "items": { "$ref": "#/components/schemas/DealArticle" } } }, "required": [ "id", "round_type", "extension", "intermediate", "pre", "date", "created_at", "total_round_raised", "deal_descriptions", "company_id", "investor_ids", "angel_investor_ids", "financings", "valuation", "articles" ] }, "PaginationMeta": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total matching results across all pages", "example": 1250 }, "page": { "type": "integer", "example": 0 }, "page_size": { "type": "integer", "example": 25 }, "credits_used": { "type": "integer", "example": 25 }, "credit_source": { "type": "string", "nullable": true, "enum": [ "monthly", "purchased" ] }, "monthly_credits_remaining": { "type": "integer", "nullable": true, "example": 990 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "example": 500 } } }, "PeopleAuthError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "AUTH_ERROR", "INVALID_API_KEY", "INACTIVE_API_KEY" ] }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "help": { "type": "string" } } } } } } }, "PeopleValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "validOptions": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "UnknownParamError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNKNOWN_PARAMETER" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "unknownParameters": { "type": "array", "items": { "type": "string" } }, "allowedParameters": { "type": "array", "items": { "type": "string" } } } } } } } }, "InvalidIdentifierError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INVALID_IDENTIFIER" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "help": { "type": "string" } } } } } } }, "PeopleNotFoundError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "PERSON_NOT_FOUND" }, "message": { "type": "string", "example": "Person not found" }, "details": { "type": "object", "properties": { "help": { "type": "string" } } } } } } }, "PeopleRateLimitError": { "type": "object", "description": "Per-minute API rate limit exceeded", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "RATE_LIMIT_EXCEEDED" }, "message": { "type": "string", "example": "Rate limit exceeded. Maximum 200 requests per minute." }, "details": { "type": "object", "properties": { "limit": { "type": "integer", "example": 200 }, "window": { "type": "string", "example": "60 seconds" }, "help": { "type": "string" } } } } } }, "required": [ "error" ] }, "SemanticUsageLimitError": { "type": "object", "description": "Monthly semantic-search usage limit exceeded. Only returned when the request included\n`company.search_query` or `investor.deals.search_query`.\n", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "USAGE_LIMIT_EXCEEDED" }, "message": { "type": "string", "example": "Search limit exceeded" }, "details": { "type": "object", "properties": { "failed_block": { "type": "string", "enum": [ "company", "investor.deals" ], "description": "Which semantic call hit the limit. Optional \u2014 only present on the unified people endpoint, which can issue two semantic calls per request." }, "currentUsage": { "type": "integer", "description": "Current monthly semantic-search count", "example": 1000 }, "limit": { "type": "integer", "description": "Monthly semantic-search ceiling for this API key tier", "example": 1000 }, "help": { "type": "string", "example": "You have reached your search usage limit. Upgrade your plan or wait for the next cycle." } } } } } }, "required": [ "error" ] }, "SemanticTimeoutError": { "type": "object", "description": "Semantic search timed out. Only returned when the request included\n`company.search_query` or `investor.deals.search_query`.\n", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "TIMEOUT" }, "message": { "type": "string", "example": "The semantic search operation timed out. Please try a simpler query." }, "details": { "type": "object", "properties": { "failed_block": { "type": "string", "enum": [ "company", "investor.deals" ], "description": "Which semantic call timed out" }, "help": { "type": "string", "example": "Try a simpler query or fewer filters" } } } } } }, "required": [ "error" ] }, "PeopleInsufficientCreditsError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INSUFFICIENT_CREDITS" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "credits_needed": { "type": "integer", "nullable": true }, "monthly_credits_remaining": { "type": "integer" }, "purchased_credits_remaining": { "type": "integer" }, "help": { "type": "string" } } } } } }, "required": [ "error" ] }, "PeopleServerError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "INTERNAL_SERVER_ERROR" }, "message": { "type": "string" } } } } }, "AlertConfiguration": { "type": "object", "description": "Alert configuration metadata including filters and settings", "properties": { "configuration_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the alert configuration", "example": "550e8400-e29b-41d4-a716-446655440000" }, "configuration_name": { "type": "string", "description": "User-defined name for the alert", "example": "AI Startups Series A" }, "frequency": { "type": "string", "description": "How often the alert runs", "enum": [ "DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY" ], "example": "WEEKLY" }, "description": { "type": "string", "description": "Alert description combining custom, alert, and semantic descriptions", "example": "Track AI and ML startups raising Series A funding" }, "filters": { "type": "object", "description": "Alert filter criteria", "properties": { "industries": { "type": "array", "items": { "type": "string" }, "description": "Industry permalinks to filter by. Use /industry/search to find permalinks; a value that is not an exact permalink is silently ignored.", "example": [ "artificial-intelligence", "machine-learning" ] }, "super_categories": { "type": "array", "items": { "type": "string" }, "description": "Super category permalinks to filter by. Use /industry/search to find permalinks; a value that is not an exact permalink is silently ignored.", "example": [ "software" ] }, "locations": { "type": "array", "items": { "type": "string" }, "description": "Location permalinks to filter by. Use /location/search to find permalinks; a value that is not an exact permalink is silently ignored.", "example": [ "san-francisco-bay-area", "new-york-new-york" ] }, "financing_types": { "type": "array", "items": { "type": "string" }, "description": "Types of financing rounds to include. NOTE: the Alerts API accepts human-readable round names here (e.g. \"Series A\", \"Seed\"), which differs from /deals and /companies \u2014 those use the canonical enum (e.g. SERIES_A, SEED).", "example": [ "Series A", "Series B" ] }, "deal_size_min": { "type": "number", "nullable": true, "description": "Minimum deal size in USD", "example": 1000000 }, "deal_size_max": { "type": "number", "nullable": true, "description": "Maximum deal size in USD", "example": 10000000 }, "num_employees": { "type": "array", "items": { "type": "string" }, "description": "Employee count ranges", "example": [ "1-10", "11-50", "51-100" ] }, "investors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Investor identifier" }, "name": { "type": "string", "description": "Investor name" } } }, "description": "Specific investors to filter by", "example": [ { "id": "sequoia-capital", "name": "Sequoia Capital" } ] }, "companies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Company identifier" }, "name": { "type": "string", "description": "Company name" } } }, "description": "Specific companies to filter by", "example": [ { "id": "stripe", "name": "Stripe" } ] } } } }, "required": [ "configuration_id", "configuration_name", "frequency", "description", "filters" ] }, "Alert": { "type": "object", "properties": { "alertId": { "type": "string", "format": "uuid", "description": "Unique identifier for the alert configuration", "example": "550e8400-e29b-41d4-a716-446655440000" }, "alertName": { "type": "string", "description": "Name of the alert configuration", "example": "Weekly AI Funding Deals" }, "alertFrequency": { "type": "string", "description": "Frequency setting of the alert", "enum": [ "DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY" ], "example": "WEEKLY" }, "totalDealCount": { "type": "integer", "description": "Total number of deals for this alert", "example": 25 }, "deals": { "type": "array", "description": "Array of deals that matched the alert criteria (flattened from all time periods, sorted by date DESC)", "items": { "$ref": "#/components/schemas/SimplifiedDeal" } } }, "required": [ "alertId", "alertName", "alertFrequency", "totalDealCount", "deals" ] }, "SimplifiedDeal": { "type": "object", "description": "Simplified deal structure optimized for API consumption.\nFlattens company information and removes nested structures for easier integration.\nDeals are sorted by date descending (newest first) and duplicates are removed.\n", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the deal", "example": "550e8400-e29b-41d4-a716-446655440000" }, "company_id": { "type": "string", "description": "Unique identifier for the company", "example": "abc123" }, "company_name": { "type": "string", "nullable": true, "description": "Company name", "example": "Acme AI Corp" }, "company_guru_permalink": { "type": "string", "nullable": true, "description": "Fundable permalink for the company", "example": "acme-ai-corp" }, "round_type": { "type": "string", "nullable": true, "description": "Type of funding round", "example": "SERIES_A" }, "date": { "type": "string", "format": "date-time", "nullable": true, "description": "Date of the funding round (ISO 8601 format)", "example": "2024-01-15T00:00:00.000Z" }, "total_round_raised": { "type": "number", "nullable": true, "description": "Total amount raised in the round (USD $M)", "example": 25 }, "company_website": { "type": "string", "nullable": true, "description": "Company website domain", "example": "acme.com" }, "company_linkedin": { "type": "string", "nullable": true, "description": "Company LinkedIn URL", "example": "https://linkedin.com/company/acme" }, "location": { "type": "object", "description": "Company location details", "properties": { "city": { "type": "string", "nullable": true, "description": "City name", "example": "San Francisco" }, "state": { "type": "string", "nullable": true, "description": "State/province name", "example": "California" }, "country": { "type": "string", "nullable": true, "description": "Country name", "example": "United States" }, "region": { "type": "string", "nullable": true, "description": "Geographic region name", "example": "North America" } } }, "deal_short_description": { "type": "string", "nullable": true, "description": "Brief description of the deal", "example": "Series A funding round" }, "deal_long_description": { "type": "string", "nullable": true, "description": "Detailed description of the deal", "example": "Company raised $25M in Series A funding led by Acme Ventures" }, "reasoning": { "type": "string", "nullable": true, "description": "AI-generated reasoning for why this deal matched the alert criteria", "example": "This deal matches your AI startups criteria with focus on machine learning" }, "articles": { "type": "array", "description": "News articles related to this deal", "items": { "type": "object", "properties": { "link": { "type": "string", "description": "URL to the article", "example": "https://techcrunch.com/article" }, "is_primary": { "type": "boolean", "description": "Whether this is the primary article for the deal", "example": true }, "publishedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Article publication date (ISO 8601 format)", "example": "2024-01-15T00:00:00.000Z" } } } } }, "required": [ "id", "company_id", "company_name", "company_guru_permalink", "round_type", "date", "total_round_raised", "company_website", "company_linkedin", "location", "deal_short_description", "deal_long_description", "reasoning", "articles" ], "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "company_id": "abc123", "company_name": "Acme AI Corp", "company_guru_permalink": "acme-ai-corp", "round_type": "SERIES_A", "date": "2024-01-15T00:00:00.000Z", "total_round_raised": 25, "company_website": "acme.com", "company_linkedin": "https://linkedin.com/company/acme", "location": { "city": "San Francisco", "state": "California", "country": "United States", "region": "North America" }, "deal_short_description": "Series A funding round", "deal_long_description": "Company raised $25M in Series A funding led by Acme Ventures", "reasoning": "This deal matches your AI startups criteria with focus on machine learning and enterprise software", "articles": [ { "link": "https://techcrunch.com/article", "is_primary": true, "publishedDate": "2024-01-15T00:00:00.000Z" } ] } }, "TierAccessError": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "enum": [ "API_TIER_REQUIRED" ] }, "message": { "type": "string", "example": "This endpoint requires a Pro+ or Enterprise plan." }, "details": { "type": "object", "required": [ "current_tier", "help" ], "properties": { "current_tier": { "type": "string", "example": "Pro" }, "help": { "type": "string", "example": "Upgrade to Pro+ or Enterprise to access this endpoint." } } } } } } }, "AlertsValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "UNKNOWN_PARAMETER" ], "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Invalid request parameters" }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The parameter name that failed validation", "example": "alertId" }, "value": { "type": "string", "description": "The invalid value provided", "example": "not-a-uuid" }, "message": { "type": "string", "description": "Human-readable error message", "example": "Alert ID must be a valid UUID" }, "code": { "type": "string", "description": "Machine-readable error code", "example": "INVALID_ALERT_ID" } } } }, "help": { "type": "string", "example": "Please check your request parameters and ensure they meet the required format and constraints." } } } } }, "statusCode": { "type": "integer", "example": 422 } }, "required": [ "success", "error" ] }, "MissingParametersError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "MISSING_PARAMETERS" }, "message": { "type": "string", "example": "Missing required parameters" }, "details": { "type": "object", "properties": { "missingParams": { "type": "array", "items": { "type": "string" }, "example": [ "alert_ids", "start_date" ] }, "help": { "type": "string", "example": "Please provide all required parameters: alert_ids, start_date, end_date" } } } } }, "statusCode": { "type": "integer", "example": 400 } }, "required": [ "success", "error" ] }, "LocationSearchResult": { "type": "object", "properties": { "permalink": { "type": "string", "description": "Location permalink identifier", "example": "san-francisco-california" }, "name": { "type": "string", "description": "Location name", "example": "San Francisco" }, "location_type": { "type": "string", "description": "Type of location", "enum": [ "REGION", "COUNTRY", "STATE", "CITY" ], "example": "CITY" } } }, "IndustrySearchResult": { "type": "object", "properties": { "permalink": { "type": "string", "description": "Industry or super category permalink identifier", "example": "artificial-intelligence" }, "name": { "type": "string", "description": "Industry or super category name", "example": "Artificial Intelligence" }, "industry_type": { "type": "string", "description": "Type of result", "enum": [ "INDUSTRY", "SUPER_CATEGORY" ], "example": "INDUSTRY" } } }, "OtherAuthError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "AUTH_ERROR", "INVALID_API_KEY", "INACTIVE_API_KEY" ], "example": "AUTH_ERROR" }, "message": { "type": "string", "example": "API key not provided" }, "details": { "type": "object", "properties": { "help": { "type": "string", "example": "Please provide your API key in the Authorization header" }, "format": { "type": "string", "example": "Bearer vg_your_api_key_here" }, "example": { "type": "object", "properties": { "header": { "type": "string", "example": "Authorization: Bearer vg_your_api_key_here" }, "curl": { "type": "string", "example": "curl -H 'Authorization: Bearer vg_your_api_key_here' https://www.tryfundable.ai/api/v1/location/search?name=san+francisco" } } }, "documentation": { "type": "string", "example": "Visit our documentation for more information about authentication" } } } } } }, "required": [ "error" ] } } }, "tags": [ { "name": "deals", "description": "Venture capital deals data" }, { "name": "companies", "description": "Company data, search, and discovery operations" }, { "name": "investors", "description": "Investor data and search operations" }, { "name": "people", "description": "People search and detail operations" }, { "name": "alerts", "description": "Saved alert configurations and deal data" }, { "name": "locations", "description": "Location search and utility operations" }, { "name": "industries", "description": "Industry and super category search operations" } ], "x-sourceSpecs": [ "/openapi/openapi-deals.yaml", "/openapi/openapi-companies.yaml", "/openapi/openapi-investors.yaml", "/openapi/openapi-people.yaml", "/openapi/openapi-alerts.yaml", "/openapi/openapi-other.yaml" ] }