{ "openapi": "3.0.3", "info": { "title": "Fundable API", "description": "Canonical OpenAPI specification for the Fundable API. This file bundles the Deals, Companies, Investors, People, Alerts, Location, and Industry endpoints.", "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": "Search and filter funding rounds by company, investor, and round details", "description": "Retrieve venture capital deals with advanced filtering, pagination, and sorting.\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 — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "422": { "description": "Unprocessable Entity - Parameter validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "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": "Retrieve detailed information about a single venture capital deal by its unique identifier", "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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "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 } } } } } }, "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": "Retrieve detailed investor information for a single deal, including lead status, personnel, and investor profile links.", "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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "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" } } } } } } } }, "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": "Retrieve detailed company information using any supported identifier format.\nThe API intelligently detects the identifier type and queries accordingly.\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\") — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "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": "Retrieve all deals for a company using any supported identifier format.\nThe API intelligently detects the identifier type and queries accordingly.\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\") — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "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" } } } } } } } } } }, "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": "Look up companies using one of four search methods. Exactly one parameter must be provided.\n\n**Search types:**\n- `name` — Fuzzy name search with relevance scoring\n- `domain` — Company domain or full URL\n- `linkedin` — LinkedIn company URL\n- `crunchbase` — 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\") — 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": "Search and filter companies with recent funding details", "description": "Retrieve companies with advanced filtering, pagination, sorting, and optional AI-powered semantic search.\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 — a flexible replacement for an industry tag. Use it to target a niche industry or specific product type by describing what the company does — its product, technology, or business model (e.g. \"AI-powered medical imaging diagnostics\" or \"vertical SaaS for dental practices\"). Best for product/category targeting the fixed industry list can't capture. Do NOT use it for other attributes like stage, location, funding, or employee count — apply those with the dedicated filter fields instead. Results include a similarity score and are sorted by relevance.", "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 — 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 — 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 — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "422": { "description": "Unprocessable Entity - Unknown parameter provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompaniesValidationError" } } } }, "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": "List and filter investors", "description": "Retrieve a paginated list of investors with optional filtering.\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, each investor in the response includes `filtered_deal_count` and `filtered_lead_count`.\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 — a flexible replacement for an industry tag.\nUse it to target a niche industry or specific product type by\ndescribing what those companies do — their product, technology, or\nbusiness model (e.g. \"climate-focused carbon capture hardware\"). Do\nNOT use it for other attributes like stage, location, or funding —\napply those with the dedicated `company_investments` and `investor`\nfilter fields instead. When provided, results are ranked by how\nclosely an investor's portfolio matches the query rather than the\ndefault sort.\n", "example": "climate-focused carbon capture hardware" }, "min_relevance": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum relevance score threshold (0–1) 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** — Date of most recent investment (newest first)\n- **recent_deals** — Deals in last 12 months (highest first)\n- **deals_led_ltm** — Lead deals in last 12 months (highest first)\n- **total_deals** — All-time deal count (highest first)\n- **matching_deals** — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "422": { "description": "Unknown parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParameterValidationError" } } } }, "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": "Retrieve detailed investor information using any supported identifier format.\nThe API intelligently detects the identifier type and queries accordingly.\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\") — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "404": { "description": "Investor not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestorsNotFoundError" } } } }, "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": "Retrieve all deals for an investor using any supported identifier format.\nThe API intelligently detects the identifier type and queries accordingly.\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\") — 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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" } } } }, "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" } } } } } } } } } }, "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": "Look up investors using one of four search methods. Exactly one parameter must be provided.\n\n**Search types:**\n- `name` — Fuzzy name search with relevance scoring\n- `domain` — Investor domain or full URL\n- `linkedin` — LinkedIn company URL\n- `crunchbase` — 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\") — 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": "Search people with cross-type filters and optional semantic search", "description": "Retrieve people with advanced filtering, pagination, sorting, and optional AI-powered semantic search.\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 — 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 — a flexible replacement for an industry tag. Use it to target a niche industry or specific product type by describing what that company does — its product, technology, or business model (e.g. \"climate tech carbon accounting software\"). Do NOT use it for other attributes like stage, location, or funding — apply those with the dedicated filter fields instead. Overrides explicit sort_by — results are ordered by relevance.", "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 — 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 — a flexible replacement for an industry tag. Use it to target a niche industry or specific product type by describing what those companies do — their product, technology, or business model (e.g. \"AI infrastructure for model training\"). Do NOT use it for other attributes like stage, location, or funding — apply those with the dedicated filter fields instead. Overrides explicit sort_by — results are ordered by relevance.", "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 — 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` — per-minute API rate limit\n- `USAGE_LIMIT_EXCEEDED` — 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": "Retrieve detailed person information using any supported identifier format.\nThe API intelligently detects the identifier type and queries accordingly.\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/deals": { "get": { "summary": "Get deals a person participated in (as an investor) by identifier", "description": "Retrieve all deals a person has participated in as an investor (angel deals + lead/firm deals)\nusing any supported identifier format. The API intelligently detects the identifier type and queries accordingly.\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": { "type": "object", "description": "Deal record (same shape as deals returned by `/api/v1/company/deals`)" } } } }, "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" } } } }, "402": { "description": "Insufficient credits to complete request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleInsufficientCreditsError" } } } }, "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" } } } } } } } }, "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": "Look up people using one of five search methods. Exactly one parameter must be provided.\n\n**Search types:**\n- `name` — Fuzzy name search across both investors AND non-investor people (founders, employees). Returns up to 10 results.\n- `id` — Person UUID lookup (returns 0 or 1)\n- `linkedin` — LinkedIn person URL or slug\n- `crunchbase` — Crunchbase person URL or slug\n- `twitter` — 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 — 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\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- This endpoint is free and does not consume credits\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": { "total_count": { "type": "integer", "description": "Total number of deals across all alerts and periods", "example": 47 }, "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", "description": "Number of credits consumed by this request (always 0)", "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": 953 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "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": { "total_count": 47, "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": { "total_count": 0, "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" } } } }, "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\n**Important Notes:**\n- This endpoint is free and does not consume usage credits\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", "description": "Number of credits consumed by this request (always 0)", "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": 1000 }, "purchased_credits_remaining": { "type": "integer", "nullable": true, "description": "Remaining purchased credits (only included for non-API tier keys)", "example": 500 } } } }, "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" } } } }, "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": "Look up locations (cities, states, countries, regions) by name with fuzzy matching. The `name` parameter is required; `type` is optional.\n\n**Search types:**\n- `name` — Fuzzy name search with relevance scoring (required)\n- `type` — Optional filter by location type: `CITY`, `STATE`, `REGION`, or `COUNTRY`\n- `location_type` — 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": "Look up industries and super categories by name with fuzzy matching. The `name` parameter is required; `type` is optional.\n\n**Search types:**\n- `name` — Fuzzy name search with relevance scoring (required)\n- `type` — Optional filter by industry type: `INDUSTRY` or `SUPER_CATEGORY`\n- `industry_type` — 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.\nOnly included for Enterprise (API tier) users. Omitted entirely for other tiers.\n", "items": { "$ref": "#/components/schemas/DealArticle" } } }, "required": [ "id", "company_id", "investor_ids", "angel_investor_ids", "financings" ] }, "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 (Enterprise/API tier only)", "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" } } } } } }, "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" } } } }, "required": [ "id", "company_id", "investor_ids", "angel_investor_ids", "financings" ] }, "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 portfolio filters (present when portfolio filters are active)" }, "filtered_lead_count": { "type": "integer", "nullable": true, "description": "Number of lead deals matching portfolio filters (present when portfolio filters are active)" } } } ] }, "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" } } } }, "required": [ "id", "company_id", "investor_ids", "angel_investor_ids", "financings" ] }, "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 — 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" } } } } ] }, "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" } } } } } }, "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 — 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 — 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" } ] } }, "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" ] }