> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryfundable.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Companies > Retrieve companies with advanced filtering, pagination, sorting, and optional AI-powered semantic search. ## Request Body Structure Send a JSON body with up to 4 filter sections plus pagination/sort at the top level: - `identifiers` - Look up specific companies by UUID, domain, LinkedIn, or Crunchbase - `company` - Filter by company attributes (search, location, industry, size, etc.) - `latest_deal` - Filter by latest funding round attributes (type, size, date, investors) - `investors` - Filter by investors (firms or people) across all rounds Filtering by location, industry, or round type? Use **exact permalinks** — a wrong value for `locations`, `industries`, or `super_categories` returns zero results with no error. Resolve them via [`/location/search`](/api-reference/locations/search) and [`/industry/search`](/api-reference/industries/search) first. See [Filtering & Permalinks](/api-reference/filtering). ## OpenAPI ````yaml openapi/openapi-companies.yaml POST /companies openapi: 3.0.3 info: title: Fundable Companies API description: > API for accessing company data including search, detailed company information, and filtered company discovery. ## Authentication All API requests require authentication using an API key in the Authorization header. ## Rate Limits API usage is tracked and may be subject to monthly limits depending on your API key tier. ## Company Identifiers Companies can be identified using query parameters with any of the following formats: - `id` - UUID format (e.g., "?id=550e8400-e29b-41d4-a716-446655440000") - `domain` - Domain or full URL (e.g., "?domain=stripe.com" or "?domain=https://stripe.com") - `linkedin` - LinkedIn company URL (e.g., "?linkedin=https://linkedin.com/company/stripe") - `crunchbase` - Crunchbase organization URL (e.g., "?crunchbase=https://crunchbase.com/organization/stripe") ## Parameter Validation (for /companies endpoint) The /companies endpoint (POST) enforces strict validation on the JSON request body: - **Unknown Fields**: Any field not in the allowed set will result in a `422 UNKNOWN_PARAMETER` error - **Enum Values**: Fields like `financing_types`, `sort_by`, `employee_count`, and `ipo_status` only accept exact enum values - **Data Types**: Numeric fields must be valid numbers, dates must be valid ISO 8601 format - **Array Fields**: Cannot be empty arrays; provide values or omit the field entirely ## Semantic Search The /companies endpoint supports AI-powered semantic search via `company.search_query`. Think of it as a flexible replacement for an industry tag: use it to pinpoint a **niche industry or specific product type** by describing what a company does — its product, technology, or business model (e.g. "AI-powered medical imaging diagnostics" or "vertical SaaS for dental practices"). It is best for product/category targeting that the fixed industry list can't capture. It is not a keyword filter: do not put other attributes like stage, location, funding, or employee count in `search_query` — apply those with the dedicated filter fields instead, and combine them with semantic search. Results come back with a `similarity` score (0-1) and are sorted by relevance. version: 1.0.0 contact: name: Fundable API Support url: 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: [] tags: - name: companies description: Company data, search, and discovery operations paths: /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. ## Request Body Structure Send a JSON body with up to 4 filter sections plus pagination/sort at the top level: - `identifiers` - Look up specific companies by UUID, domain, LinkedIn, or Crunchbase - `company` - Filter by company attributes (search, location, industry, size, etc.) - `latest_deal` - Filter by latest funding round attributes (type, size, date, investors) - `investors` - Filter by investors (firms or people) across all rounds 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 as an **angel investor** OR as a **lead partner** of an investing firm. Resolve via `/people/{id}`. 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/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 - Unknown parameter provided 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' components: schemas: CompanyListItem: type: object description: >- Company object returned by the /companies list endpoint. Same shape as CompanyDetails. allOf: - $ref: '#/components/schemas/CompanyDetails' 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: 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 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 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 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 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 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: | API key authentication using Bearer token format. Format: `Authorization: Bearer vg_your_api_key_here` API keys follow the pattern: `vg_[12_hex_chars]_[32_base64url_chars]` ````