Document description_values for Filings API call

The documentation here doesn’t provide much in the way of discussing the description_values field which seems to be returned as a result of this call.

This is clearly crucial for producing the content in the filings presentation section so it would be good to understand what we can expect there.

Looking at our notes - admittedly from several years ago - this was a bit of a muddle. I don’t know if the older data is now served in a more consistent way. We did try to cover all the bases to recreate something much like you see in the page though - you might be content to cover the main cases.

We did something like (starting with the most common case):

Check the description member. This should exist. Try looking it up in the list in the “enumeration constants” for the “filing history descriptions”:

That will give you a (markdown) template. Parse through this template looking for any values that need substituting. If there are any there then fill these in from the description_values member. (These themselves may need some parsing e.g. checking / formatting of dates etc).

From company SC046419 (you might want to re-check these examples as they were downloaded some time past):
The item:

	"type": "AA",
	"action_date": "1987-09-30",
	{ "made_up_date": "1987-09-30" },
	"description": "accounts-with-accounts-type-full",
	"category": "accounts",
	"date": "1988-01-21",
	"barcode": null,
    "transaction_id": "MDEzOTcxNjM1MGFkaXF6a2N4"	

Looking up the description gives the entry:

'accounts-with-accounts-type-full' : "**Full accounts** made up to {made_up_date}"

So we substitute description_values.made_up_date in here.

First exception: if the description is “legacy” (which doesn’t appear in the “enum constants”) or “miscellaneous” (which does but just has the template “Miscellaneous”) then there should be a description member in description_values. You could either just emit this as is or format it (e.g. add a template for “legacy” to the constants / roll your own miscellaneous").

Example (same company as above):

    "date": "1987-12-14",
    "category": "officers",
    "type": "288",
    { "description": "Director's particulars changed" },
    "description": "legacy",
    "barcode": null,
    "transaction_id": "MDA4NTk4NjkzNWFkaXF6a2N4"

And a “misc”:

    "type": "MISC",
		{ "description": "Certificate of incorporation" },
		"description": "miscellaneous",
		"date": "1969-03-18",
		"category": "miscellaneous",
			"document_metadata": "",
			"self": "/company/SC046419/filing-history/MDE4NTU1MDMwN2FkaXF6a2N4"	
		"pages": 2,
		"paper_filed": true,
		"barcode": null,
		"transaction_id": "MDE4NTU1MDMwN2FkaXF6a2N4"	

Second complication: your example (company 04591440) has the following entry:

Annual return made up to 15 November 2015 with full list of shareholders
Statement of capital on 2015-11-25

  • GBP 812.74

Here there’s an associated_filings member which acts like a mini filing history environment. Here’s the whole item:

    "links": {
        "self": "/company/04591440/filing-history/MzEzNTk4NDkzNmFkaXF6a2N4",
        "document_metadata": ""
    "description_values": {
        "made_up_date": "2015-11-15"
    "action_date": "2015-11-15",
    "description": "annual-return-company-with-made-up-date-full-list-shareholders",
    "type": "AR01",
    "category": "annual-return",
    "date": "2015-11-25",
    "associated_filings": [
            "action_date": 1448409600000,
            "category": "capital",
            "date": "2015-11-25",
            "description": "statement-of-capital",
            "description_values": {
                "capital": [
                        "currency": "GBP",
                        "figure": "812.74"
                "date": "2015-11-25"
            "type": "SH01"
    "pages": 4,
    "barcode": "X4KY7S95",
    "transaction_id": "MzEzNTk4NDkzNmFkaXF6a2N4"

For each of the associated_filings items you can use a similar process (e.g. look up “statement-of-capital” in enum constants to get the template etc.) - but you’ll find that the “capital” part isn’t provided for. (Looking at the constants you’ll see stuff which appears to be expecting a “capital” statement after it e.g.:

'capital-return-purchase-own-shares-capital-date' : "**Purchase of own shares.** Capital on {date}"
'capital-sale-or-transfer-treasury-shares-with-date-currency-capital-figure' : "**Sale or transfer of treasury shares.** Treasury capital:"

…and you’ll find a similar kind of thing to the associated_filings as well for annotations and resolutions. Things were even more exciting pre-2018 where these would not necessarily have their own description_values entry but I think that’s fixed now.

After all that if you still have oddities you will find that the data is somewhat “redundant” in that you may be able to fall back on using the older type parameter (type of form / filing) and looking those up (if e.g. description didn’t get you anywhere). We kept that as a backup since we already had that available from when we used the XML Gateway system.

There may be more elsewhere on the forum about this. Also if you feel like “cheating” you could always look at how Companies House’s own front end handles this (page code and templates.


Thanks, this is very helpful and I’ll certainly bookmark this as “doc reference”!

I figured out the templating of that description string in the end, which means that yes, you don’t need to worry about what is in that field as long as you do some generic replacement of vars (which worked for us so far).

The other use cases are also something we’d need to consider as well, so that’s very useful too.

Thanks again!