# Filing watches

A filing watch asks Companies House Lookup to keep an eye on a company. Every
hour, a background job checks each watched company for new filings and records
what it finds, so you hear about a change without anybody going looking.

## Start watching a company

**Watch filings** appears on the company snapshot and on the Customer, Vendor
and Contact cards. Choosing it registers the watch and opens the watch
register showing that company.

A company that is already watched simply opens the register - the row, with
its **Registered At** and **Last Polled At**, is the answer.

You need the **D2KL Edit** permission set to start or stop a watch. The first
watch in a company also creates the hourly job queue entry, which needs
permission to create job queue entries.

## The watch register

Open **Companies House Filing Watches** from the search.

| Column | Meaning |
|---|---|
| **Company Registration Number** | The company being watched |
| **Registered Name** | From the snapshot, so it is blank if the company has never been looked up |
| **Subscriber App** | Who or what asked for the watch - your user name if you started it from a card |
| **Enabled** | Clear this to pause a watch without losing it |
| **Registered At** | When the watch started |
| **Last Polled At** | When the background job last checked successfully |

The actions on the register:

| Action | What it does |
|---|---|
| **Poll now** | Checks every enabled watch for new filings straight away, without waiting for the hourly job, and tells you how many filing events it recorded |
| **Schedule hourly poll** | Creates the hourly job queue entry if it does not exist. Use it when the entry has been deleted |
| **View recorded filings** | Opens the filing events recorded for the selected company |
| **Companies House snapshot** | Opens the snapshot for the selected company |
| **Customer**, **Vendor** | Opens the customer or vendor carrying that registration number, or the list when several do |

**Last Polled At** only moves after a successful check, so a rate limit or an
outage never loses a window of time. The same period is checked again next
hour.

## What the background job does

Each hour, for every enabled watch, it:

1. fetches the company's filings since it last looked,
2. records any it has not seen before as **filing events**, and
3. re-checks the company's status, so a move into administration is noticed
   without anybody opening the card.

The status check honours **Cache TTL (Status)** on [Companies House Setup](https://docs.d2k.uk/companies-house-lookup/companies-house-setup) - one day by default - so it costs about one
extra call per watched company per day rather than one per hour. Set that TTL
to zero to stop status re-checks entirely.

A company that fails is retried next hour, and one failing company never
blocks the others.

## Filing events

Open **Companies House Filing Events** from the search to see everything the
poll has recorded, newest first, across all watched companies. From a filing
event you can open the **Companies House snapshot**, the **Customer** or the
**Vendor** carrying that registration number, and download the filed document
where there is one.

| Column | Meaning |
|---|---|
| **Entry No.** | The app's own number for the event |
| **Company Registration Number**, **Registered Name** | The company that filed |
| **Filing Date** | The date Companies House recorded the filing |
| **Filing Type**, **Description** | What was filed |
| **Document** | Ticked when there is a PDF you can download with **Download Document** |
| **Filing Status** | The status of the filing itself, for example accepted |
| **Notification Sent** | Ticked once the event has been passed on to anything that subscribes to it |

On the Role Centre, the **Latest Filings** part shows the most recent filing
events, and **View all** opens this list.

Filing events are kept under the standard **Retention Policies**, with a
minimum of 90 days. If you need them for longer than your policy keeps them,
copy them into your own table.

## Stop watching

Clear **Enabled** to pause a watch and keep its history, or delete the row to
stop entirely. Filing events already recorded are kept either way.

## If the poll stops

A notification appears on the Role Centre and the watch list if the background
job has not run when it should have. The usual cause is the licence of the
user who set the job queue entry to Ready - see
[Troubleshooting](https://docs.d2k.uk/companies-house-lookup/companies-house-troubleshooting).

If the job queue entry has been deleted, choose **Schedule hourly poll** to
create it again. To check the watched companies without waiting, choose
**Poll now**.

---
Source: https://docs.d2k.uk/companies-house-lookup/filing-watches
Last updated: 2026-10-10