Notice feed
The notice feed interface is exposed by the Official Register and follows VIN-5 Message Envelope. It delivers the notices published in the Official Register to member systems as a sequenced feed of envelopes, so that a system may learn of a registration, suspension or withdrawal on the day it is published rather than by consulting the register afterwards.
| Particular | Value |
|---|---|
| Catalogue identifier | API-04 |
| Provider | Official Register |
| Standard followed | VIN-5 Message Envelope |
| Interface version | 0.7 |
| Status | Interim |
| Listed | 6 September 2026 |
The feed carries every notice, whatever its subject. Systems that check the standing of an organisation before dealing with it should combine the feed with the registry lookup: the feed announces a change, and the lookup confirms the record after it. The feed is the model for the standards feed that the Developer Portal plans, which is listed in the API Catalogue as Planned.
Operations. The interface offers four operations: two for retrieving notices on request and two for managing a subscription.
| Operation | Purpose | Request | Response |
|---|---|---|---|
| Retrieve notices | Returns notices published since a given sequence number, oldest first. | A sequence number, or none for the earliest retained notice | Up to 100 envelopes, each carrying one notice |
| Retrieve notice | Returns one notice by its number. | A notice number | One envelope carrying the notice, or a not-found result |
| Subscribe | Registers a member system to receive each new notice as an envelope when it is published. | The identifier of the receiving system | A subscription reference |
| Unsubscribe | Ends a subscription. | A subscription reference | Acknowledgement |
The notice. Each envelope carries one notice with the fields below. The envelope itself carries the sender, recipient, timestamp and signature defined in VIN-5.
| Field | Meaning |
|---|---|
| Notice number | The number under which the Official Register published the notice. |
| Date | The date of publication. |
| Kind | One of Registration, Suspension, Withdrawal, Correction or General. |
| Subject | A one-line statement of what the notice concerns, naming the organisation or system affected where there is one. |
| Body | The full text of the notice as published. |
| Issuing office | The office of the Official Register that published the notice. |
| Sequence | The position of the notice in the feed. Increases by one with each notice and is never reused. |
Subscribing to the feed. A member system that wishes to receive notices as they are published follows the procedure below.
Step 1: Register the receiving system
The receiving system must be registered with the Identity Service, since the Official Register addresses each envelope to a registered system identifier.
Step 2: Call Subscribe
Supply the system identifier. The subscription reference returned should be kept; it is needed to end the subscription. A system may hold at most five subscriptions.
Step 3: Record the sequence number of each envelope received
Envelopes are delivered in sequence. A gap in the sequence means a notice has been missed; a repeat means an envelope has been delivered twice and should be ignored.
Step 4: Fill gaps with Retrieve notices
On finding a gap, or on restarting after an interruption, call Retrieve notices from the last sequence number received. The feed retains twelve months of notices.
Step 5: Acknowledge each envelope
The Official Register expects an acknowledgement, in the form defined by VIN-5, for every envelope delivered. An envelope not acknowledged within one hour is delivered again, up to three times.
Error conditions. A request that cannot be answered receives one of the following results.
- Unknown sequence
- The sequence number supplied is greater than the latest published, or earlier than the oldest retained. The response gives both bounds.
- Notice not found
- No notice bears the number supplied.
- Recipient not registered
- The system identifier supplied to Subscribe is not registered with the Identity Service.
- Subscription limit reached
- The system already holds five subscriptions. End one before creating another.
- Delivery suspended
- Three deliveries of the same envelope have gone unacknowledged and the subscription has been suspended. It is resumed by calling Subscribe again with the same system identifier.
Versions. The interface is Interim at Version 0.7, the earliest of the four available interfaces. Filtering of subscriptions is planned before confirmation. Changes are announced on this page and recorded in the API Catalogue.
6 September 2026
Version 0.7 listed as Interim
Retrieve and subscribe operations available. Acknowledgement and redelivery rules published.
Forthcoming
Version 0.8
Filtering of a subscription by kind of notice, so that a system may receive only suspensions and withdrawals, expected before the end of 2026.
Forthcoming
Confirmation at Version 1.0
Expected after the first review of VIN-5 in March 2027.
Questions about the interface may be sent to contact@developer.gov.vin and are passed to the Official Register where they concern its operation. The envelope the feed uses is described under Standards; the terms used on this page are defined in the Glossary.