> ## 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 Deals > Retrieve venture capital deals with advanced filtering, pagination, and sorting. ## Request Body Structure Send a JSON body with up to 4 filter sections plus pagination/sort at the top level: - `identifiers` - Look up specific deals by UUID - `deal` - Filter by deal attributes (financing type, size, date) - `company` - Filter by company attributes (location, industry, size) - `investors` - Filter by investor participation (firms or people, by UUID) 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-deals.yaml POST /deals openapi: 3.0.3 info: title: Fundable Deals API description: > API for accessing venture capital deals data with advanced filtering capabilities. ## 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. ## Request Body Structure Send a JSON body with up to 4 filter sections plus pagination/sort at the top level: - `identifiers` - Look up specific deals by UUID - `deal` - Filter by deal attributes (financing type with pre/extension modifiers, size, date) - `company` - Filter by company attributes (location, industry, size, IPO status) - `investors` - Filter by investor participation (firms or people, by UUID) ## Parameter Validation This API enforces strict parameter validation: - **Unknown Fields**: Any field not in the allowed list will result in a `422 UNKNOWN_PARAMETER` error - **Enum Values**: Parameters like `financing_types`, `sort_by`, `employee_count`, and `ipo_status` only accept exact enum values - **Data Types**: Numeric parameters must be valid numbers, dates must be valid ISO 8601 format - **Array Parameters**: Cannot be empty arrays; provide values or omit entirely ## Validation Errors Invalid parameters return detailed error responses with: - Specific error codes (e.g., `INVALID_FINANCING_TYPE`, `UNKNOWN_PARAMETER`) - Clear error messages explaining what's wrong - Valid options for enum parameters - Help text and documentation links version: 2.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: deals description: Venture capital deals data 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. ## Request Body Structure Send a JSON body with up to 4 filter sections plus pagination/sort at the top level: - `identifiers` - Look up specific deals by UUID - `deal` - Filter by deal attributes (financing type, size, date) - `company` - Filter by company attributes (location, industry, size) - `investors` - Filter by investor participation (firms or people, by UUID) 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 **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_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' components: 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: $ref: '#/components/schemas/Valuation' nullable: true description: Valuation information for this deal articles: type: array description: > Related articles/sources for this deal. Only included for Enterprise (API tier) users. Omitted entirely for other tiers. items: $ref: '#/components/schemas/DealArticle' required: - id - company_id - investor_ids - angel_investor_ids - financings 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 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 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 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 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]` ````