Incident submission
The incident submission interface is exposed by the Status Service and follows VIN-3 Incident Reporting Format. Through it a member organisation reports an event affecting the availability, integrity, security or data quality of one of its connected systems, keeps the report up to date as the incident develops, and closes it with a statement of cause and resolution. The Status Service uses the reports it receives to inform other members of the state of the Network.
| Particular | Value |
|---|---|
| Catalogue identifier | API-03 |
| Provider | Status Service |
| Standard followed | VIN-3 Incident Reporting Format |
| Interface version | 0.8 |
| Status | Interim |
| Listed | 6 September 2026 |
A report is a formal record. Once lodged it cannot be deleted, only amended, and every revision is retained. The interface therefore asks for facts rather than conclusions: the cause of an incident is recorded on closure, when it is known, and not before. Every request is carried in a VIN-5 envelope with an identity assertion issued for a system of the reporting organisation, as described under APIs.
Operations. The interface offers four operations.
| Operation | Purpose | Request | Response |
|---|---|---|---|
| Submit report | Lodges a new incident report with the Status Service. | An incident report in the VIN-3 format | A report reference and the time of receipt |
| Amend report | Adds to or corrects a report already lodged. Every amendment creates a new revision; earlier revisions are retained. | Report reference and the fields to be changed | The new revision number and the time of receipt |
| Close report | Records that the incident is over and states its cause and resolution. | Report reference and a closing statement | Acknowledgement with the time of closure |
| Retrieve report | Returns a report lodged by the calling organisation at its latest revision, or at a named revision. | Report reference, optionally with a revision number | The report as lodged |
The incident report. VIN-3 defines the fields below. A report that omits a required field is refused; the fields marked On closure are supplied with the closing statement.
| Field | Meaning | When |
|---|---|---|
| Reporting organisation | Member key of the organisation lodging the report. Must match the issuing organisation of the assertion. | Required |
| Affected system | Identifier of the member system affected, as registered with the Identity Service. | Required |
| Category | One of Availability, Integrity, Security or Data quality. | Required |
| Severity | 1 (Network-wide effect) to 4 (confined to one system, no effect on others). | Required |
| Started at | Time at which the incident is believed to have begun. | Required |
| Detected at | Time at which the reporting organisation became aware of it. | Required |
| Description | What has happened, in plain terms, without speculation as to cause. | Required |
| Impact | Which interfaces, records or other organisations are affected and how. | Required |
| Contact | An email address at the reporting organisation to which questions may be sent. | Required |
| Cause | The established cause, once known. | On closure |
| Resolution | What was done to end the incident and to prevent its recurrence. | On closure |
Severity and time to report. The severity stated in a report determines how soon after detection it must be lodged. A report may be lodged with the fields known at the time and amended as the position becomes clearer; it is better to report early and amend than to wait.
| Severity | Meaning | Report to be lodged |
|---|---|---|
| 1 | Network-wide: affects the envelope, identity assertion or registry for all members. | Within one hour of detection |
| 2 | Affects other organisations' systems or a Network service. | Within four hours of detection |
| 3 | Confined to the reporting organisation but affects data exchanged with others. | Within one working day |
| 4 | Confined to one system; no effect on others. Reported for the record. | Within five working days |
Error conditions. A request that cannot be answered receives one of the following results.
- Missing required field
- A required field of the report is absent or empty. The response names the field. No report is lodged.
- Unknown category or severity
- The value supplied is not one of those defined in VIN-3. No report is lodged.
- Assertion lacks authority
- The identity assertion in the envelope was not issued for a system of the reporting organisation named in the report. No report is lodged.
- Reference not found
- The report reference supplied does not exist, or belongs to another organisation. Reports may be retrieved and amended only by the organisation that lodged them.
- Report already closed
- An amendment or a second closure has been attempted on a closed report. A closed report may be reopened only by writing to the Status Service.
Versions. The interface is Interim at Version 0.8. One further operation is planned before confirmation. Changes are announced on this page and recorded in the API Catalogue.
6 September 2026
Version 0.8 listed as Interim
Submit, amend, close and retrieve available. The required fields of VIN-3 and the reporting times by severity published.
Forthcoming
Version 0.9
Addition of an operation returning the reports lodged by the calling organisation in a period, expected before the end of 2026.
Forthcoming
Confirmation at Version 1.0
Expected after the first review of VIN-3 in June 2027.
Questions about the interface may be sent to contact@developer.gov.vin and are passed to the Status Service where they concern its operation. The reporting format is described under Standards; the terms used on this page are defined in the Glossary.