Migrating from the v0 legacy API to v1
If you have been using VerifyVAT since the beta phase, this guide is for you.
During beta, VerifyVAT exposed an API surface that is now referred to as the Legacy API or v0. The legacy API is still reachable at:
https://api.verifyvat.com/v0/:type/:idThis endpoint is kept only to ease the migration path. It will not evolve further. All current documentation, behaviour, and guarantees apply to v1, and all new integrations should target v1 directly.
This guide explains what changed between the legacy (v0) API and v1, why those changes were introduced, and how to map the concepts you already know onto the current API without guesswork.
Foundational changes
The most important change in v1 is not a renamed field or a reshaped payload. It is a change in structure.
In v1, verification responses are explicitly split into two parts:
- process, which describes how verification was performed
- entity, which describes what could be resolved about the subject
This split is defined and documented in Verify an ID, the central reference for the v1 verification response model.
The intent is to separate verification mechanics from resolved data. Verification and entity resolution are related, but they are not the same thing, and they do not always succeed or fail together.
The process section
The process section records the execution of a verification request. It includes the normalised input, the registries that were consulted, whether data came from a live registry or from cache, the syntactic validity of the identifier, the derived verification outcome, and any issues encountered during execution. This is where v1 makes verification explicit and inspectable.
A key difference is that the legacy v0 was single-registry, while v1 is cross-registry by design.
A single v1 request may consult multiple registries, and each contribution is represented explicitly in the response.
The process section is always present, even when no entity can be resolved. Verification can still produce meaningful outcomes without entity-level data.
How verification works end to end is described in Verify an ID, while how evidence from multiple registries is combined is described in Cross-registry checks. You can read about our approach to caching and data freshness in Caching and stale data.
The entity section
The entity section represents the resolved subject, when resolution is possible.
It may include data like identifiers, registrations, names, addresses, status records, and timeline events.
It may also be null.
A null entity is not an error. It means the verification process could not confidently resolve an entity beyond syntax and registry outcome.
This distinction is intentional in v1. A request can be processed successfully, and verification can complete, without producing a resolved entity. The structure of the entity object and the rules used to normalise and merge data across registries are defined in Verify an ID and expanded in Data normalisation.
Request success versus verification outcome
v1 uses a shared response envelope across all endpoints. That envelope includes a success field that indicates whether the request was successfully processed at the system level, and a data field that contains the verification result when applicable.
success | Meaning |
|---|---|
false | The request failed at the system level. This includes authentication errors, malformed input, and hard rate limits. |
true | The request was processed. Verification semantics live inside data.process, not in the envelope. |
This distinction matters if your v0 integration treated an HTTP 200 response as a successful verification. In v1, request success and verification outcome are separate concerns. The envelope format and its semantics are explained in Response envelope.
Operational metadata moved out of the payload
In v0, operational fields such as the request identifier (eventId), rate-limit indicators, and overage flags were embedded directly in the response body.
In v1, operational metadata is deliberately exposed via HTTP headers instead of the payload.
If you logged or surfaced eventId previously, you should now read the corresponding request identifier header. Rate-limit and overage signals follow the same pattern.
The full list of response headers and their meaning is documented in Response envelope.
Mapping legacy concepts to v1
Once the v1 structure is clear, mapping legacy concepts becomes mechanical.
Input and identifiers
| Legacy concept | v1 location | Notes |
|---|---|---|
Input value | process.input.value | The value actually processed |
Identifier type | process.input.type | Canonical identifier type |
Formatted ID | process.input.display | Canonical display form |
Alternative identifiers | entity.identity.identifiers[] | All identifiers are first-class |
Validity and verification
| Legacy concept | v1 location | Notes |
|---|---|---|
Structural validity | process.output.syntax.valid | Syntax and checksum only |
Pattern-only checks | process.output.syntax.method | Explicitly stated |
Verified boolean | process.output.outcome with issues | Multi-state outcome |
These fields are covered in more detail in Verify an ID.
Entity data
| Legacy concept | v1 location | Notes |
|---|---|---|
Name | entity.names[] | Multiple names may exist |
Address | entity.addresses[] | Multiple address kinds |
Business type | entity.identity.legalForm | Normalised representation |
Status | entity.identity.statusRecords[] | Explicit records |
Lifecycle | entity.identity.registrations[] or entity.timeline[] | Depending on the context |
Entity structure and normalisation rules are documented in Verify an ID and Data normalisation.
Choosing how far to migrate
Not every integration needs full adoption of the v1 model. Some clients derive a simplified snapshot from the entity section and use the process section only for validation and audit signals. Others progressively adopt multi-identifier and multi-registry behaviour. Some treat v1 as an evidence engine and design around explicit outcomes and provenance. All of these approaches are valid.
The Legacy API exists only to make this transition possible. v1 is the stable foundation going forward.