The "Unverified" Gap: Handling New IDV Statuses & VS01 Schemas

1

Based on the latest API specifications and the rollout of the Economic Crime and Corporate Transparency Act (ECCT Act) measures as of late 2025, here is a draft article tailored for the Companies House Developer Forum.

It specifically addresses the “pain points” developers are likely facing right now regarding the mandatory Identity Verification (IDV) rollout that began on November 18, 2025.

Hi everyone,

With the mandatory Identity Verification (IDV) rollout now live (as of Nov 18), many of us are deep in the weeds of updating our integrations. While the policy intent is clear, the API behavior for “unverified” edge cases has been a bit of a moving target.

I wanted to share what we’re seeing regarding the new JSON fields and VS01 schemas, and ask how you are handling the “pending” limbo states in your software.

1. The New Status Fields (It’s not just a boolean)

If you haven’t updated your object models yet, watch out for the new date fields in the officers and psc endpoints. We are seeing that simple “is verified?” logic isn’t enough. You need to handle:

  • appointment_verification_start_on: This seems to be the primary indicator that a verification statement has been successfully linked.
  • appointment_verification_statement_due_on: Critical for existing directors who are in the 12-month transition period.
  • identity_verified_on: Note: This appears to be populated specifically when verification is done via an ACSP (Authorised Corporate Service Provider). If your user verified directly via GOV.UK One Login, this might behave differently or be absent.

The Gotcha: We’ve noticed cases where appointment_verification_start_on is null even after a user claims they’ve verified. There seems to be a propagation lag between the IDV service and the public data API.

2. Handling Rejections (New Appointments)

For those submitting new AP01 filings via the XML Gateway or REST API:
Are you receiving specific 4xx validation errors when the appointee’s Personal Code is invalid or unlinked?

  • We are trying to distinguish between a Generic 400 (bad data) and a specific “Unverified Officer” rejection.
  • Tip: Ensure your UI collects the 11-character Personal Code for new appointments, as the API now strictly enforces this link before the appointment is registered.

3. The VS01 Schema for Existing PSCs

For existing PSCs, the new PSCVerificationStatement-v1-0.xsd (VS01) is the standard.
Question for the group: Has anyone successfully automated the VS01 submission for a batch of existing PSCs? We are debating whether to build this into our software or instruct clients to use the WebFiling interface for this one-off “catch-up” task to avoid the development overhead.

Open Discussion: The “Lag”

How are you handling the data consistency lag?

  • Option A: Trust the user’s word that they verified and allow them to proceed in your UI (risking a failed filing).
  • Option B: Poll the officers endpoint until appointment_verification_start_on appears (risking user frustration).

If anyone has found a reliable way to “force” a status refresh or has a mapping of the new specific error codes, I’d love to hear it.

(And a big thanks to the team for the updated Swagger docs—they’ve been essential!)

Why this topic works:

  • Technical Specificity: It references actual field names (appointment_verification_start_on) and schemas (VS01), showing you know what you are talking about.
  • Timely Problem: It addresses the “lag” issue and the distinction between ACSP verification vs. One Login, which is a common source of confusion right now.
  • Strategic Question: The question about building vs. skipping the VS01 integration is a genuine business logic problem that other product managers/developers will want to discuss.

source: United Kingdom - Mandatory Identity Verification at Companies House Now in Effect - BDO Local

2

Disclaimer: Feel like I should add that the following isn’t intended to be authorative, just my take and understanding of the situation:

I feel like your issues (in section 1 at least) stem from this statement:

As far as I’m aware this isn’t a gotcha/lag/gap: verification (IDV) and appoinment verification are two separate processes and the former is never going to propogate to the latter. appointment_verification_start will always be null up until the relevant form is submitted (mostly CS01, but also incorporation, appointments and the PSC specific forms). It’s the submission of this form, with a valid personal code that dictates this value.

So not lag, the value just doesn’t exist yet. It’s not something you’ll be able to force to refresh. Your option A and B above just don’t make sense to me in this context. Yes there will be a gap between the time someone is verified and they become appointment verified, but this is a “by design” gap as the two statuses represent two different things. One does not inform the other.

FWIW our handling of IDV in general follows from this. The system we have in place for managing IDV either on behalf of clients or collating personal codes if they are doing themselves, is mostly divorced from our general compliance systems, which only cares whether or not they have supplied us with a code by a particular date.

More information from CH here: Officer appointment verified but identify is not verified This clarified some confusion I had regarding the contents of the three fields above.

Of course this is all further confused by the current issues with the filing of some forms, which I can imagine is a right pain (on a code level I’m only dealing with incorporations which were thankfully working day 1!).