openapi: 3.2.0
info:
  title: Daloopa Fundamentals API
  version: 2.0.0
  description: Comprehensive API for financial data and analytics
  contact:
    name: Daloopa API Support
    email: api-support@daloopa.com
  license:
    name: Proprietary
servers:
- url: https://app.daloopa.com
  description: Production
tags:
- name: Fundamentals
  description: Financial Fundamentals Data
paths:
  /api/v3/companies/fundamentals:
    get:
      operationId: get_company_fundamentals_v3
      description: Retrieve paginated fundamental financial data for a specific company and time periods.
      summary: Get Company Fundamental Data
      parameters:
      - in: query
        name: calendar_periods
        schema:
          type: array
          items:
            type: string
        description: 'List of calendar reporting periods to include. Mutually exclusive with `fiscal_periods`. Accepted formats: `YYYYQ[1-4]` (quarters), `YYYYH[1-2]` (half-years), or `YYYYFY` (fiscal year). Example: `?calendar_periods=2023Q4&calendar_periods=2024Q1`.'
        explode: true
        style: form
        examples:
          QuarterlyCalendarPeriods:
            value:
            - 2023Q4
            - 2024Q1
            - 2024Q2
            summary: Quarterly Calendar Periods
            description: Recent quarterly calendar periods
      - in: query
        name: company_id
        schema:
          type: integer
        description: The unique identifier of the company.
        required: true
        examples:
          AppleInc.:
            value: 2
            summary: Apple Inc.
            description: Example company ID for Apple Inc.
      - in: query
        name: created_at
        schema:
          type: string
          format: date-time
        description: Minimum creation timestamp (ISO-8601). Used together with `updated_at` to form an inclusive range; `created_at` must be ≤ `updated_at`.
        examples:
          CreatedAfter:
            value: '2025-06-01T00:00:00Z'
            summary: Created After
            description: Return records created on/after June 1, 2025 (UTC).
      - in: query
        name: document_id
        schema:
          type: integer
        description: Filter fundamentals to those from a specific document ID.
      - in: query
        name: fiscal_periods
        schema:
          type: array
          items:
            type: string
        description: 'List of fiscal reporting periods to include. Mutually exclusive with `calendar_periods`. Accepted formats: `YYYYQ[1-4]` (quarters), `YYYYH[1-2]` (half-years), or `YYYYFY` (fiscal year). Example: `?fiscal_periods=2023Q4&fiscal_periods=2024Q1`.'
        explode: true
        style: form
        examples:
          QuarterlyFiscalPeriods:
            value:
            - 2023Q4
            - 2024Q1
            - 2024Q2
            summary: Quarterly Fiscal Periods
            description: Recent quarterly fiscal periods
      - in: query
        name: include_derived
        schema:
          type: boolean
        description: Whether to include derived fundamentals. `true` = include derived fundamentals, `false` = exclude derived fundamentals, omit for default behavior (excludes derived).
        examples:
          IncludeDerived:
            value: true
            summary: Include Derived
          ExcludeDerived:
            value: false
            summary: Exclude Derived
      - in: query
        name: limit
        schema:
          type: integer
        description: Number of results to return per page.
      - in: query
        name: offset
        schema:
          type: integer
        description: The initial index from which to return results.
      - in: query
        name: restated
        schema:
          type: boolean
        description: Filter by restatement status. `true` = only restated values, `false` = only original values, omit to include both.
        examples:
          OnlyRestated:
            value: true
            summary: Only Restated
          OnlyOriginal:
            value: false
            summary: Only Original
      - in: query
        name: sections
        schema:
          type: array
          items:
            type: string
            enum:
            - BALANCE_SHEET
            - CASH_FLOW_STATEMENT
            - DEPRECATED_DATA
            - GAAP_TO_NON_GAAP
            - GEOGRAPHICAL_INFORMATION
            - GUIDANCE
            - INCOME_STATEMENT
            - KPIS
            - OTHER_INFORMATION
            - SEGMENTAL_INFORMATION
        description: Optional list of financial statement sections to filter by. Narrows the response to fundamentals whose finantial section matches one of the provided values.
        explode: true
        style: form
        examples:
          IncomeStatementAndBalanceSheet:
            value:
            - INCOME_STATEMENT
            - BALANCE_SHEET
            summary: Income Statement and Balance Sheet
            description: Restrict the response to two top-level sections.
      - in: query
        name: series_ids
        schema:
          type: array
          items:
            type: integer
        description: 'Optional list of series IDs to filter by. Example: `?series_ids=101&series_ids=205`.'
        explode: true
        style: form
        examples:
          MultipleSeries:
            value:
            - 101
            - 205
            - 309
            summary: Multiple Series
            description: Filter to a subset of series
      - in: query
        name: unit
        schema:
          type: string
          enum:
          - actual
          - billion
          - million
          - thousand
          - trillion
        description: Optional target unit to convert values to. When omitted, values are returned as-reported. Values reported in a currency (e.g. dollars) or as a percentage are not convertible and are returned unchanged.
        examples:
          ConvertToMillions:
            value: million
            summary: Convert to millions
            description: Return values scaled to millions.
      - in: query
        name: updated_at
        schema:
          type: string
          format: date-time
        description: Maximum update timestamp (ISO-8601). Used together with `created_at` to form an inclusive range; `created_at` must be ≤ `updated_at`.
        examples:
          UpdatedBefore:
            value: '2025-08-01T23:59:59Z'
            summary: Updated Before
            description: Return records updated on/before Aug 1, 2025 (UTC).
      tags:
      - Fundamentals
      security:
      - apiKeyAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFundamentalList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                  status_code:
                    type: integer
                  message:
                    type: string
          description: ''
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
  /api/v3/companies/fundamentals/series:
    get:
      operationId: get_fundamentals_series
      description: Look up series and company context for up to 100 fundamental IDs. IDs not in the dataset visible to the user are silently omitted from the response.
      summary: Get Fundamental Series
      parameters:
      - in: query
        name: ids
        schema:
          type: array
          items:
            type: integer
            minimum: 1
          maxItems: 100
        description: List of fundamental IDs to look up (max 100)
        required: true
      tags:
      - Fundamentals
      security:
      - apiKeyAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: integer
                      series_id:
                        type: integer
                      full_series_name:
                        type: string
                      category:
                        type: string
                      label:
                        type: string
                      company_id:
                        type: integer
                      company_name:
                        type: string
                      company_ticker:
                        type: string
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                  status_code:
                    type: integer
                  message:
                    type: string
          description: ''
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
  /api/v3/companies/fundamental-updates:
    get:
      operationId: get_fundamental_updates
      description: Retrieve updates and changes to fundamental financial data for a specific company since a given timestamp.
      summary: Get Fundamental Data Updates
      parameters:
      - in: query
        name: company_id
        schema:
          type: integer
        description: The unique identifier of the company
        required: true
        examples:
          AppleInc.:
            value: 2
            summary: Apple Inc.
            description: Example company ID for Apple Inc.
      - in: query
        name: limit
        schema:
          type: integer
        description: Number of results to return per page
      - in: query
        name: offset
        schema:
          type: integer
        description: The initial index from which to return the results
      - in: query
        name: since
        schema:
          type: string
          format: date-time
        description: Timestamp to get updates since (ISO 8601 format)
        examples:
          RecentUpdates:
            value: '2024-01-01T00:00:00Z'
            summary: Recent Updates
            description: Get all updates since the beginning of 2024
      tags:
      - Fundamentals
      security:
      - apiKeyAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedFundamentalUpdatesList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                  status_code:
                    type: integer
                  message:
                    type: string
          description: ''
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
        '429':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
          description: ''
components:
  schemas:
    FundamentalDerivedComponents:
      type: object
      properties:
        formula:
          type: string
        components:
          type: array
          items:
            $ref: '#/components/schemas/FundamentalDerivedComponent'
      required:
      - components
      - formula
    Fundamental:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the fundamental datapoint
        label:
          type: string
          description: Display label for the datapoint (e.g., revenue, ebitda)
        category:
          type: string
          description: Category grouping for the datapoint (income, balance sheet, cash flow, etc.)
        restated:
          type: boolean
          description: Indicates whether the value has been restated
        document_type:
          type: string
          description: Type of the source document (e.g., 10-K, 10-Q, EX-99.1, EX-99.2)
        filing_type:
          type: string
          description: Filing type the datapoint originates from (e.g., 10-K, 10-Q)
        series_id:
          type: integer
          description: Identifier of the series associated with this datapoint
        title:
          type: string
          description: Full title of the series as presented in the model
        value_raw:
          type: number
          format: double
          description: Original reported numeric value before normalization
        value_normalized:
          type: number
          format: double
          description: Value normalized to the system's standard unit/scale
        unit:
          type: string
          description: Unit of measure for the value (e.g., USD)
        original_unit:
          type:
          - string
          - 'null'
          description: The unit the value was originally reported in, before any conversion
        conversion_factor:
          type: string
          description: Multiplier applied to convert value_normalized from original_unit to unit. Equals '1' when no conversion was applied.
        calendar_period:
          type: string
          description: Calendar period for the datapoint (YYYYQQ/HH/FY format)
        fiscal_period:
          type: string
          description: Fiscal period for the datapoint (YYYYQQ/HH/FY format)
        span:
          type: string
          description: Time span covered by the datapoint (e.g., Q1, FY, trailing 12 months)
        fiscal_date:
          type: string
          format: date
          description: Fiscal period end date associated with the datapoint
        document_id:
          type: integer
          description: Identifier of the source document for this datapoint
        filing_date:
          type: string
          format: date
          description: Date when the underlying filing was made public
        document_released_at:
          type: string
          format: date-time
          description: Timestamp when the source document was released
        created_at:
          type: string
          format: date-time
          description: Timestamp when the datapoint was first created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the datapoint was last updated
        derived_components:
          allOf:
          - $ref: '#/components/schemas/FundamentalDerivedComponents'
          description: Computation metadata for derived fundamentals (formula and component values). Null for non-derived fundamentals.
      required:
      - calendar_period
      - category
      - conversion_factor
      - created_at
      - document_id
      - document_released_at
      - document_type
      - filing_date
      - filing_type
      - fiscal_date
      - fiscal_period
      - id
      - label
      - original_unit
      - restated
      - series_id
      - span
      - title
      - unit
      - updated_at
      - value_normalized
      - value_raw
    ValueErrorDetails:
      type: object
      properties:
        field_changed:
          type: string
          description: Name of the field that was corrected in the datapoint
        old_value:
          type: number
          format: double
          description: Value before the correction was applied
        new_value:
          type: number
          format: double
          description: Value after the correction was applied
        fundamental_id:
          type: integer
          description: Identifier of the affected fundamental datapoint
        series_id:
          type: integer
          description: Identifier of the related series for the datapoint
      required:
      - field_changed
      - fundamental_id
      - new_value
      - old_value
      - series_id
    FundamentalDerivedComponent:
      type: object
      properties:
        component:
          type: string
        fundamental_id:
          type: integer
        value:
          type: number
          format: double
      required:
      - component
      - fundamental_id
      - value
    FundamentalUpdates:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the update record
        type:
          type: string
          description: Type of update event (e.g., correction, restatement)
        period:
          type: string
          description: Period associated with the update (YYYYQQ/HH/FY format)
        run_date:
          type: string
          format: date-time
          description: Timestamp when the update process was executed
        details:
          allOf:
          - $ref: '#/components/schemas/ValueErrorDetails'
          description: Details describing the change applied to the datapoint
      required:
      - details
      - id
      - period
      - run_date
      - type
    PaginatedFundamentalUpdatesList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/FundamentalUpdates'
    PaginatedFundamentalList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type:
          - string
          - 'null'
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/Fundamental'
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: basic
      description: 'Basic authentication with base64-encoded credentials. Format: "Basic base64(email:apiKey)"'