Registry lookup
The registry lookup interface is exposed by the Member Registry and follows VIN-4 Registry Data Model. It allows a member system to obtain the registry record of any organisation listed on the register, to check the current status of an organisation before dealing with one of its systems, and to see the history of that status. A record returned by the interface may be relied upon as evidence of certification without further enquiry.
| Particular | Value |
|---|---|
| Catalogue identifier | API-01 |
| Provider | Member Registry |
| Standard followed | VIN-4 Registry Data Model |
| Interface version | 0.9 |
| Status | Interim |
| Listed | 6 September 2026 |
The interface is read-only. Changes to the register are made only by the Member Registry through its own procedures and are published as notices; a system that needs to know of a change as it happens should subscribe to the notice feed rather than poll this interface. Every request is carried in a VIN-5 envelope and must include an identity assertion for the calling system, as described under APIs.
Operations. The interface offers four operations. Each returns records in the VIN-4 data model; the fields of a record are set out below the table.
| Operation | Purpose | Request | Response |
|---|---|---|---|
| Lookup by key | Returns the registry record of the organisation that holds a given member key. | One member key | One registry record, or a not-found result |
| Search by name | Finds organisations whose registered name contains the text supplied. | Text of at least three characters | Up to 50 registry records, in order of name |
| Retrieve status | Returns only the current status of an organisation and the date from which it has applied. Intended for systems that check status on every transaction. | One member key | Status and effective date |
| Retrieve history | Returns every change of status recorded against an organisation since its first listing. | One member key | A list of status changes, each with its date and the notice that recorded it |
The registry record. A record carries the following fields. Fields marked Always are present in every record; the others are present only in the circumstances stated.
| Field | Meaning | Present |
|---|---|---|
| Key | The member key under which the organisation is listed. Unique and never reused. | Always |
| Organisation | The registered name of the organisation. | Always |
| Kind | Whether the organisation is a department, a Network service or a member organisation. | Always |
| Status | One of Active, Suspended, Withdrawn or Pending. | Always |
| Certified since | The date on which the organisation was first listed with the status Active. | When the status is or has been Active |
| Last change | The date of the most recent change to any field of the record. | Always |
| Certificate | The reference of the current certificate issued by the Member Registry. | When the status is Active |
Error conditions. A request that cannot be answered receives one of the following results. Each is returned in the envelope with the sequence number of the request to which it relates.
- Not found
- No organisation holds the key supplied, or no name contains the text supplied. A not-found result is not evidence that an organisation has never been listed; use Retrieve history for a key that was once valid.
- Malformed key
- The key supplied does not have the form defined in VIN-4. The request is refused before any lookup is made.
- Assertion rejected
- The identity assertion in the envelope is missing, expired or not issued for a member system. No lookup is made.
- Too many requests
- A single system has made more than 600 requests in one minute. Further requests are refused until the minute has passed. Systems that check status on every transaction should use Retrieve status, which is not counted against this limit.
- Service unavailable
- The Member Registry is not able to answer. The request may be repeated after 30 seconds; a record obtained within the previous 24 hours may be relied upon in the meantime.
Versions. The interface is Interim at Version 0.9. The operations listed are not expected to change before confirmation; the form of the history result may be revised after the first review of VIN-4. Changes are announced on this page and recorded in the API Catalogue.
6 September 2026
Version 0.9 listed as Interim
All four operations available to member organisations. Documentation of the record fields and error conditions published.
Forthcoming
Confirmation at Version 1.0
Expected after the first review of VIN-4 in June 2027, provided the interface has been stable for three months and two member systems have declared conformance to VIN-4.
Questions about the interface may be sent to contact@developer.gov.vin and are passed to the Member Registry where they concern its operation. The data model the interface follows is described under Standards; the terms used on this page are defined in the Glossary.