The filings in filings.xbrl.org can be accessed via a public API.
The API follows the JSON API standard. The API is accessible at https://filings.xbrl.org/api.
The API provides the following resources:
https://filings.xbrl.org/api/filingshttps://filings.xbrl.org/api/entitieshttps://filings.xbrl.org/api/validation_messagesThe information from the filing resource is also available as a set of static index files. These are the preferred way to download a list of all filings.
Results are paginated. Links to other pages within the results are included in the links object within the response. Pagination can be controlled with query parameters:
page[size]=200 — specify the page sizepage[number]=2 — retrieve a specific page
It is often useful to include entity information when retrieving filings. This can be done by specifying a query parameter of ?include=entity.
Results can be filtered on attributes of the resource. For example, https://filings.xbrl.org/api/filings?filter[country]=GB will retrieve filings with a country of GB.
More complex filters can be constructed by passing a JSON list of filter expressions in the filter query parameter. Each expression has a name, an op and a val, for example:
filter=[{"name":"country","op":"eq","val":"GB"},{"name":"period_end","op":"ge","val":"2023-01-01"}]
All expressions in the list must match. Expressions can be combined using {"or": [...]}, {"and": [...]} and {"not": {...}}. Attributes of related resources can be filtered on using a dotted name, such as entity.name. The supported operators are eq, ne, lt, le, gt, ge, like, ilike, notlike, notilike, in, notin, is, isnot, startswith, endswith and contains.
Results can be sorted by specifying a sort query parameter.
If you are looking to obtain the most recent filings, specify a parameter of ?sort=-processed.
The published attribute of a filing is the date on which it was published by the filing source, where this is available from the source, and null otherwise. It can be used in filters and sorts, for example filter=[{"name":"published","op":"ge","val":"2024-01-01"}].
If you need details of all filings, for example to keep a local copy of the index up to date, please download the index files instead of retrieving every page of results from the API.
There is one index file per year, containing all filings with a period end date in that calendar year:
https://filings.xbrl.org/indexes/filings-{YEAR}.json
For example, https://filings.xbrl.org/indexes/filings-2024.json contains filings with a period end of 2024-01-01 to 2024-12-31 inclusive. If there are no filings for a year, there is no file and the request returns a 404.
Each file is a JSON API document in the same format as /api/filings?include=entity, containing all filings for the year in a single document, with the related entities in included. There are no pagination links, and meta.count gives the number of filings in the file.
The index files are updated whenever new filings are processed, and the Last-Modified header accurately reflects when a file was last changed.
To avoid downloading files that have not changed, please make conditional requests: store the Last-Modified header from each response, and send it back as an If-Modified-Since header on the next request. If the file has not changed, the response will be 304 Not Modified, with no content.
New filings will generally only be added to the current year and previous year, but we will occasionally fill in gaps in the index for older filings, or re-process existing filings for earlier years.
Access to the API is provided free of charge, but we reserve the right to alter the API at any time, including applying rate limits or withdrawing it completely.
If you are routinely using the API, please set a user agent that includes a contact email address, or a link to where we can find your contact details.
If you are making regular use of the API, it is strongly recommended to join the mailing list.