# Document description\_values for Filings API call **URL:** \ **Category:** Documentation Issues\ **Created:** [August 11, 2021, 10:40am UTC](http://forum.companieshouse.gov.uk/t/document-description-values-for-filings-api-call/4256 "2021-08-11T10:40:21Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![cos\_marginean](http://forum.companieshouse.gov.uk/letter_avatar_proxy/v4/letter/c/a3d4f5/32.png) [@cos\_marginean](http://forum.companieshouse.gov.uk/u/cos_marginean)\ **Post date:** [August 11, 2021, 10:40am UTC](http://forum.companieshouse.gov.uk/t/document-description-values-for-filings-api-call/4256/1 "2021-08-11T10:40:22Z")
The documentation [here](https://developer-specs.company-information.service.gov.uk/companies-house-public-data-api/reference/filing-history/list) 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](https://find-and-update.company-information.service.gov.uk/company/04591440/filing-history) so it would be good to understand what we can expect there. ---
**Author:** ![voracityemail](http://forum.companieshouse.gov.uk/letter_avatar_proxy/v4/letter/v/b77776/32.png) [@voracityemail](http://forum.companieshouse.gov.uk/u/voracityemail)\ **Post date:** [August 11, 2021, 6:07pm UTC](http://forum.companieshouse.gov.uk/t/document-description-values-for-filings-api-call/4256/2 "2021-08-11T18:07:18Z")
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 [find-and-update.company-information.service.gov.uk](http://find-and-update.company-information.service.gov.uk) 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). Example: 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", "description_values": { "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_values": { "description": "Director's particulars changed" }, "description": "legacy", "barcode": null, "transaction_id": "MDA4NTk4NjkzNWFkaXF6a2N4" } ``` And a “misc”: ``` { "type": "MISC", "description_values": { "description": "Certificate of incorporation" }, "description": "miscellaneous", "date": "1969-03-18", "category": "miscellaneous", "links": { "document_metadata": "https://frontend-doc-api.companieshouse.gov.uk/document/GSv5Q4-u6uNnqbNqBth8cj7CG2idPAT-xyJ6EYYVEH0", "self": "/company/SC046419/filing-history/MDE4NTU1MDMwN2FkaXF6a2N4" }, "pages": 2, "paper_filed": true, "barcode": null, "transaction_id": "MDE4NTU1MDMwN2FkaXF6a2N4" } ``` Second complication: [your example (company 04591440)](https://find-and-update.company-information.service.gov.uk/company/04591440/filing-history) 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": "https://frontend-doc-api.company-information.service.gov.uk/document/CbB8LKPB8CyZthAVeuDC1Atmg2iBxGXKCWtOugyROfA" }, "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_filing`s 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](https://github.com/companieshouse/ch.gov.uk) handles this ([page code](https://github.com/companieshouse/ch.gov.uk/blob/master/lib/ChGovUk/Controllers/Company/FilingHistory.pm) and [templates](https://github.com/companieshouse/ch.gov.uk/tree/master/templates/company/filing_history). Enjoy! ---
**Author:** ![cos\_marginean](http://forum.companieshouse.gov.uk/letter_avatar_proxy/v4/letter/c/a3d4f5/32.png) [@cos\_marginean](http://forum.companieshouse.gov.uk/u/cos_marginean)\ **Post date:** [August 11, 2021, 7:05pm UTC](http://forum.companieshouse.gov.uk/t/document-description-values-for-filings-api-call/4256/3 "2021-08-11T19:05:49Z")
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!