Skip to content
This repository has been archived by the owner on Sep 28, 2022. It is now read-only.

Filing events

Jump to bottom
Brian Evans edited this page Apr 28, 2021 · 5 revisions

Introduction

One of the types of event streams offered by Companies House is filing events.

These are events whenever a company makes a new filing with Companies House. This includes accounts, change in officers, change in PSC, change in registered office address and many others.

Usage

These are the datasource for the companies.stream grey filing cards, and are saved in a database table by a cloud function. They are also used to filter companies by recent events, such as a change in ownership or directors.

Sample event

{
        "resource_kind": "filing-history",
        "resource_uri": "/company/10676322/filing-history/MzI4OTQzODc5MGFkaXF6a2N4",
        "resource_id": "MzI4OTQzODc5MGFkaXF6a2N4",
        "data": {
            "barcode": "X9WQX0NE",
            "category": "accounts",
            "date": "2021-01-22",
            "description": "accounts-with-accounts-type-micro-entity",
            "description_values": {
                "made_up_date": "2020-03-31"
            },
            "links": {
                "self": "/company/10676322/filing-history/MzI4OTQzODc5MGFkaXF6a2N4"
            },
            "transaction_id": "MzI4OTQzODc5MGFkaXF6a2N4",
            "type": "AA"
        },
        "event": {
            "timepoint": 48990574,
            "published_at": "2021-01-22T18:28:02",
            "type": "changed"
        }
    }

The key pieces of information contained in each event are:

  • the company number
  • the resource id
  • the category
  • the description (and values)
  • the date of publication
  • the filing date

Unique ID

The resource id (identical to transaction id) is unique for each filing. Events are usually emitted multiple times by Companies House, so it is necessary to have a unique constraint on resource id in the database to prevent duplicate storage and retrieval of events.

Descriptions

The way the descriptions work, is that there is a code for a description, such as notification-of-a-person-with-significant-control and a map of values, such as {psc_name: 'Eduards Segals', date: '2019-10-23'}. These are machine readable pieces of data sent in the event, but can be converted to a human readable description by using enumerations defined by companies house in a YAML key-value map. Each description code is a key in this map (there are about a thousand keys), and the corrosponding value is a string with {} braces to format the values in. For example, a value could be **Notification** of {psc_name} as a person with significant control on {notification_date}. Note the ** to indicate a title, and the {psc_name} to indicate a value should go there. This value can be found in the previously mentioned map of values sent with the event. The title section is usually displayed in bold for emphasis.

Storing in Database

This is a sample of how Filing Events are stored in the database:

id category description_code description description_values filing_date timepoint published captured barcode type company_number
MzI5OTIzMDk4NGFkaXF6a2N4 persons-with-significant-control notification-of-a-person-with-significant-control **Notification** of Fiona Catan as a person with significant control on 2021-03-29 {"psc_name": "Fiona Catan", "notification_date": "2021-03-29"} 2021-04-28 57411746 2021-04-28 08:19:31.000000 2021-04-28 08:40:50.107012 XA3E3WJ5 PSC01 13261669
MzI5OTIyOTIwNWFkaXF6a2N4 persons-with-significant-control notification-of-a-person-with-significant-control **Notification** of Seema Begum Malik as a person with significant control on 2018-03-22 {"psc_name": "Seema Begum Malik", "notification_date": "2018-03-22"} 2021-04-28 57411743 2021-04-28 08:19:31.000000 2021-04-28 08:40:50.081413 XA3E3WK1 PSC01 10960182
MzI5OTIyOTEyOGFkaXF6a2N4 accounts accounts-with-accounts-type-dormant **Accounts for a dormant company** made up to 2020-12-31 {"made_up_date": "2020-12-31"} 2021-04-28 57410823 2021-04-28 08:19:31.000000 2021-04-28 08:40:42.705421 XA3E3WG9 AA 09362301
MzI5OTIyODQ1MmFkaXF6a2N4 accounts accounts-with-accounts-type-dormant **Accounts for a dormant company** made up to 2020-12-31 {"made_up_date": "2020-12-31"} 2021-04-28 57411741 2021-04-28 08:19:31.000000 2021-04-28 08:40:50.065954 XA3E3WMH AA 09337797
MzI5OTIyNzE2N2FkaXF6a2N4 officers appoint-person-director-company-with-name-date **Appointment** of Mr Jan Raineir Acosta as a director on 2021-04-14 {"officer_name": "Mr Jan Raineir Acosta", "appointment_date": "2021-04-14"} 2021-04-28 57411738 2021-04-28 08:19:31.000000 2021-04-28 08:40:50.037503 XA3E3WOA AP01 13305414

PS to perform the migration from the old table to the newer better one (28th April 2021 9AM), I ran this script:

INSERT INTO filing_events
    (
        SELECT DISTINCT ON (old.id) old.id,
                             old.category,
                             old.description_code,
                            -- go to stars rather than html
                             replace(replace(old.description, '<b>', '**'), '</b>', '**'),
                             null,
                             old.filing_date,
                             old.timepoint,
                             old.published,
                             old.captured,
                             old.barcode,
                             old.type,
                             old.company_number
     FROM filing_events_legacy old
     ORDER BY id, captured
    )
Clone this wiki locally