Login Register

API Documentation

Complete reference for the Fundamentals Hub API v2

πŸ” Authentication

All API requests require authentication using your API key in the request header: 

X-API-Key: fh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can create API keys in the API Keys tab.

🌐 Base URL

https://fundamentalshub.com/api/v2

AAPL Sample Response

The financials endpoint returns normalized SEC EDGAR statements as JSON. This sample is shortened to show the response shape. 

{
  "success": true,
  "company": {
    "cik": "0000320193",
    "ticker": "AAPL",
    "name": "Apple Inc."
  },
  "data": [
    {
      "filing_period": "TTM",
      "period_end": "2026-03-28",
      "revenue": 451442000000,
      "net_income": 122575000000,
      "total_assets": 371082000000,
      "free_cash_flow": 129174000000
    }
  ]
}

Try with your API key

cURL

curl "https://fundamentalshub.com/api/v2/companies/AAPL/financials?period=ttm&fields=all" \
  -H "X-API-Key: your_api_key"

Python

import requests

headers = {"X-API-Key": "your_api_key"}
url = "https://fundamentalshub.com/api/v2/companies/AAPL/financials"
params = {"period": "ttm", "fields": "all"}

response = requests.get(url, headers=headers, params=params, timeout=20)
print(response.json())

⚑ Rate Limits

Shown below are the Free tier limits.

Window Limit
Per Minute 5
Per Hour 20
Per Day 100
Per 30 Days (rolling) 300

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

πŸ“š Endpoints

GET /companies/search

Search for companies by name or ticker symbol.

Parameters

Name Type Required Description
q string Yes Search query (company name or ticker, min 1 character)
limit integer No Results per page (default: 50, max: 100)
offset integer No Number of results to skip (default: 0)

Example Request

curl -X GET "https://fundamentalshub.com/api/v2/companies/search?q=apple&limit=10" \
     -H "X-API-Key: your_api_key"

Example Response

{
  "success": true,
  "data": [
    {
      "cik": "0000320193",
      "name": "Apple Inc.",
      "ticker": "AAPL",
      "sic_code": "3571",
      "industry": "ELECTRONIC COMPUTERS"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}
GET /companies/{identifier}/financials

Get financial data for a company. Identifier can be CIK (with or without leading zeros) or ticker symbol.

Path Parameters

Name Type Description
identifier string Company CIK or ticker symbol (e.g., "320193", "0000320193", or "AAPL")

Query Parameters

Name Type Required Description
fields string No Field set to return:
  • all - All fields (default)
  • income, is, or income_statement - Income statement fields
  • balance, bs, or balance_sheet - Balance sheet fields
  • cashflow, cfs, or cash_flow - Cash flow statement fields
period string No Period type:
  • ttm - Trailing twelve months only (default)
  • annual - Annual (10-K) filings
  • quarterly - Quarterly (10-Q) filings
  • all - All available periods
limit integer No Maximum number of periods (default: 1 for TTM, 12 for annual/quarterly; max: 100)

Available Financial Fields

Income Statement (IS)

Revenue:

  • revenue
  • cost_of_revenue - COGS
  • gross_profit

Operating Expenses:

  • research_and_development - R&D
  • selling_general_admin - SG&A
  • other_operating_expenses - (plug)
  • operating_income

Non-Operating:

  • interest_expense
  • interest_income
  • other_income_expense
  • pretax_income
  • income_tax
  • net_income

Per Share & Supplemental:

  • diluted_eps
  • diluted_shares
  • ebitda - (derived)
  • depreciation_amortization - D&A
Balance Sheet (BS)

Assets:

  • cash_and_equivalents
  • short_term_investments
  • accounts_receivable
  • inventory
  • other_current_assets
  • current_assets
  • property_plant_equipment - PP&E
  • goodwill
  • intangible_assets
  • other_noncurrent_assets
  • noncurrent_assets
  • total_assets

Liabilities:

  • accounts_payable
  • short_term_debt
  • other_current_liabilities - (plug)
  • current_liabilities
  • long_term_debt
  • other_noncurrent_liabilities - (plug)
  • noncurrent_liabilities
  • total_liabilities

Equity:

  • common_stock
  • additional_paid_in_capital
  • retained_earnings
  • accumulated_other_comprehensive_income
  • total_equity
  • redeemable_noncontrolling_interest
  • liabilities_and_equity - L+E total

Supplemental:

  • total_debt - (derived)
  • shares_outstanding
Cash Flow (CFS)
  • cfo - Operating cash flow
  • capex - Capital expenditures
  • cfi - Investing cash flow
  • cff - Financing cash flow
  • fx_effect - FX impact on cash
  • free_cash_flow - (derived)
Supplemental (DEI)
  • public_float - Entity public float (from DEI filings)
Plug fields: Fields marked "(plug)" are computed as the difference between a subtotal and its itemized components. For example, other_operating_expenses = gross_profit − R&D − SGA − operating_income. They capture all unitemized line items within a section.
Legacy fields: Using ?fields=all also returns legacy fields not in the default structured output: operating_expenses, accrued_liabilities, deferred_revenue, cash_cfs.

Example Request

curl -X GET "https://fundamentalshub.com/api/v2/companies/AAPL/financials?fields=income&period=annual&limit=1" \
     -H "X-API-Key: your_api_key"

Example Response

{
  "success": true,
  "company": {
    "cik": "0000320193",
    "name": "Apple Inc.",
    "ticker": "AAPL",
    "sic_code": "3571",
    "industry": "Electronic Computers",
    "filer_category": null,
    "entity_type": "operating",
    "state_of_incorporation": null,
    "fiscal_year_end": null
  },
  "data": [
    {
      "filing_period": "FY2025",
      "period_end": "2025-09-27",
      "public_float": null,
      "revenue": 416161000000,
      "cost_of_revenue": 220960000000,
      "gross_profit": 195201000000,
      "research_and_development": 34550000000,
      "selling_general_admin": 27601000000,
      "other_operating_expenses": 0,
      "operating_income": 133050000000,
      "interest_expense": null,
      "interest_income": null,
      "other_income_expense": -321000000,
      "pretax_income": 132729000000,
      "income_tax": 20719000000,
      "net_income": 112010000000,
      "diluted_eps": 7.46,
      "diluted_shares": 15004697000,
      "ebitda": 144748000000,
      "depreciation_amortization": 11698000000
    }
  ],
  "periods_returned": 1
}
GET /industries/search

Search for SIC industry codes by name or code.

Parameters

Name Type Required Description
q string Yes Search query (industry name or SIC code, min 1 character)
limit integer No Results per page (default: 50, max: 100)
offset integer No Number of results to skip (default: 0)

Example Request

curl -X GET "https://fundamentalshub.com/api/v2/industries/search?q=software" \
     -H "X-API-Key: your_api_key"

Example Response

{
  "success": true,
  "data": [
    {
      "sic_code": "7371",
      "industry": "SERVICES-COMPUTER PROGRAMMING SERVICES",
      "company_count": 245
    },
    {
      "sic_code": "7372",
      "industry": "SERVICES-PREPACKAGED SOFTWARE",
      "company_count": 523
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2,
    "has_more": false
  }
}
GET /industries/{sic}/companies

List all companies in a specific SIC industry code.

Path Parameters

Name Type Description
sic string 4-digit SIC code (e.g., "7372")

Query Parameters

Name Type Required Description
limit integer No Results per page (default: 50, max: 100)
offset integer No Number of results to skip (default: 0)

Example Request

curl -X GET "https://fundamentalshub.com/api/v2/industries/7372/companies?limit=10" \
     -H "X-API-Key: your_api_key"

Example Response

{
  "success": true,
  "industry": {
    "sic_code": "7372",
    "name": "SERVICES-PREPACKAGED SOFTWARE"
  },
  "data": [
    {
      "cik": "0000789019",
      "name": "MICROSOFT CORP",
      "ticker": "MSFT"
    },
    {
      "cik": "0001018724",
      "name": "AMAZON COM INC",
      "ticker": "AMZN"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 523,
    "has_more": true
  }
}

⚠️ Error Handling

All errors return JSON with "success": false. Validation errors (400) and not-found errors (404) use: 

{"success": false, "error": "description"}

Authentication (401), rate limit (429), and server (500) errors also include a message field: 

{"success": false, "error": "category", "message": "details"}

HTTP Status Codes

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid API key
404 Not Found - Resource doesn't exist
429 Rate Limit Exceeded - Too many requests
500 Server Error - Something went wrong

πŸ’» Code Examples

Python

import requests

API_KEY = "your_api_key"
BASE_URL = "https://fundamentalshub.com/api/v2"

headers = {"X-API-Key": API_KEY}

# Search for a company
response = requests.get(
    f"{BASE_URL}/companies/search",
    params={"q": "apple"},
    headers=headers
)
companies = response.json()

# Get company financials
response = requests.get(
    f"{BASE_URL}/companies/AAPL/financials",
    params={"fields": "income", "period": "annual", "limit": 5},
    headers=headers
)
financials = response.json()

JavaScript (Node.js)

const API_KEY = "your_api_key";
const BASE_URL = "https://fundamentalshub.com/api/v2";

async function searchCompanies(query) {
    const response = await fetch(
        `${BASE_URL}/companies/search?q=${encodeURIComponent(query)}`,
        { headers: { "X-API-Key": API_KEY } }
    );
    return response.json();
}

async function getFinancials(ticker) {
    const response = await fetch(
        `${BASE_URL}/companies/${ticker}/financials?fields=all&period=ttm`,
        { headers: { "X-API-Key": API_KEY } }
    );
    return response.json();
}

// Usage
const companies = await searchCompanies("apple");
const financials = await getFinancials("AAPL");

PHP

<?php
$apiKey = "your_api_key";
$baseUrl = "https://fundamentalshub.com/api/v2";

function apiRequest($endpoint, $params = []) {
    global $apiKey, $baseUrl;
    
    $url = $baseUrl . $endpoint;
    if ($params) {
        $url .= '?' . http_build_query($params);
    }
    
    $opts = [
        'http' => [
            'header' => "X-API-Key: $apiKey\r\n"
        ]
    ];
    $context = stream_context_create($opts);
    $response = file_get_contents($url, false, $context);
    return json_decode($response, true);
}

// Search for companies
$companies = apiRequest('/companies/search', ['q' => 'apple']);

// Get financials
$financials = apiRequest('/companies/AAPL/financials', [
    'fields' => 'income',
    'period' => 'annual',
    'limit' => 5
]);