The company facts endpoint is a free SEC EDGAR API endpoint that returns structured financial facts for one company in a single JSON response. It can provide historical revenue, assets, liabilities, cash flow, earnings, shares, and other XBRL-tagged values reported in SEC filings.
Analysts and developers use the endpoint to build financial models, research tools, dashboards, screening systems, and data pipelines. It does not require an API key, but automated requests must follow the SEC’s access rules.
In this blog, you’ll learn how the Company Facts endpoint works, what data it returns, how the JSON response is structured, and what to check before using the values in financial analysis.
What is the Company Facts Endpoint
The Company Facts endpoint is part of the U.S. Securities and Exchange Commission’s EDGAR data APIs. It gathers qualifying XBRL facts reported by a specific filer across its SEC submissions.
XBRL stands for eXtensible Business Reporting Language. It adds structured tags to financial data so software can identify a value, its meaning, its unit, its reporting period, and its source filing.
The endpoint follows this URL format:
https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json
Replace "##########" with the company’s 10-digit Central Index Key, or CIK. You must add leading zeros when the original CIK contains fewer than 10 digits.
For example, Apple’s CIK is 320193. Its correctly formatted Company Facts URL is:
https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json
The SEC states that its data APIs provide JSON-formatted information and do not require authentication or API keys. The Company Facts API returns all available company-concept data for one filer through a single request.
What Does the Company Facts Endpoint Return?
The endpoint returns qualifying XBRL facts extracted from a company’s SEC filings. These facts may come from forms such as:
- Amendments and related form variants
The SEC updates its XBRL APIs as filings are disseminated. The typical processing delay is under one minute, although updates may take longer during peak filing periods.
A Company Facts response can contain concepts such as:
- - Cash and cash equivalents
The available concepts depend on what the company reported. They may also vary based on the company’s industry, accounting framework, financial statement presentation, and choice of XBRL tags.
How the Company Facts Endpoint Works
The endpoint starts with the company’s CIK. It then gathers the qualifying structured facts associated with that filer.
The basic process looks like this:
- 1. Find the company’s CIK.
- 2. Pad the CIK to 10 digits.
- 3. Add it to the endpoint URL.
- 4. Send an HTTP GET request.
- 5. Read the returned JSON file.
- 6. Find the required taxonomy and concept.
- 7. Filter the facts by unit, period, form, and filing date.
The SEC publishes a "company_tickers.json" file that maps company names and ticker symbols to CIKs. Those CIK values may appear without leading zeros, so they must be reformatted before use.
The response normally groups facts under taxonomies such as "us-gaap", "ifrs-full", "dei", or "srt". U.S. companies commonly report financial statement concepts under "us-gaap", while some foreign private issuers use "ifrs-full".
The SEC’s XBRL APIs generally aggregate facts that use a non-custom taxonomy and apply to the entire filing entity. This helps keep the concepts more consistent across companies and reporting periods.
How is the Company Facts JSON Response Structured?
A complete Company Facts response can be large and deeply nested. At the top level, it identifies the filer and then groups its facts by taxonomy and concept.
Inside the response, one financial fact may look like this:
{
"start": "2023-07-01",
"end": "2023-09-30",
"val": 89498000000,
"accn": "0000320193-23-000106",
"fy": 2023,
"fp": "FY",
"form": "10-K",
"filed": "2023-11-03"
}
This is a simplified example created to show the structure. And each field tells you something specific:
| Field |
What It Means |
| val |
The raw reported value, not in thousands or millions |
| start / end |
The reporting period the value covers |
| fy / fp |
Fiscal year and fiscal period, such as Q1, Q2, Q3, or FY |
| form |
The filing type the data came from, such as 10-K or 10-Q |
| accn |
The accession number, a unique ID for the specific filing |
| filed |
The date the filing was submitted |
Why Do Duplicate Values Appear
A Company Facts response can contain the same financial value more than once. This is normal and does not always indicate an error.
A 10-K often repeats figures from earlier periods for comparison. A later filing may also repeat, amend, or restate a previously reported value.
Repeated records may have:
- - The same value but different accession numbers
- - The same end date but different start dates
- - Different reporting contexts
- - Original and restated values
Do not remove a record only because the number appears more than once. Check the period, filing type, filing date, and accession number before deciding which value to use.
This is especially important for quarterly data. A three-month figure and a year-to-date figure may share the same end date but cover different reporting periods.
Company Facts vs Company Concept vs Frames
SEC EDGAR actually offers three related XBRL endpoints. Picking the right one saves you from downloading data you don't need.
| Endpoint |
Returns |
Best For |
| Company Facts |
Every tag for one company |
Full financial profile of a single company |
| Company Concept |
One tag for one company |
Tracking a single metric, such as revenue, over time |
| Frames |
One tag across many companies |
Comparing the same metric across an entire industry |
Use Company Facts when you need several financial metrics for one company.
Use Company Concept when you already know the exact taxonomy and tag. It provides a smaller response for one selected metric.
Use Frames when you want to compare one concept across several reporting entities for a specific calendar period.
Requirements Before You Can Access the Data
The endpoint is free and doesn't require an API key. But it does have a few rules and skipping them is the main reason first-time requests fail.
User-Agent header is mandatory:
Every request needs a header identifying who's making it, typically a name or company and a contact email. If you miss this, you'll get a 403 Forbidden error. To fix it, add a header like "YourCompany yourname@email.com” to every request.
Rate limit is 10 requests per second per IP:
Exceed it and you'll hit a 429 Too Many Requests error, or in some cases a dropped connection. To fix it, add a short delay, around 100 to 120 milliseconds, between calls when pulling data for multiple companies.
No authentication or sign-up needed:
Unlike most commercial financial data APIs, this one is open to anyone.
Data has a historical floor:
XBRL tagging became mandatory for large accelerated filers in 2009 and extended to all filers by 2011. Filings before that period aren't available through this endpoint.
Common Uses of Company Facts Data
The Company Facts endpoint is commonly used for:
- - Financial modeling: Collect revenue, earnings, assets, liabilities, equity, and cash flow data for valuation or credit models.
- - Historical trend analysis: Track revenue growth, margins, debt, spending, earnings, and share count over time.
- - Financial dashboards: Display company metrics in charts, profiles, and internal reporting tools.
- - Stock screening: Filter companies using measures such as revenue growth, net income, assets, or operating cash flow.
- - Fintech applications: Add structured SEC financial data to research platforms, investor tools, and financial products.
- - Peer comparison: Compare similar financial concepts across companies in the same industry.
- - Filing verification: Use accession numbers and filing dates to trace a value back to its SEC submission.
- - Data pipelines: Collect and store reported financial facts for analysis, monitoring, or database updates.
The data still needs validation before use. Check the XBRL concept, unit, reporting period, filing type, and accession number.
Limitations of the Company Facts Endpoint
The Company Facts endpoint provides useful raw data, but it is not a complete financial database.
Financial Concepts Need Normalization
Two companies may report similar financial information under different XBRL concepts. A company may also change the concept it uses over time.
Larger datasets need mapping rules to create consistent financial histories and peer comparisons.
Some Facts May Be Missing
The endpoint mainly includes supported non-custom taxonomy facts that apply to the full filing entity.
Some company-specific, custom, or segment-level facts may not appear in the response.
Reporting Periods Need Careful Review
The 'fy' and 'fp' fields do not always describe the exact duration of an individual value.
Check the start and end dates before separating quarterly, annual, and year-to-date figures.
Narrative context is Not Included
The endpoint shows what a company reported, but it does not explain why a number changed.
Analysts still need the original 10-K or 10-Q for footnotes, risk factors, segment details, and management commentary.
Company Facts Endpoint or Standardized Financial Data?
Direct SEC data may work well when you cover a limited number of U.S. companies and have the resources to process XBRL data.
It may be less suitable when you need:
- - Standardized financial statements
- - One consistent schema across many companies
- - Full filing text and financial facts together
- - Production-ready data without maintaining XBRL mappings
Bottom Line
The SEC Company Facts endpoint provides qualifying XBRL financial facts for one company in a single JSON response. It is free, requires no API key, and works well for financial research, modeling, dashboards, and filing verification.
However, the response contains raw filing data. Users still need to check concepts, units, periods, duplicates, and source filings before using the values in analysis or production systems.
Quantillium offers an all in one API for corporate filings across global markets. With a reliable SEC Filings API, you can access standardized SEC data, extract full documents, track historical coverage, and daily updates from 60 stock exchanges. Explore the API docs, or start a free trial.
Frequently Asked Questions
Does the Company Facts endpoint require an API key?
No. The SEC’s public data.sec.gov APIs do not require an API key, authentication, or account registration.
How should a CIK be formatted?
The CIK must contain 10 digits, including leading zeros. Apple’s CIK becomes CIK0000320193 in the endpoint URL.
What financial data does the endpoint provide?
It may include revenue, assets, liabilities, net income, cash flow, equity, shares, and earnings per share. The exact concepts depend on what the company reports using supported XBRL taxonomies.
Why does the endpoint contain duplicate values?
Later filings often repeat values from previous periods. Amendments, restatements, comparative statements, and different reporting durations can also create records that look like duplicates.
Can I compare companies with the Company Facts endpoint?
Yes, but the data usually needs normalization first. Companies may use different concepts, fiscal calendars, accounting policies, units, and reporting structures.
How quickly does the SEC update the endpoint?
The SEC updates its XBRL APIs as filings are disseminated. The typical delay is under one minute, although processing may take longer during peak filing periods.
The company facts endpoint is a free SEC EDGAR API endpoint that returns structured financial facts for one company in a single JSON response. It can provide historical revenue, assets, liabilities, cash flow, earnings, shares, and other XBRL-tagged values reported in SEC filings.
Analysts and developers use the endpoint to build financial models, research tools, dashboards, screening systems, and data pipelines. It does not require an API key, but automated requests must follow the SEC’s access rules.
In this blog, you’ll learn how the Company Facts endpoint works, what data it returns, how the JSON response is structured, and what to check before using the values in financial analysis.
What is the Company Facts Endpoint
The Company Facts endpoint is part of the U.S. Securities and Exchange Commission’s EDGAR data APIs. It gathers qualifying XBRL facts reported by a specific filer across its SEC submissions.
XBRL stands for eXtensible Business Reporting Language. It adds structured tags to financial data so software can identify a value, its meaning, its unit, its reporting period, and its source filing.
The endpoint follows this URL format:
https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json
Replace "##########" with the company’s 10-digit Central Index Key, or CIK. You must add leading zeros when the original CIK contains fewer than 10 digits.
For example, Apple’s CIK is 320193. Its correctly formatted Company Facts URL is:
https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json
The SEC states that its data APIs provide JSON-formatted information and do not require authentication or API keys. The Company Facts API returns all available company-concept data for one filer through a single request.
What Does the Company Facts Endpoint Return?
The endpoint returns qualifying XBRL facts extracted from a company’s SEC filings. These facts may come from forms such as:
- Amendments and related form variants
The SEC updates its XBRL APIs as filings are disseminated. The typical processing delay is under one minute, although updates may take longer during peak filing periods.
A Company Facts response can contain concepts such as:
- - Cash and cash equivalents
The available concepts depend on what the company reported. They may also vary based on the company’s industry, accounting framework, financial statement presentation, and choice of XBRL tags.
How the Company Facts Endpoint Works
The endpoint starts with the company’s CIK. It then gathers the qualifying structured facts associated with that filer.
The basic process looks like this:
- 1. Find the company’s CIK.
- 2. Pad the CIK to 10 digits.
- 3. Add it to the endpoint URL.
- 4. Send an HTTP GET request.
- 5. Read the returned JSON file.
- 6. Find the required taxonomy and concept.
- 7. Filter the facts by unit, period, form, and filing date.
The SEC publishes a "company_tickers.json" file that maps company names and ticker symbols to CIKs. Those CIK values may appear without leading zeros, so they must be reformatted before use.
The response normally groups facts under taxonomies such as "us-gaap", "ifrs-full", "dei", or "srt". U.S. companies commonly report financial statement concepts under "us-gaap", while some foreign private issuers use "ifrs-full".
The SEC’s XBRL APIs generally aggregate facts that use a non-custom taxonomy and apply to the entire filing entity. This helps keep the concepts more consistent across companies and reporting periods.
How is the Company Facts JSON Response Structured?
A complete Company Facts response can be large and deeply nested. At the top level, it identifies the filer and then groups its facts by taxonomy and concept.
Inside the response, one financial fact may look like this:
{
"start": "2023-07-01",
"end": "2023-09-30",
"val": 89498000000,
"accn": "0000320193-23-000106",
"fy": 2023,
"fp": "FY",
"form": "10-K",
"filed": "2023-11-03"
}
This is a simplified example created to show the structure. And each field tells you something specific:
| Field |
What It Means |
| val |
The raw reported value, not in thousands or millions |
| start / end |
The reporting period the value covers |
| fy / fp |
Fiscal year and fiscal period, such as Q1, Q2, Q3, or FY |
| form |
The filing type the data came from, such as 10-K or 10-Q |
| accn |
The accession number, a unique ID for the specific filing |
| filed |
The date the filing was submitted |
Why Do Duplicate Values Appear
A Company Facts response can contain the same financial value more than once. This is normal and does not always indicate an error.
A 10-K often repeats figures from earlier periods for comparison. A later filing may also repeat, amend, or restate a previously reported value.
Repeated records may have:
- - The same value but different accession numbers
- - The same end date but different start dates
- - Different reporting contexts
- - Original and restated values
Do not remove a record only because the number appears more than once. Check the period, filing type, filing date, and accession number before deciding which value to use.
This is especially important for quarterly data. A three-month figure and a year-to-date figure may share the same end date but cover different reporting periods.
Company Facts vs Company Concept vs Frames
SEC EDGAR actually offers three related XBRL endpoints. Picking the right one saves you from downloading data you don't need.
| Endpoint |
Returns |
Best For |
| Company Facts |
Every tag for one company |
Full financial profile of a single company |
| Company Concept |
One tag for one company |
Tracking a single metric, such as revenue, over time |
| Frames |
One tag across many companies |
Comparing the same metric across an entire industry |
Use Company Facts when you need several financial metrics for one company.
Use Company Concept when you already know the exact taxonomy and tag. It provides a smaller response for one selected metric.
Use Frames when you want to compare one concept across several reporting entities for a specific calendar period.
Requirements Before You Can Access the Data
The endpoint is free and doesn't require an API key. But it does have a few rules and skipping them is the main reason first-time requests fail.
User-Agent header is mandatory:
Every request needs a header identifying who's making it, typically a name or company and a contact email. If you miss this, you'll get a 403 Forbidden error. To fix it, add a header like "YourCompany yourname@email.com” to every request.
Rate limit is 10 requests per second per IP:
Exceed it and you'll hit a 429 Too Many Requests error, or in some cases a dropped connection. To fix it, add a short delay, around 100 to 120 milliseconds, between calls when pulling data for multiple companies.
No authentication or sign-up needed:
Unlike most commercial financial data APIs, this one is open to anyone.
Data has a historical floor:
XBRL tagging became mandatory for large accelerated filers in 2009 and extended to all filers by 2011. Filings before that period aren't available through this endpoint.
Common Uses of Company Facts Data
The Company Facts endpoint is commonly used for:
- - Financial modeling: Collect revenue, earnings, assets, liabilities, equity, and cash flow data for valuation or credit models.
- - Historical trend analysis: Track revenue growth, margins, debt, spending, earnings, and share count over time.
- - Financial dashboards: Display company metrics in charts, profiles, and internal reporting tools.
- - Stock screening: Filter companies using measures such as revenue growth, net income, assets, or operating cash flow.
- - Fintech applications: Add structured SEC financial data to research platforms, investor tools, and financial products.
- - Peer comparison: Compare similar financial concepts across companies in the same industry.
- - Filing verification: Use accession numbers and filing dates to trace a value back to its SEC submission.
- - Data pipelines: Collect and store reported financial facts for analysis, monitoring, or database updates.
The data still needs validation before use. Check the XBRL concept, unit, reporting period, filing type, and accession number.
Limitations of the Company Facts Endpoint
The Company Facts endpoint provides useful raw data, but it is not a complete financial database.
Financial Concepts Need Normalization
Two companies may report similar financial information under different XBRL concepts. A company may also change the concept it uses over time.
Larger datasets need mapping rules to create consistent financial histories and peer comparisons.
Some Facts May Be Missing
The endpoint mainly includes supported non-custom taxonomy facts that apply to the full filing entity.
Some company-specific, custom, or segment-level facts may not appear in the response.
Reporting Periods Need Careful Review
The 'fy' and 'fp' fields do not always describe the exact duration of an individual value.
Check the start and end dates before separating quarterly, annual, and year-to-date figures.
Narrative context is Not Included
The endpoint shows what a company reported, but it does not explain why a number changed.
Analysts still need the original 10-K or 10-Q for footnotes, risk factors, segment details, and management commentary.
Company Facts Endpoint or Standardized Financial Data?
Direct SEC data may work well when you cover a limited number of U.S. companies and have the resources to process XBRL data.
It may be less suitable when you need:
- - Standardized financial statements
- - One consistent schema across many companies
- - Full filing text and financial facts together
- - Production-ready data without maintaining XBRL mappings
Bottom Line
The SEC Company Facts endpoint provides qualifying XBRL financial facts for one company in a single JSON response. It is free, requires no API key, and works well for financial research, modeling, dashboards, and filing verification.
However, the response contains raw filing data. Users still need to check concepts, units, periods, duplicates, and source filings before using the values in analysis or production systems.
Quantillium offers an all in one API for corporate filings across global markets. With a reliable SEC Filings API, you can access standardized SEC data, extract full documents, track historical coverage, and daily updates from 60 stock exchanges. Explore the API docs, or start a free trial.
Frequently Asked Questions
Does the Company Facts endpoint require an API key?
No. The SEC’s public data.sec.gov APIs do not require an API key, authentication, or account registration.
How should a CIK be formatted?
The CIK must contain 10 digits, including leading zeros. Apple’s CIK becomes CIK0000320193 in the endpoint URL.
What financial data does the endpoint provide?
It may include revenue, assets, liabilities, net income, cash flow, equity, shares, and earnings per share. The exact concepts depend on what the company reports using supported XBRL taxonomies.
Why does the endpoint contain duplicate values?
Later filings often repeat values from previous periods. Amendments, restatements, comparative statements, and different reporting durations can also create records that look like duplicates.
Can I compare companies with the Company Facts endpoint?
Yes, but the data usually needs normalization first. Companies may use different concepts, fiscal calendars, accounting policies, units, and reporting structures.
How quickly does the SEC update the endpoint?
The SEC updates its XBRL APIs as filings are disseminated. The typical delay is under one minute, although processing may take longer during peak filing periods.
.webp)
.webp)
.webp)
