Complete Guide to Data.sec.gov API XBRL CompanyFacts Documentation

Published April 8, 2026 · 7 min read

Complete Guide to Data.sec.gov API XBRL CompanyFacts Documentation

Introduction to the SEC's Data.sec.gov API XBRL CompanyFacts

The Securities and Exchange Commission's data.sec.gov API has revolutionized how developers and analysts access financial data. Among its most powerful features is the XBRL CompanyFacts endpoint, which provides structured financial information extracted from companies' XBRL filings. This comprehensive documentation will guide you through everything you need to know about leveraging this essential API endpoint.

The data.sec.gov api xbrl companyfacts documentation reveals a treasure trove of standardized financial data that can transform your financial analysis workflows. Whether you're building investment tools, conducting research, or creating compliance applications, understanding this API is crucial for accessing high-quality SEC data programmatically.

Understanding XBRL and CompanyFacts Structure

What is XBRL?

XBRL (eXtensible Business Reporting Language) is a standardized format that companies use to report financial information to the SEC. This XML-based language creates machine-readable financial statements, making data extraction and analysis significantly more efficient than traditional text-based filings.

The CompanyFacts endpoint aggregates this XBRL data into a structured JSON format, organizing financial metrics by taxonomy, units, and reporting periods. This standardization eliminates much of the manual work typically required to extract and normalize financial data from SEC filings.

CompanyFacts Data Structure

When you query the CompanyFacts endpoint, the response includes several key components:

API Endpoint Structure and Authentication

Base URL and Endpoint Format

The CompanyFacts endpoint follows this structure:

https://data.sec.gov/api/xbrl/companyfacts/CIK{CIK-number}.json

Where {CIK-number} is the 10-digit Central Index Key assigned to each company by the SEC. For example, Apple Inc.'s CIK is 0000320193, so the endpoint would be:

https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json

Authentication and Rate Limiting

The SEC requires all API requests to include a User-Agent header that identifies your application and provides contact information. Requests without proper User-Agent headers will be rejected. The format should be:

User-Agent: YourCompany YourApp/1.0 ([email protected])

The API implements rate limiting of 10 requests per second. Exceeding this limit will result in HTTP 429 responses. Implement proper retry logic with exponential backoff to handle rate limiting gracefully.

Request Parameters and Options

Required Parameters

The CompanyFacts endpoint requires only one parameter:

Note that CIKs must be padded with leading zeros to reach 10 digits. For instance, if a company's CIK is 1234, you must format it as 0000001234 in the URL.

Optional Query Parameters

While the base endpoint returns all available data, you can optimize your requests by understanding the data structure and implementing client-side filtering. The API doesn't currently support server-side filtering parameters, so all data processing must occur after receiving the response.

Response Format and Data Interpretation

JSON Response Structure

The API returns a comprehensive JSON object containing the company's complete XBRL fact set. The response structure includes:

Within the facts object, data is organized by taxonomy namespaces such as:

Understanding Fact Values

Each fact contains multiple data points across different time periods and units. Key attributes include:

Implementation Examples and Best Practices

Python Implementation Example

Here's a robust Python example for accessing CompanyFacts data:

import requests
import json
import time
from typing import Dict, Any

class SECCompanyFacts:
    def __init__(self, user_agent: str):
        self.base_url = "https://data.sec.gov/api/xbrl/companyfacts/"
        self.headers = {
            "User-Agent": user_agent,
            "Accept-Encoding": "gzip, deflate",
            "Host": "data.sec.gov"
        }
        self.rate_limit_delay = 0.1  # 10 requests per second
    
    def get_company_facts(self, cik: str) -> Dict[str, Any]:
        # Ensure CIK is properly formatted
        formatted_cik = f"CIK{cik.zfill(10)}.json"
        url = f"{self.base_url}{formatted_cik}"
        
        try:
            response = requests.get(url, headers=self.headers)
            response.raise_for_status()
            
            # Respect rate limiting
            time.sleep(self.rate_limit_delay)
            
            return response.json()
            
        except requests.exceptions.RequestException as e:
            print(f"Error fetching data for CIK {cik}: {e}")
            return {}

Error Handling Strategies

Implement comprehensive error handling for common scenarios:

Always implement retry logic with exponential backoff for temporary failures, and cache successful responses to minimize API calls.

Data Processing and Analysis Techniques

Filtering and Aggregating Data

The CompanyFacts response can be extensive, often containing thousands of data points. Implement efficient filtering strategies to extract relevant information:

Handling Data Quality Issues

XBRL data can contain inconsistencies and reporting variations. Address these challenges by:

Common Use Cases and Applications

Financial Analysis Applications

The CompanyFacts API enables numerous financial analysis scenarios:

Integration with Financial Platforms

Many developers integrate CompanyFacts data into larger financial platforms:

Performance Optimization and Caching

Caching Strategies

Given the rate limiting and the relatively static nature of historical financial data, implement robust caching:

Batch Processing Considerations

When processing multiple companies, optimize your approach:

Troubleshooting Common Issues

Data Availability Problems

Not all companies provide XBRL data through the CompanyFacts endpoint. Common scenarios include:

Technical Implementation Issues

Address common technical challenges:

Future Developments and API Evolution

The SEC continues to enhance the data.sec.gov API based on user feedback and technological improvements. Stay informed about:

Monitor the SEC's developer resources and consider joining developer communities focused on financial data to stay current with best practices and new features.

Conclusion

The data.sec.gov api xbrl companyfacts documentation provides developers with unprecedented access to standardized financial data. By understanding the API's structure, implementing proper error handling, and following best practices for data processing, you can build robust applications that leverage this valuable resource.

Remember to always respect the API's rate limits, implement appropriate caching strategies, and handle data quality issues proactively. With these foundations in place, the CompanyFacts API becomes a powerful tool for financial analysis, research, and application development.

Frequently Asked Questions

How do I find a company's CIK number for the CompanyFacts API?

You can find a company's CIK (Central Index Key) through the SEC's EDGAR database at sec.gov/edgar, by using the company search endpoint at data.sec.gov/api/xbrl/companyconcept, or through various financial data providers. The CIK is a unique 10-digit identifier that must be zero-padded when used in API requests.

What should I do if the CompanyFacts API returns a 404 error?

A 404 error typically means either the CIK is invalid/incorrectly formatted, or the company doesn't have XBRL data available. Verify the CIK is correct and zero-padded to 10 digits. Some smaller companies or recent filers may not have XBRL data available through this endpoint.

How often is the CompanyFacts data updated?

The CompanyFacts data is updated as companies file new reports with the SEC. Quarterly reports (10-Q) are typically filed within 40-45 days after quarter-end, while annual reports (10-K) are filed within 60-90 days after fiscal year-end. The API reflects these updates shortly after the SEC processes the filings.