Description Values / Description And FilingHistory Endpoint

API Issues
#1

Hi!

In the Description Enumeration there are a couple of placeholders we have to map.

We did not find a documentation or example data to know the type of below fields.

Category ANNUAL_RETURN: branch_number & representative_details
Category CHANGE_OF_NAME: change_name
Category INCORPORATION: company_type
Category LIQUIDATION: form_attached
Category MORTGAGE: charge_number
Category OFFICERS: branch_number & change_details & officer_address
Category CONFIRMATION_STATEMENT: original_description
Category DISSOLUTION: branch_number & company_number & change_details

Can you please be so kind to tell me the corresponding type of above fields ? So that I do not have to guess ? :slight_smile:

Another question regarding this endpoint GET https://api.companyinformation.service.gov.uk/company/{company_number}/filing-history

→ is it possible to add a sortparam to sort the items ?

Thanks in advance,

Reinhard!

#2

The API return a JSON response, depending on the lanugage you are using will determing what you do with the JSON.

I am using C#.NET so used the following to parse the response https://json2csharp.com/

I have a c# demo you can download from here https://github.com/lukhezo/CompaniesHouse

Below is the filling history response as C#
------------------------------------------JSON To C#------------------------------------------------------------------------

public class Capital
{
    public string figure { get; set; }
    public string currency { get; set; }
    public string date { get; set; }
}

public class DescriptionValues
{
    public string change_date { get; set; }
    public string officer_name { get; set; }
    public string termination_date { get; set; }
    public List<Capital> capital { get; set; }
    public string date { get; set; }
    public string made_up_date { get; set; }
    public string description { get; set; }
    public string appointment_date { get; set; }
}

public class FilingHistoryLinks
{
    public string self { get; set; }
    public string document_metadata { get; set; }
}

public class Resolution
{
    public string category { get; set; }
    public string description { get; set; }
    public string subcategory { get; set; }
    public string type { get; set; }
    public DescriptionValues description_values { get; set; }
}

public class Annotation
{
    public string annotation { get; set; }
    public string category { get; set; }
    public string date { get; set; }
    public string description { get; set; }
    public DescriptionValues description_values { get; set; }
    public string type { get; set; }
}

public class FilingHistoryItem
{
    public string action_date { get; set; }
    public string category { get; set; }
    public string date { get; set; }
    public string description { get; set; }
    public DescriptionValues description_values { get; set; }
    public FilingHistoryLinks links { get; set; }
    public string subcategory { get; set; }
    public string type { get; set; }
    public int pages { get; set; }
    public string barcode { get; set; }
    public string transaction_id { get; set; }
    public bool? paper_filed { get; set; }
    public List<Resolution> resolutions { get; set; }
    public List<Annotation> annotations { get; set; }
}

public class FilingHistoryResponse
{
    public List<FilingHistoryItem> items { get; set; }
    public string filing_history_status { get; set; }
    public int total_count { get; set; }
    public int start_index { get; set; }
    public int items_per_page { get; set; }
}
#3

If I’ve understood your first question correctly there is a simple answer and a longer one. (For your second question - that’s a change request you’ll have to ask Companies House about as I’m not aware that you can sort at the moment).

Simple answer: “string”! The fields you’re looking for to fill in the placeholders should all appear in the JSON response in the description_values object in the filingHistoryItem (or an object in the items array in the filingHistoryList object). This has the general form:

 "description_values" : {
    "{value_name}" : "{value}"
 }

… where the different {value_name} keys will include the placeholders in the appropriate filing history descriptions “enum constant”. The {value} is what you can substitute in.
In this system as far as I’m aware both sides are always strings in the JSON. (Companies House has in general been know to have occasional odd values in its data however so we always validate…).

Longer answer:
Some examples - I’m using curl here to get the data for simplicity / general applicability.

Lots of the things you ask about seem to relate to Foreign Companies (Companies House code starting “FC”) and their “UK establishments” (Companies House code starting “FC”). There can be multiple “UK establishments” associated with one “Foreign Company”. Here’s an example pair:
FC008102 - BR000775

Looking at these you’ll find that the “UK establishment” doesn’t hold its own filing history - this is on the “parent” Foreign Company:

curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/BR000775/filing-history”

{
    "items_per_page": 25,
    "items": [ ],
    "filing_history_status": "filing-history-available",
    "total_count": 0,
    "start_index": 0
}

Let’s look at some specific ones on the FC. First officers:

curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/FC008102/filing-history/MzE3NDgzMzg3N2FkaXF6a2N4”
(I’ve snipped some irrelevant details in the response)

{
    "category": "officers",
    "description": "termination-person-authorised-overseas-company",
    "subcategory": "termination",
    "description_values": {
        "change_details": "Transaction OSTM03- BR000775 Person Authorised to Represent terminated 28/07/2016 hwa joong joo"
    },
    "links": {
       ...
    },
    "date": "2017-05-02", "paper_filed": true,
    "type": "OSTM03", "pages": 3, "barcode": "A64WKU86",
    "transaction_id": "MzE3NDgzMzg3N2FkaXF6a2N4"
}

So here you’d look up the description (“termination-person-authorised-overseas-company”) in the “Enum constants”. That gives us "**Termination of appointment** for a UK establishment - {change_details}".

So we can look up “change_details” in the description_values member of the JSON response and substitute that into the description text we got back.

That’s the general principle. I don’t have examples to hand for everything you’re asking about but here are a few more:

Officers:
curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/FC008102/filing-history/MzE3NDgzMjM0MWFkaXF6a2N4”

{
    "category": "officers",
    "description": "appoint-person-authorised-represent-overseas-company-with-appointment-date",
    "subcategory": "appointments",
    "description_values": {
        "branch_number": "BR000775",
        "officer_name": "Jong Rae Kim",
        "new_address": "Korean Air 24 Saville Row, London, W1S 2ES, England",
        "change_date": "2016-07-08"
    },
    "paper_filed": true, "type": "OSAP05", "date": "2017-05-02",
    "pages": 3, "barcode": "A64WKU7L",
    "transaction_id": "MzE3NDgzMjM0MWFkaXF6a2N4",
    "links": {
        ...
    }
}

Address change:
curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/FC008102/filing-history/MzA1NzE5MjQwNWFkaXF6a2N4”

{
    "category": "other",
    "description": "change-company-details-by-uk-establishment-overseas-company-with-change-details",
    "description_values": {
        "change_type": "Address Change",
        "branch_number": "BR000775",
        "change_details": "66-68 piccadilly, london, , W1V 0HJ",
        "change_date": "2012-05-04"
    },
    "barcode": "A18AYH4Z", "type": "OSCH01",
    "transaction_id": "MzA1NzE5MjQwNWFkaXF6a2N4",
    "pages": 3, "date": "2012-05-09", "paper_filed": true,
    "links": {
        ...
    }
}

A more complex one - a resolution (change of name):
curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/10348588/filing-history/MzI2NDc1MTk1NGFkaXF6a2N4”

{
    "category": "resolution",
    "subcategory": "certificate",
    "description": "resolution",
    "description_values": {
        "description": "Resolutions"
    },
    "associated_filings": [
        {
            "category": "change-of-name",
            "description": "change-of-name-by-resolution",
            "date": "2020-05-14", "type": "NM01"
        }
    ],
    "resolutions": [
        {
            "category": "change-of-name",
            "subcategory": "resolution",
            "description": "resolution-change-of-name",
            "description_values": {
                "resolution_date": "2020-05-12"
            },
            "delta_at": "20200514065732520317", "type": "RES15"
        }
    ],
    "type": "RESOLUTIONS", "date": "2020-05-14", "pages": 3,
    "barcode": "X94YYSZM", "transaction_id": "MzI2NDc1MTk1NGFkaXF6a2N4",
    "links": {
        ...
    }
}

A couple that just have a “description” - Legacy ones should be OK but I think in the past we found some where we had to look this up using the type.

Miscellaneous:
curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/FC008102/filing-history/OTg2NTM5MjVhZGlxemtjeA”

{
    "category": "miscellaneous",
    "description": "miscellaneous",
    "description_values": {
        "description": "Admin closure"
    },
    "date": "2002-04-10", "paper_filed": true,
    "type": "MISC", "pages": 1, "transaction_id": "OTg2NTM5MjVhZGlxemtjeA"
    "links": {
        ...
    }
}

Mortgage - legacy:

curl -u YOUR_API_KEY: “https://api.company-information.service.gov.uk/company/FC008102/filing-history/MzA0Mzk5NzQzOGFkaXF6a2N4”

{
    "category": "mortgage",
    "description": "legacy",
    "description_values": {
        "description": "Particulars of a mortgage or charge / charge no: 81"
    },
    "date": "2011-09-16", "type": "MG01",
    "pages": 11, "paper_filed": true,
    "barcode": "A9E4KXL3", "transaction_id": "MzA0Mzk5NzQzOGFkaXF6a2N4",
    "links": {
        ...
    }
}
1 Like