Monthly supplier check against official company registers

On the first Monday of each month, re-verify our entire supplier base against official company registers so we never pay a company that has quietly been dissolved. Run this on a cron trigger set to the first Monday of every month.

Start by pulling the supplier list from Xero with List Contacts, and keep only the contacts marked as suppliers. This is the working set for the pass.

For each supplier, find its registry record in OpenCorporates. Use Search Companies on the supplier's registered company name, restricting to the supplier's jurisdiction where Xero gives you enough address detail to infer one. From the search results, pick the record you are confident is the same legal entity, then call Get Company with that record's jurisdiction code and company number to read its current status. A company is identified by the jurisdiction code and company number pair rather than a single id, so carry both through the workflow. Then call List Company Statements for that company to catch gazette and insolvency notices, which are the real point of this check because they surface trouble before the official registry status flips.

Where the name match is ambiguous, skip it rather than guessing. Treat a match as ambiguous when several companies share the name with no clear jurisdiction or address tiebreak, when the only candidates are dissolved shells that may or may not be the same business, or when the Xero contact name is a trading name that does not correspond to a registered entity. Matching the wrong company is worse than not matching, since it can either clear a failing supplier or wrongly accuse a healthy one. Collect every skipped supplier into a separate needs manual review list.

Treat a supplier as flagged when its registry status is dissolved, in liquidation, struck off, or the local equivalent in that jurisdiction, or when its statements include a new insolvency or gazette notice. To decide whether a notice is new, compare the notice date against the date of the previous run, which you can read from the most recent check date in the audit log. Only treat notices dated after the previous check as new, so the same old notice does not get re-reported every month.

Post a Slack message to the finance channel with Send a Message, containing only the flagged suppliers. For each one give the supplier name as it appears in Xero, the matched company name and number, the registry status, the specific notice and its date where that is what triggered the flag, and a link to the OpenCorporates record. Add the needs manual review list underneath as a short separate section. Do not list the clean suppliers, and do not pad the message with a summary of everything checked, since this channel is only worth reading if it stays signal only. If nothing was flagged and nothing needs review, post a single short line confirming the check ran and found no issues, so the absence of a message is never confused with a workflow that failed to run.

Append the full pass, including every clean supplier, to the Google Sheets audit log with Append Values. Write one row per supplier with the check date, the supplier name from Xero, the matched company name, the jurisdiction code, the company number, the registry status that was read, whether any insolvency or gazette notice was found along with its date, a link to the OpenCorporates record, and the outcome as clean, flagged, or needs manual review. The audit log matters as much as the alert, because the point is being able to evidence that the check happened and against which record, not just that something was found.

Be economical with lookups. OpenCorporates enforces per plan daily and monthly quotas, which is why this runs monthly rather than more often. Do not re-search a supplier you have already resolved in this pass, and if the quota is exhausted partway through, still post what you found and log the suppliers you got through, noting in the log which ones were not reached so the next run can pick them up.