list_filings

Return the filing history for a company, newest first. Each filing has filing_id, filing_date, category (normalised across jurisdictions), description, and (where upstream exposes one) a document_id that round-trips to get_document_metadata / fetch_document. Filter by category to narrow.

Frequently asked questions

What categories are recognized?

accounts / annual-return / confirmation-statement / officers / persons-with-significant-control / charges / resolution / capital / incorporation / dissolution. The category field is normalized across jurisdictions. The registry's native form code stays under jurisdiction_data.form_type for round-tripping.

Do I get the document content or just metadata?

Just metadata + a document_id. To download, pipe document_id into fetch_document (or get_document_metadata first to check format / size). For annual accounts specifically, get_financials is the more ergonomic shortcut — same data, period-end-sorted.

Why is document_id missing on some filings?

Pre-electronic filings (paper) often have a filing record but no scanned PDF on the registry server. has_document tells you upfront whether a fetch is possible. Pre-2003 GB filings, pre-1997 IE filings, and most Eastern European pre-2010 filings frequently lack downloads.

How do I paginate beyond limit?

limit caps at 1000 per call. For larger histories, jurisdiction_data.next_cursor (where the registry exposes one) returns a token to pass on the next call. Some registries cap total history at 35 years — older filings simply not returned.

What's the date format?

filing_date is YYYY-MM-DD ISO. Always reflects the date the registry RECEIVED the filing, NOT the period the filing covers. For period-end (e.g. accounts cover FY2024 ending 2024-12-31), look inside the filing's payload via fetch_document or use get_financials which surfaces period_end as a top-level field.

Newest-first or oldest-first?

Newest first, always. To get oldest, fetch all and reverse client-side, or paginate to the last page (jurisdiction_data.total_count / your limit). Some registries return chronological order in their native API; we normalize.

I see two filings for the same period — accounts amended?

Yes — annual accounts can be filed, then re-filed (corrections, late amendments). Both records remain. description on the later filing usually contains 'AA', 'AMD', or similar amendment marker. Use the most recent for the canonical view; preserve the older ones for audit trail.

Charges filings vs get_charges?

list_filings(category='charges') gives the filing events (MR01, MR04 etc.). get_charges gives the structured charge register snapshot (active + satisfied charges with creator, secured party, amount). Use get_charges for current-state, list_filings for the event log.

Why does a country I want not work?

Currently supported: GB, IE, FI, CA, IS, PL, DE, NZ, NL, MC, ES, KR, MX, RU, IM, LI. Others return 501 + alternative_url. The list expands as we wire each registry's filing endpoint. Check list_jurisdictions({supports_tool: 'list_filings'}) for live coverage.

Can I filter by date range?

Not via parameters — list_filings doesn't accept date_from / date_to. Fetch newest-first with a high limit, then filter client-side. For very long histories where date filtering would matter most (GB Tesco, decades of filings), it's quicker to filter by category first.