API specification

Version 4.15.32

This document details all the functions for integrating with Street Manager via the latest version of the API. See the ‘Versions and Changes’ section for more details on previous versions. The documentation for the stable version of the API is available here.

Table of contents

Introduction

This is the API guidance documentation for Street Manager, intended as a guide for developers integrating their systems to submit and retrieve information about street works. It is intended as a technical guide to be used with the API definition documentation and not a business change guide.

System context diagram

The Street Manager APIs are RESTful APIs to read/write data to the centralised Street Manager system following GDS guidelines, not a peer to peer solution.

References

For supplemental details, please see the following documents:

  1. Business rules, for details on Street Managers business processes and logic
  2. Registration, for details on how to start using Street Manager with-in your organisation

Swagger Documentation

The services APIs are documented and defined using OpenAPI Specification Version 2 (Swagger). This allows developers to get the full technical detail for the API endpoints, including Request/Response object definitions. The Swagger JSON includes comments for field validation rules and references to the business rules. You can use the files to generate interface code for your chosen language.

The Swagger JSON files for each API are available below:

  1. Work API JSON
  2. Reporting API JSON
  3. Street Lookup API JSON
  4. GeoJSON API JSON
  5. Party API JSON
  6. Data Export API JSON
  7. Event API JSON
  8. Sampling API JSON

You can see the Swagger definitions rendered as HTML on the SANDBOX environment:

  1. Work API
  2. Reporting API
  3. Street Lookup API
  4. GeoJSON API
  5. Party API
  6. Data Export API
  7. Event API
  8. Sampling API

Please be aware of the following:

If you attempt to validate the above swagger files using the online tool https://editor.swagger.io or swagger-cli, you may see schema errors. Please note we are aware of this issue and it will not stop you from being able to generate mock server/clients. We aim to fix this in a future version.

Swagger UI does not display all description text for enumerations and child elements, instead check each of the swagger.json files above for full description text.

In the Work API several request definitions contain internal_user_identifier and internal_user_name. Please see Works API - Delegated Users section for details.

Environments

The Street Manager service provides two separate isolated application service environments. Both of these environments contains a full stack deployment of Street Manager and are designated for specific purposes, as outlined below.

Service environments

SANDBOX environment

API URL: https://api.sandbox.manage-roadworks.service.gov.uk

  1. SANDBOX environment is primarily intended as an integration testing environment for API integrators and an initial orientation environment for organisations intending to use the Street Manager web frontend.
  2. Each Public Beta participant organisation will be provided with credentials as part of the initial onboarding process. User credentials can be valid for either the Street Manager web frontend, or the Street Manager API interfaces - not both at the same time. In order to have existing credentials reconfigured for API access, please contact the Street Manager service desk.
  3. Organisations who are not a recognised Street Works Authority (do not have a SWA code, Contractor/Vendors etc.) may test using accounts for associated Street Works Authority organisations.
  4. Organisations intending to use only the Street Manager web frontend can leverage SANDBOX environment to test end-to-end permit journeys and familiarise their staff with the service.
  5. API integration developers can leverage the SANDBOX environment to access the latest Swagger documentation for the available API endpoints, as well as test their API clients against the Street Manager API services from their CI integration environment.
  6. Organisations are permitted to leverage SANDBOX for additional assurance activities such as focussed end-user testing, however no form of performance testing is permitted against this environment. Organisations who wish to carry out performance testing must contact the Street Manager project team directly in order to discuss options.
  7. SANDBOX is development-grade, therefore a) is subject to higher-velocity changes and releases; b) is not guaranteed to be highly-available nor highly-performant; c) may be subject to occasional resets of the underlying databases.
  8. Organisations and their users of Street Manager must agree not to submit sensitive nor personally identifiable data into the SANDBOX environment under any circumstances – only use of ‘dummy’ data is permitted.

PRODUCTION environment

API URL: https://api.manage-roadworks.service.gov.uk

  1. The PRODUCTION environment is for LIVE use and LIVE data only – neither functional nor non-functional testing is permitted against the live environment.
  2. Once an organisation has reached production-readiness – and have aligned with their local area ecosystem partners in that production-readiness – the organisations must engage with the Street Manager team to inform them of their production readiness. At this stage the team will work with the organisation to facilitate a transition into the PRODUCTION environment.
  3. In some cases, local area ecosystem alignment may not be possible within reasonable time frames due to external factors. In these cases, dual-keying may be necessary between the organisation, their existing EToN system, and the Street Manager Service.

Connecting to the API services

In order to connect to the Street Manager environments, your API client must be configured to connect to an environment-specific API URL via HTTPS.

It is important to note that the hostname within the URL contains a DNS CNAME. Due to the nature of Street Manager’s highly-available cloud-native design, the underlying IP addresses resolved from this CNAME are subject to change frequently and without notice.

Therefore, if your IT department restrict outbound internet access from your API client to the Street Manager service via a perimeter firewall or some other means, it is important that access to Street Manager is whitelisted on the basis of the DNS CNAME and not the transient underlying IP addresses.

Timing

All Street Manager environments use standard NTP Pool servers to synchronise their system clocks, ensuring they keep accurate and consistent time. Street Manager system time is UTC. Please provide accurate time zone information in API requests, not doing so can cause errors in some time based calculations such as works duration. To learn more about how Street Manager uses time and defines rules like working day, see the Business rules.

Technical Overview

Available APIs

Getting data

Street Manager exposes a number of APIs to allow external applications to retrieve and submit data.

Work API

The Street Manager Work API allows promoters and highway authority users to carry out a number of key workflows relevant to their organization and role. We will cover each in detail but at a high level they are:

Promoter workflows

  1. Submit permit application
  2. Submit forward plan
  3. Carry out a work
  4. Create reinstatement
  5. Action an FPN
  6. Add comments to a works record
  7. Submit a permit alteration (change-request, work extension)

Highway Authority workflows

  1. Assess permit application
  2. Issue an inspection
  3. Schedule reinspections
  4. Issue an FPN
  5. Submit event and highway license activities
  6. Add comments to a works record
  7. Issue a Section 81
  8. Generate Sample Inspections

In order to ensure a user has the appropriate permissions to carry out the above workflows they must authenticate to the API and acquire a JWT to be used as part of their request.

Street Lookup API

The Street Manager Street Lookup API allows querying of NSG and ASD data based on location and USRN. This function is only available as part of submitting a permit for a work. See the resource guide for details.

GeoJson API

The Street Manager GeoJson API exposes works and events spatial data to authenticated users for use with mapping queries. This API returns data in the form of GeoJSON using BNG (British National Grid EPSG:27700) as the Coordinate Reference System, as per Street Works industry standard. See the resource guide for details.

Data Export API

Street Manager supports an API for Open Data users. The Data Export API allows non street works authority users, such as Mobile Application developers, to retrieve information about works. It also allows users of Street Manager to extract data within their organisation from the service in CSV format. See Open Data - Hourly Export and the Resource Guide for details.

Reporting API

The Reporting API allows promoters and highway authority users to carry out a number of data analysis and reporting workflows, allowing them to retrieve data with configurable filtering, sorting and paging. This is the backbone of our dashboard and list functionality. This API should be used as a primary API to retrieve large volumes of data about your works.

Getting data from Street Manager

External systems integrating with Street Manager need to retrieve data from the service to give their users the most up-to-date view on what is going on with their works. Street Manager has a number of ways which you can extract data from the service.

Individual work data

The Work API provides endpoints which give the full detail available for individual Works and Permits. Use these endpoints to retrieve details such as timings, comments, history and changes.

Reporting

You can use the Data Export API to extract data from the service in CSV format. These endpoints allow you to extract most Work information efficiently for your organisation.

Continuous Polling

The Event API exposes a /works/updates endpoint for polling. See the resource guide for full information.

Notifications

Street Manager offers a Notification service which will send Push notifications to organisations for updates to their Works to subscribed systems. Organisations who wish to receive notifications need to expose an HTTPS endpoint capable of receiving POST requests from the Notification service containing the update event data as JSON.

You can find out more about Notifications, including how to access them, on the Open Data Overview page.

Notifications cannot offer guaranteed delivery (network issues, service downtime etc.) so to reconcile for missed Notifications you can use the Polling API endpoint to validate you have received notifications for all updated works.

Contractors

Contractors can use the Data Export API to extract data from the service in CSV format. These endpoints allow you to extract most Work information efficiently for the organisation you are working on behalf of. swa_code parameters are available on the endpoints which can be used by contractors to provide the SWA code of the promoter they are working on behalf of. Additionally, contractors can carry out promoter workflows via the Work API.

Open Data - Hourly Export

Street Manager currently maintains an hourly scheduled job for data exporting. This retrieves activities across all organisations that have been added, changed, or deleted in the past hour, which is then stored in CSV format. This export can be retrieved using the Data Export API. This scheduled job is planned to be decommissioned in favour of the Open Data event notifications described above, however.

For example, a CSV file named Activity_data_export_2020-01-01_13-00.csv will contain activities across all organisations that have been added, changed, or deleted between 2020-01-01T12:00:00.000Z and 2020-01-01T12:59:59.999Z.

Note: The timing in the CSV file names are in British Summer Time (BST), similar to the async data extraction CSV files. So during BST, a CSV file named Activity_data_export_2020-04-15_13-00.csv will contain activities across all organisations that have been added, changed, or deleted between 2020-04-15T11:00:00.000Z (2020-04-15T12:00:00.000+0100) and 2020-04-15T11:59:59.999Z (2020-04-15T12:59:59.999+0100).

Versioning and Release Management

During Public Beta and beyond, the Street Manager services will remain under continual active development. Therefore, a process must be established which allows low-friction development to continue at pace, whilst providing the option for web frontend users and API integrators to focus on a higher-stability version of the services.

This section aims to describe the approach taken by the Street Manager team in order to meet both of those requirements. The approach is based upon existing GDS best practices and will undergo continual refinement over time, based on feedback from the consumers of the service environments as well as observations by the Street Manager project team.

API Versioning Approach

The Street Manager API services are versioned via the URL path, for example api.sandbox.domain.com/v1/work/.../ versus api.sandbox.domain.com/latest/work/.../. The UI will point at the latest version of the code base, while API users will be able to use v1 or latest.

API Versions

  1. V1 (decommissioned on 3rd May 2021)
  2. V2 (decommissioned on 16th May 2022)
  3. V3 (stable - to be decommissioned 24th July 2023)
  4. V4 (stable)

Release Management

Minor version updates will be released to all available versions of Street Manager APIs every two weeks - these updates may include existing feature enhancements, entirely new feature additions, as well as issue hot fixes. Although regular releases will continue throughout Public Beta, the Street Manager development team will strive to minimise the number of breaking changes to stable versions where possible.

It should however be noted that during Public Beta development, there remains the potential that breaking changes may occasionally be required in order to release corrective hot fixes deemed to be service critical. In such situations, the project team will notify potentially affected participant organistations in advance of the release and provide support with a view to minimising disruption.

After an API version is deprecated this will no longer be supported or deployed. This will be communicated in advance to ensure ample notice for integrators to migrate to the new stable version.

The following are examples of what we consider to be breaking and non-breaking changes.

What is a breaking change

  1. Adding new mandatory field to existing endpoint request object
  2. Removing/renaming enum value for field in existing endpoint request object
  3. Adding/renaming enum value for field in existing endpoint response object
  4. Removing/renaming existing field in endpoint response object
  5. Adding new required endpoint to use an existing flow (e.g. submitting a permit)

What is a non-breaking change

  1. Adding a new optional field to existing endpoint request object
  2. Adding new enum values for field in existing endpoint request object
  3. Adding new data to response objects (accepting risk that this breaks some formal contract JSON deserialisers)
  4. Adding a new endpoint to support new functionality or an enhancement to existing functionality
  5. Updating values in non-enumerable fields

Testing

Environments and usage

See the Environments section for details on the environments. If you require non-functional performance or security testing please contact Street Manager support to agree scope, volumes and scheduling beforehand, as this may have an impact on other users and each environment has specific rate limiting and protective controls which may invalidate your tests.

Our recommendation for organisations who want to start testing Street Manager is to get access to the SANDBOX environment and test in collaborative groups that reflect their normal operational area and actions. This allows more realistic test scenarios and will help better understand how other organisations plan to use Street Manager.

This will not always be possible and organisations may need to test using accounts for other organisations in order to test certain scenarios independently (e.g. a Utility company using a HA account to assess a permit they submitted). To enable this we will allow organisations to request accounts for other organisations with some restrictions to prevent conflicts in testing between organisations test data. See below for recommendations per type of organisation for independent testing.

  1. Highway Authorities

    Use self permitting, submitting permits as a HA Planner and assessing permits under your own area.

  2. Promoters

    Request an HA account for a HA which you normally interact with and submit permits using a specific Workstream which identifies your test permits from the HA's own test data. This allows the HA to differentiate between your test data and their own. Use your HA account to respond to your Workstream permits and test your scenarios. You will need permission from the HA to do this and must liaise with the HA to ensure your testing does not interfere with their testing.

    If you can not find an appropriate HA to test with you can request a HA test account for Isles of Scilly HA ("COUNCIL OF THE ISLES OF SCILLY", 835, HJ) via the service desk. This will allow you to independently test scenarios for a limited set of streets.

  3. Contractors

    Request your contractor organisation to be associated with a specific Promoter (or HA acting as Promoter for self permitting) in SANDBOX. Arrange with Promoter to create a Workstream for your test permits. If you need an HA account to assess your test permits you may request an HA account (same as a Promoter, see above).

    If your users operate directly as users for a Promoter, managed by their organisation directly and not as contractors users working for many organisations under single account, you may request users for that Promoter and test under Workstreams based on your normal actions for the Promoter and should liaise with the Promoter during testing.

  4. Vendors/Non-SWA organisations

    If you are not testing for a specific SWA Promoter/HA (e.g. developing API integration for your product) you may request accounts for a Promoter/HA organisation (with their permission) and test using specific Workstreams to isolate your test data from their own.

Reporting issues

In order to correct issues and bugs found in Street Manager we require specific information so we can trace and attempt to reproduce errors.

Details will be provided to you at onboarding regarding how to report issues, the format and information required.

Generating test client and server stubs

It is possible to generate test clients and servers using the available API documentation (Swagger JSON) which can be retrieved directly from the exposed APIs in SANDBOX environments. This allows isolated testing of your integration without dependency on test environments and can speed up development.

Swagger-codegen supports generating client and server stubs for a variety of languages, see here for details. Below is an example of generating Java client and server stubs using the Swagger-codegen utility.

Requires

  1. Java (tested with openjdk version "11.0.1" 2018-10-16)
  2. Maven for build
  3. Swagger Codegen

Client

Generated with command:

swagger-codegen generate -i swagger.json -l java -o ./streetmanager-apiclient-java

The generated code for the template had a number of errors which required manual corrections.

Corrections:

  1. pom.xml - updated 1.7 to 1.8 to support annotations
  2. pom.xml - added dependency javax.annotation to replace deprecated class
  3. Find/Replace body@ApiParam to body,@ApiParam due to template error on generated clients
  4. Find/Replace new BigDecimal() to new BigDecimal(0)due to template error on generated tests

To build:

mvn package

Server

Generated with command:

swagger-codegen generate -i swagger.json -l spring -o ./streetmanager-apistub-java-spring

The generated code for the template had a number of errors which required manual corrections.

Corrections:

  1. pom.xml - updated 1.7 to 1.8 to support annotations
  2. pom.xml - added dependencies for javax.xml.bind to replace deprecated class
  3. Find/Replace body\@ApiParam to body,\@ApiParam due to template error on generated controllers
  4. Find/Replace new BigDecimal() to new BigDecimal(0)due to template error on generated tests To run:

mvn package java -jar target/swagger-spring-1.0.0.jar --server.port=8080

Security

HTTPS

All Street Manager web and API interfaces are secured using Transport Layer Security (TLS) v1.2 certificates issued by Amazon Web Services. These certificates are signed by the ‘Amazon Root CA 1’ certificate as listed in the ‘Certification Authorities’ section of the AWS Chain of Trust document.

When sending requests to the Street Manager APIs the URL must start with https://. Requests sent with http:// will result in an error.

Authentication and Authorisation

All resource endpoints in the API, with the exception of authentication and status, require a JWT to be passed in the 'token' header of the request. The JWT contains information about the user and allows them to access routes, services, and resources that are permitted with that token. Without it the request will be met with a 401 error response.

A systemToken API key is also available on the Party API, this token is for internal use only and is not required for any exposed endpoint.

User accounts and permissions

External systems integrating with Street Manager should use specific credentials setup for API users. This is to allow Street Manager to differentiate between Web UI user accounts and API users. User accounts are assigned specific roles, such as planner and admin.

Each user can perform read operations to every resource, however write operations are restricted based on a user’s role and the organisation they are associated with.

If the organisation the user belongs to is suspended or disabled they will be unable to log in. If they are logged in before the organisation is suspended or disabled then they will receive 401 error responses on read/write operations and will be prevented from logging again. Contractors working on behalf of suspended or disabled organisations will receive 401 error responses on read/write operations for that organisation.

If a user has not logged into Street Manager in more than 6 months their account will be disabled. If a user has been disabled they will be unable to log in and will require an admin to re-invite them to Street Manager.

Note: Currently systems who need to act as users associated with multiple organisations, i.e. submitting permits for multiple utility companies, need to use separate user accounts for each organisation.

The table below shows the current permissions per endpoint.

Work API

Authorisation per endpoint for Work API
Endpoint Roles Organisation Member*
POST /authenticate None Not Required
POST /files Planner, Contractor & Highway Authority Required
DELETE /files/{id} Planner, Contractor & Highway Authority Required
POST /works Planner & Contractor Required
PUT /works/* Planner & Contractor Required
POST /works/{referenceNumber}/comments Planner, Contractor & Highway Authority Required
PUT /works/{referenceNumber}/comments/{commentReferenceNumber}/read Planner, Contractor & Highway Authority Required
POST /works/{referenceNumber}/fixed-penalty-notices Highway Authority Required
PUT /works/{referenceNumber}/fixed-penalty-notices/{fpnReferenceNumber}/status Planner, Contractor & Highway Authority Required
DELETE /works/{work reference number}/fixed-penalty-notices/{FPN reference number} Highway Authority Required
POST /works/{referenceNumber}/inspections Highway Authority Required
PUT /works/{referenceNumber}/inspections/{inspectionReferenceNumber}/withdraw Highway Authority Required
DELETE /works/{referenceNumber}/inspections/{inspectionReferenceNumber} Highway Authority Required
POST /works/{referenceNumber}/scheduled-inspections Highway Authority Required
DELETE /works/{referenceNumber}/scheduled-inspections Highway Authority Required
POST /works/{referenceNumber}/permits/{permitReferenceNumber}/alterations Planner, Contractor & Highway Authority Required
PUT /works/{referenceNumber}/permits/{permitReferenceNumber}/alterations Highway Authority Required
POST /works/{referenceNumber}/permits/{permitReferenceNumber}/alterations/impose Highway Authority Required
POST /works/{referenceNumber}/permits/{permitReferenceNumber}/status Planner, Contractor & Highway Authority Required
POST /works/{referenceNumber}/sites/{siteNumber}/reinstatements Planner & Contractor Required
POST /activity Highway Authority Required
GET /activity/{activityReferenceNumber} Planner, Contractor & Highway Authority Not Required
PUT /activity/{activityReferenceNumber}/cancel Highway Authority Required
POST /forward-plans Planner & Contractor Required
GET /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber} Planner & Contractor Required
PUT /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber} Planner & Contractor Required
PUT /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber}/cancel Planner & Contractor Required
POST /historic-works/fixed-penalty-notices Highway Authority Required
POST /historic-works/inspections Highway Authority Required
POST /non-notifiable-works/sites Planner & Contractor Required
POST /section-81-works/section-81s Highway Authority Required
GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber} Planner, Contractor & Highway Authority Required
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/status Highway Authority Required
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/link-section-81 Highway Authority Required
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/unlink-section-81 Highway Authority Required
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/reassign-section-81 Highway Authority Required
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/hs2_acknowledgement Highway Authority Required
POST /geographical-areas Admin (associated with a Highway Authority), Highway Authority Required
PUT /geographical-areas/{geographicalAreaReferenceNumber} Admin (associated with a Highway Authority), Highway Authority Required
POST /sample-inspection-targets Admin (associated with a Highway Authority), Highway Authority Required
GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber} Admin (associated with a Highway Authority), Highway Authority Required
DELETE /sample-inspection-targets/{sampleInspectionTargetReferenceNumber} Admin (associated with a Highway Authority), Highway Authority Required
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber} Admin (associated with a Highway Authority), Highway Authority Required
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close Admin (associated with a Highway Authority), Highway Authority Required
POST /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close Admin (associated with a Highway Authority), Highway Authority Required
POST /works/${workReferenceNumber}/section-74s Highway Authority Required
GET /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber} Planner, Contractor & Highway Authority (StreetWorksAdmin optional and if included returns additional sensitive financial information) Required
PUT /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}/highway-authority-status Highway Authority Required
PUT /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}/promoter-status Planner or Contractor Required
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-review Planner or Contractor Required
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-non-acceptance-response Highway Authority Required
GET /works/{workReferenceNumber}/earliest-permit Planner, Contractor & Highway Authority Not Required
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-review Planner or Contractor Required
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-non-acceptance-response Highway Authority Required
POST /section-58s Highway Authority Required
GET /section-58s/{section58ReferenceNumber} Planner, Contractor & Highway Authority Not Required
PUT /section-58s/{section58ReferenceNumber}/status Highway Authority Required

Reporting API

Authorisation per endpoint for Reporting API
Endpoint Roles Organisation Member*
GET /* Planner, Contractor & Highway Authority Not Required
GET /sample-inspections Highway Authority Not Required
GET /sample-inspection-targets Admin & Highway Authority Not Required

Street Lookup API

Authorisation per endpoint for Street Lookup API
Endpoint Roles Organisation Member*
GET /* Planner, Contractor & Highway Authority Not Required

Geojson API

Authorisation per endpoint for Geojson API
Endpoint Roles Organisation Member*
GET /* Planner, Contractor & Highway Authority Not Required

Party API

Authorisation per endpoint for Party API
Endpoint Roles Organisation Member*
GET /* Planner, Contractor, Highway Authority & Admin Not Required
POST /logout Planner, Contractor, Highway Authority & Admin Not Required
POST /refresh Planner, Contractor, Highway Authority & Admin Not Required
GET /organisations/{organisationReference} Planner, Contractor, Highway Authority & Admin Not Required
GET /organisations/{organisationReference}/workstreams Planner, Contractor & Admin Required
POST /organisations/{organisationReference}/workstreams Planner & Admin Required
GET /organisations/{organisationReference}/workstreams/{workstreamId} Planner, Contractor, Highway Authority & Admin Not Required
PUT /organisations/{organisationReference}/workstreams/{workstreamPrefix} Planner & Admin Required
GET /users/{email} Planner, Contractor & Admin Not Required

Data Export API

Authorisation per endpoint for Data Export API
Endpoint Roles Organisation Member*
GET /activity-data Planner, Contractor, Highway Authority, DataExport and Admin Not Required
POST /*/csv Planner, Contractor & Highway Authority Not Required
GET /csv/{csvId} Planner, Contractor & Highway Authority Not Required

* An Organisation Member is a user with a SWA code matching the permit’s highway_authority_swa_code or promoter_swa_code. This is enforced in addition to the user’s role.

JWT

Json Web Token (JWT) is an open standard for exchanging information securely. The entities of Street Manager exchange information using JWTs and resources of the Street Manager API require that a JWT ID token be provided as part of the request.

The JWT is validated per service per request. Every service exposed by street manager will attempt to validate the JWT as part of its authentication and authorisation function.

The ID token expires 1 hour after it was generated, if an expired JWT is used in a request, an error with the HTTP status 401 will be returned. In this scenario a new token will need to be generated using the /party/refresh endpoint by supplying a Refresh token.

To invalidate all JWT tokens associated with a user, the Access token should be provided to the /party/logout endpoint.

Resource

POST /authenticate

The authenticate endpoint takes a case sensitive username (email address) and password, returning JWT ID, Access and Refresh tokens if successful. The JWT ID and Access tokens are valid for one hour, meanwhile the Refresh token is valid for 1 day. Once the ID token has been acquired it can be added to all protected resource requests made via swagger using the Authorize button. Users who have had their account disabled will not be able to successfully authenticate. User accounts that have 5 failed login attempts within a 5 minute period will be locked, and will return a 423 status code when attempting to authenticate. Locked accounts are automatically unlocked after 5 minutes. If the organisation the user belongs to is suspended or disabled, then a 412 (Precondition Failed) error will be returned.

Example response:

{
  "idToken": "...", // Token to be included in header for authentication
  "organisationReference": "XXXX", // SWA code or organisation reference for user
  "accessToken": "...", // Token used to logout a user invalidating existing tokens
  "refreshToken": "..." // Token used to re-authenticate a user, has long expiry time
}

authorise

When clicked this will present an input to enter the token. Once authorized then all protected resource requests made via swagger will have the token header set.

available authorisations

If authenticating for the first time with a temporary password, a 307 Temporary Redirect to authenticate/initial will be returned, which can be called with the same request body.

POST /authenticate/initial

After a user has been invited to the system by their organisation admin, they need to set a new password. This endpoint can be called with a new user’s email address and temporary password, and will return a token that should be provided to the Party API /set-password endpoint.

Error responses

It’s important to distinguish between authentication and authorization error responses as it will help narrow down where an issue is occurring.

Authentication Failed

{ "message": "Authentication failed", "error": { "status": 401 } }

Authentication fails when the token provided in the request is invalid. The ID token may have expired or the value set as the token was incorrect. You may also see this error when calling the POST /authenticate endpoint with invalid credentials i.e. wrong username or password.

Access Restricted

{ "message": "Access restricted", "error": { "status": 401 } }

The access restricted error indicates that although the token was valid, the user does not have permissions to perform the desired action. This error could arise for several reasons which will be listed in detail as part of the resource section, but common triggers would be attempting to manipulate entities (permit, reinstatement, inspection etc.) not related to your organization.

Rate limiting

To protect the system from denial of service attacks, repeated calls made in a short period of time from a single IP source will receive 429 status responses. If you are receiving 429 responses ensure you are not sending an excessive number of calls.

Sequencing

As detailed in the Technical Overview section, the Reporting API drives a large amount of data retrieval functionality whilst the Street Manager API drives a lot of key user workflows e.g. submit permit, assess permit, etc. These two APIs together form much of the common sequences a user is likely to perform.

Below is an example of sequence calls used to submit and respond to a permit application as well as how various actions affect the works lifecycle. These endpoints are all available as part of the street manager API and are discussed in more detail within the resource guide.

sequence diagram

The following actions can be performed at any subsequent stage in the sequence from the stage they are available:

  1. File upload
  2. Add a comment
  3. Add reinstatement
  4. Add inspections
  5. Make alteration

Whilst the above focuses much on data manipulation via the Work API, here is an example of some data retrieval calls that may be performed alongside these actions via the Reporting API.

  1. Permits awaiting assessment: GET /permits?status=submitted
  2. Expiring interim reinstatements: GET /reinstatements?status=interim&latest_reinstatements_only=true
  3. Disputed FPNs: GET /fixed-penalty-notices?status=disputed

Understanding the status of a work

As a permit progresses through the sequence above the permit status changes. Knowing the various statuses of a work and a permit allows you to filter lists of permits related to your organisation through the Reporting API.

The statuses of a work are:

  1. planned: The work has not yet started i.e. works start has not been logged
  2. in_progress: The work has been started but not yet completed i.e. works start has been logged but works stop has not
  3. completed: The work has been finished i.e. works stop has been logged
  4. cancelled: The active permit on the work has been cancelled
  5. unattributable: An unattributable work record
  6. historical: The work record was created from a historical inspection or FPN
  7. non_notifiable: The work record was created from a non notifiable reinstatement
  8. section_81: The work record was created from a section 81

The statuses of a permit are:

  1. submitted: The permit is awaiting assessment
  2. granted: The permit has deemed or has been assessed as granted by an HA
  3. permit_modification_request: The permit has been assessed as a permit modification request by an HA, it can still be subsequently assessed as granted/refused by an HA.
  4. refused: The permit has been assessed as refused by an HA
  5. closed: The permit has been stopped by the promoter
  6. cancelled: The permit has been cancelled by the promoter
  7. revoked: The permit has been revoked after it was granted
  8. progressed: The PAA has been progressed to a major permit

Note: PAA/Major submission will be included as part of this sequence.

Viewing works and permits

Work API

When a permit has been submitted and a works record exists both promoters and HAs can view the works record via the GET work endpoint on the work API. This endpoint requires you to provide the work reference number which was supplied during the submission of the permit application.

GET /works/{work reference number}

This contains information about all of the entities associated with the work record, the properties of this response are:

  1. Active permit: The currently active permit associated with the works. In the sequence above this would contain the permit awaiting assessment
  2. Forward plan: Summary of a forward plan if it has been added to the works (none initially)
  3. Sites: Any reinstatement sites that have been added to the works (none initially). This is restricted to the latest 50 sites recorded against the work. The full list can be retrieved using the GET /reinstatements endpoint on Reporting API.
  4. Inspections: Any inspections that have been issued on the works (none initially). This is restricted to the latest 50 inspections recorded against the work. The full list can be retrieved using the GET /inspections endpoint on Reporting API.
  5. FPNs: Any fixed penalty notices that have been issued on the works (none initially). This is restricted to the latest 50 FPNs issued on the work. The full list can be retrieved using the GET /fixed-penalty-notices endpoint on Reporting API.
  6. Permits: Summary of permits that have been associated with that works (i.e. multiple permits). This is restricted to the latest 50 permits on the work. The full list can be retrieved using the GET /permits endpoint on Reporting API.
  7. History: Summary of all history associated with that works
  8. Files: Any files that have been uploaded on the works (none initially)
  9. Section 81: Summary of a Section 81 if it has been added to the works (none initially)
  10. Sample Inspections: Summary of any samples that have been raised against this work (none initially)
  11. Section 74s: Summary of any Section 74s that have been raised against this work (none initially). This is restricted to the latest 50 Section 74s on the work. The full details of a Section 74 can be viewed using the /works​/{workReferenceNumber}​/section-74s​/{section74ReferenceNumber} endpoint on the Work API.

It’s also possible to retrieve only information about the permit itself using the GET permit endpoint. This endpoint requires you to provide the permit reference number which is returned in the response of the permit application submission. As detailed in the submit permit application section of the resource guide, the permit reference number is simply the works reference number suffixed by an incrementing number e.g. {WRN}-01 for the first permit added to that work.

GET /works/{work reference number}/permits/{permit reference number}

This contains information about all of the entities associated with the permit record, it also includes:

  1. Permit alterations: Summary of any permit alterations on the permit. This is restricted to the latest 50 permit alterations recorded against the permit. The full list of permit alterations can be retrieved using the GET /alterations endpoint on Reporting API.
  2. Ancillary informations: Summary of any ancillary informations on the permit. This is restricted to the latest 50 ancillary informations recorded against the permit.

Reporting API

The Reporting API permits endpoint will be the most useful way to see all permits that are relevant to your organisation.

For example, as an HA you can use the status property of a permit indicates the current state it is in, for submitted permits that are awaiting assessment the permit status will be “submitted”.

GET /permits?status=submitted

The status query param can be changed to any of the values discussed above to retrieve permits in any stage of the sequence. This is discussed in more detail in the Reporting API resource guide.

Promoters can use status values to find permits which the HA has responded to, see the Street Manager API resource guide for more details on Permit status values.

Permits

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Approve the permit (Highway Authority): PUT /works/{work reference number}/permits/{permit reference number}/status

permit create and assess diagram

Permit modification requests

HA Officers will have the option to assess permit applications as a permit_modification_request. This means the work can not be started until the HA makes a final assessment, i.e. granted or refused. They can do this at any time, but the promoter will have the option to submit permit alterations in order to address the changes the HA has asked for.

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Modification request (Highway Authority): PUT /works/{work reference number}/permits/{permit reference number}/status

    Via the assessment endpoint, the HA requests changes to the permit.

  3. Create permit alteration (Promoter): POST /works/{work reference number}/permits/{permit reference number}/alterations

    Promoter submits requested changes via change request

  4. Assess the alteration (Highway Authority): PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status

    Once a permit alteration is submitted the Highway Authority can either grant or refuse it.

    Once a permit alteration is granted by a Highway Authority the permit is updated with the altered values.

  5. Approve or reject the permit (Highway Authority): PUT /works/{work reference number}/permits/{permit reference number}/status

    The HA makes a final assessment decision on the permit

permit modification request diagram

Inspections

In order to create an inspection the following steps should be followed:

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Start the work (Planner): PUT /works/{work reference number}/start
  3. Upload supporting evidence (Highway Authority): POST /files

    If supporting evidence is required for an inspection (for example, a photograph of a defect) one or more files can be associated with the inspection as part of the POST request. The file(s) must be uploaded first, the returned file_id submitted in the file_ids array in the inspection request and the inspection_evidence boolean set to true. The maximum amount of files which can be linked to an inspection is 50.

  4. Create an inspection (Highway Authority): POST /works/{work reference number}/inspections

    Once a permit is in the "In Progress" or "Closed" state an inspection can be recorded against it. When recording a Failed inspection it is possible to create a reinspection which will act as a placeholder for a follow up inspection.

    Once an inspection is recorded against a work any previously scheduled reinspections, for that work, will be removed.

    Once an inspection is recorded against a work it cannot be updated.

Inspections sequence diagram

Fixed Penalty Notices

In order to create a fixed penalty notice the following steps should be followed:

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Upload supporting evidence (Highway Authority): POST /files

    If supporting evidence is required for a fixed penalty notice (for example, a photograph of a breach of conditions) one or more files can be associated with the inspection as part of the POST request. The file(s) must be uploaded first, the returned file_id submitted in the file_ids array in the inspection request and the fpn_evidence boolean set to true. The maximum amount of files which can be linked to a fixed penalty notice is 50.

  3. Create a fixed penalty notice (Highway Authority): POST /works/{work reference number}/fixed-penalty-notices

    A fixed penalty notice can be created against a work as soon as it has been created.

  4. Accept a fixed penalty notice (Planner): PUT /works/{work reference number}/fixed-penalty-notices/{fpn reference number}/status

    Optional Step: A promoter can mark the fixed penalty notice as accepted or, alternatively, they can pay it offline.

  5. Dispute a fixed penalty notice (Planner): PUT /works/{work reference number}/fixed-penalty-notices/{fpn reference number}/status

    Optional Step: A promoter can dispute a fixed penalty notice. Once a promoter disputes a fixed penalty notice, they are able to retroactively mark it as accepted, if required.

  6. Set fixed penalty notice outcome (Highway Authority): PUT /works/{work reference number}/fixed-penalty-notices/{fpn reference number}/status

    The Highway Authority issuing the fixed penalty notice is able to record the resolution of the fixed penalty notice. Possible resolution states are: Paid, Paid with Discount or Withdrawn.

FPN sequence diagram

Sites and reinstatements

Reinstatements can be created as part of a non-notifiable work record or a planned work record. Reinstatement and sites have the following types:

  1. excavation
  2. bar_holes
  3. core_holes
  4. pole_testing

The type is only specified when creating a site, any reinstatements created an against existing site will inherit the type from the site they are created against. Excavation sites can only be created for work records which have an active permit which is in-progress or complete and where excavation is set to true in the permit application. A typical flow is as follows:

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application. Excavation will be true when promoter wishes to raise excavation sites

  2. Start the work (Planner): PUT /works/{work reference number}/start
  3. Create a site (Planner): POST /works/{workReferenceNumber}/sites

    Once a permit is in the "In Progress" or "Closed" state a site can be created.

    Once a site is recorded against a work a reinstatement of the same type can be optionally added to the site using POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements

    Once a site/reinstatement is recorded against a work it cannot be updated.

Reinstatement sequence diagram

Permit alterations

Promoter change request

In order to create a promoter change request the following steps should be followed:

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Approve the permit (Highway Authority): PUT /works/{work reference number}/permits/{permit reference number}/status
  3. Request a change (Planner): POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations

    Promoter should submit all fields in the original permit with the changes they require included.

  4. Assess the alteration (Highway Authority): PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status

    Once a permit alteration is submitted the Highway Authority can either grant or refuse it.

    Once a permit alteration is granted by a Highway Authority the permit is updated with the altered values.

Promoter work extension

In order to create a work extension the following steps should be followed:

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Approve the permit (Highway Authority): PUT /works/{work reference number}/permits/{permit reference number}/status
  3. Start the work (Planner): PUT /works/{work reference number}/start
  4. Request a change (Planner): POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations

    Promoter should submit all fields in the original permit containing a change to the proposed_stop_date.

  5. Assess the alteration (Highway Authority): PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status

    Once a permit alteration is submitted the Highway Authority can either grant, grant with duration challenge or refuse it. If the Highway Authority grants with duration challenge they also provide an alternative end_date for the work to be complete.

    Once a permit alteration is granted by a Highway Authority the permit is updated with the altered values.

Highway Authority imposed changed

In order to create a Highway Authority imposed change the following steps should be followed:

  1. Create a work record (Planner): POST /works

    Initially a promoter will create a work, which will, in turn, create a permit application.

  2. Approve the permit (Highway Authority): PUT /works/{work reference number}/permits/{permit reference number}/status
  3. Impose a change (Highway Authority): POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/impose

    Highway Authority can impose changes to the conditions only.

    Once an imposed change is submitted by a Highway Authority the permit is updated with the altered values. No assessment is required.

alteration sequence diagram

Generating Sample Inspections

In order to generate sample inspections the following steps should be followed:

  1. Create sample inspection targets (Highway Authority Admin): POST /sample-inspection-target

    Once targets are agreed with promoter a target should be created against that promoter in Street Manager. Only promoters with an active target are included in sampling.

  2. Request Sample Generation (Highway Authority Admin): POST /sample-inspections

    Samples are generated for each promoter with an active target up to the limits (caps) specified in the target.

  3. Update sample target (Highway Authority Admin): PUT /sample-inspection-target

    After a target is raised, Highway Authority Admins have the option to update the agreed counts and the max number per category to generate

  4. Closing a sample target (Highway Authority Admin): PUT /sample-inspection-target/close

    A Highway Authority may only have one active target per promoter. Targets may be closed to allow a fresh target to be created, for example at the end of a financial year.

sample inspections sequence diagram

Access and Permissions

As discussed in our authentication and authorisation section, all resource endpoints in the API, require a JWT to be passed in the 'token' header of the request. The JWT contains information about the currently authenticated user which is used for more granular level access control as detailed below:

Role Based Access

The following roles can be associated with users:

A user can have multiple roles, but some roles are mutually exclusive in that you may only have one role in the following groups:

So for example it is not possible for Admins to be API users at the same time, or to hold both UI and API access simultaneously.

Role Based Access - Contractor

Many endpoints in our API support the ability to provide a swaCode query param. This is intended for Contractor users to assume the Planner role on behalf of another organisation. When assuming the role of a Planner for another organisation there is validation in place to ensure that the contractor’s organisation is permitted to work for the target organisation. This is controlled by the target organisation’s admin, as they can establish contracting relationships via the front-end application. Please note that currently Street Manager does not support contractors assuming a HighwayAuthority role. This is currently in the road map for future release (post April 2020).

If a valid contract exists for the target organisation then a contractor is bound to the same planner access controls detailed below as regular planners working for that organisation directly.

Role Based Access - Planner

Endpoints which support the Planner role on the API are protected by workstream access. This is admin functionality on the front-end which allows an admin to assign users or contractors working for them the following levels of access for a particular workstream:

The workstream restrictions set by administrators are applied to both UI and API user accounts. no-access users are still permitted to use the GeoJSON & Street Lookup API as well as view specific details of entities returned from those API responses, for example permit details can still be accessed via the work-api but the wider work-record details cannot.

The Reporting and Data Export APIs will automatically filter data in endpoint responses based upon the users allocated workstreams.

Role Based Access - HighwayAuthority

HighwayAuthority users are not restricted to work records based upon workstreams or contract associations. Instead they are only allowed to perform write actions on resources associated with their own organisation. For example they can only assess permits for work records which have been assigned to their own organisation. HighwayAuthority users can instead filter resources using Geographical Areas. For more information see the resource guide

Role Based Access - StreetWorksAdmin

The StreetWorksAdmin role cannot be used by itself, it must be paired with either Admin, Planner, Contractor or Highway Authority. Users who are have been granted the StreetWorksAdmin role are able to access additional sensitive information, for example financial information relating to Section 74s.

The StreetWorksAdmin role is not the same as the Admin role and does not provide access to functionality that is currently exclusive to the Admin role.

While the Admin role on it’s own will not have access to the additional sensitive information provided by the StreetWorksAdmin role via the UI they will be able to access the data via the ‘Download all my data’ functionality.

Default Workstream

A default workstream with the prefix “000” exists for every organisation. This is intended as a holding-place for work records without permits, for example historic works and section 81s are created against the default workstream for the associated promoter’s organisation. When the first permit is created for a work record the promoter will be able to provide the correct workstream for which it should be associated. The default workstream should NOT be provided explicitly in requests when creating permits, this will result in a bad request error. Instead, a workstream for which the user has full-write access to should be provided.

Resource Guide

  1. Reporting API
  2. Work API
  3. Geojson API
  4. Street Lookup API
  5. Party API
  6. Data Export API
  7. Event API
  8. Sampling API

Reporting API

As discussed in the sequencing section, the Reporting API allows promoters and HAs to query resource lists for their organisation, filtering them by various properties. The Reporting API currently allows users to retrieve the following:

  1. Permits
  2. Inspections
  3. Sample Inspections
  4. Comments
  5. Fixed penalty notices
  6. Reinstatements
  7. Expiring Interim Reinstatements
  8. Alterations
  9. Forward plans
  10. Workstreams
  11. Activities
  12. Section 58s
  13. Section 74s
  14. Section 81s
  15. CSV exports
  16. Permits - Duration challenges
  17. Permit Alterations - Duration challenges
  18. PBI Sample Inspection Targets
  19. PBI Sample Inspections

Pagination

Most endpoints on the Reporting API are driven with pagination. This is controlled by the offset query param, which indicates the starting point from which to return data.

Following is a description of the meta-data contained in a paginated response in the Reporting API.

{ "pagination": { "has_next_page": true, "total_rows": "50" }, "rows": [...] }

The has_next_page and total_rows properties indicate if additional pages of results are available to be returned, in the context of the total number of rows (records).

The total_rows property can return a maximum number of 501, if 501 is returned it indicates that there may be more rows available in the database to query. This is confirmed if has_next_page is true, and means that if there are more than 501 rows, and the offset is greater than 501, additional rows will be returned, but the total_rows property will still be limited to 501 rows.

The rows property contains the records for the current page.

By default, there are a maximum of 25 rows returned per page. Therefore, in the example above, if you have 50 items total with 25 items per page, to get the next page of results the offset should be set to 25. The next response would contain rows 26-50.

Organisation specific data

The various resources queryable through the Reporting API are only for the currently authenticated user’s organisation or associated organisation as a contractor.

Get permits

GET /permits

Query params:

  1. status: The permit status i.e. submitted, granted
  2. work_status: The work status i.e. planned, completed
  3. work_category: The work category i.e. minor, standard
  4. lane_rental_assessment_outcome: The outcome of the lane rental assessment (if exists) i.e. chargeable, exempt
  5. sort_column: The property of the permit to order results by
  6. sort_direction: Ascending/descending
  7. start_date: Date range filtering by actual dates if available, otherwise filter permits by proposed dates
  8. end_date: Date range filtering by actual dates if available, otherwise filter permits by proposed dates
  9. work_start_date_from: Date filtering by actual start date if available, otherwise filter permits by proposed start date
  10. work_start_date_to: Date filtering by actual start date if available, otherwise filter permits by proposed start date
  11. work_end_date_from: Date filtering by actual end date if available, otherwise filter permits by proposed end date
  12. work_end_date_to: Date filtering by actual end date if available, otherwise filter permits by proposed end date
  13. start_date_created: Date filtering by permit date created. Filters permits created on or after start_date_created
  14. end_date_created: Date filtering by permit date created. Filters permits created on or before start_date_created
  15. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  16. hs2_works_only: Used only by eligible promoters, HA's and contractors. This will return all HS2 works.
  17. consultation_works_only: Used only by eligible promoters, HA's and contractors. When true, this will return all HS2 consultation works.
  18. consent_works_only: Used only by eligible promoters, HA's and contractors. When true, this will return all HS2 consent works
  19. unacknowledged_by_ha_only: Used only by eligible promoters, HA's and contractors. When true, this will return all HS2 applications that have not yet been acknowledged by a HA.
  20. is_traffic_sensitive: When true this will return permits where a traffic sensitive ASD has been selected
  21. is_high_impact_traffic_management: When true this will return permits with a traffic management type of road closure, contra-flow, lane closure, convoy workings, multi-way signals or two-way signals
  22. has_no_final_registration: When true this will return permits that have not yet submitted their final reinstatement
  23. has_excavation: When true this will return permits that have carried out an excavation
  24. is_early_start: When true this will return permits that have been flagged as an early start
  25. is_deemed: When true this will return permits that have been automatically deemed
  26. lane_rental_charges_not_agreed: When true this will return permits that have a lane rental assessment outcome of "chargeable" and charges have not been agreed
  27. lane_rental_charges_potentially_apply: When true this will return permits that have a lane rental assessment outcome of "chargeable" or "potentially chargeable", or the work is taking place on a lane rental applicable road
  28. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  29. organisation: Name of organisation associated with the permit (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  30. street_descriptor: Search by street, town or area (partial match)
  31. usrn: Search by USRN
  32. permit_reference_number: Search by the reference number of the permit
  33. work_reference_number: Search by the work reference number of the permit

Get inspections

Query params:

  1. inspection_response_type: inspection or reinspection
  2. start_date: The inspection_start_date for inspections and reinspection_date_time for reinspections
  3. end_date: The inspection_start_date for inspections and reinspection_date_time for reinspections
  4. inspection_type: The inspection type i.e. live_site, reinstatement etc.
  5. inspection_outcome: The inspection outcome i.e. passed, failed_low etc.
  6. start_date_created: The date the inspection was created
  7. end_date_created: The date the inspection was created
  8. sort_column: The property of the inspection to order results by
  9. sort_direction: Ascending/descending
  10. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  11. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  12. organisation: Name of organisation associated with the permit (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  13. street_descriptor: Search by street, town or area (partial match)
  14. usrn: Search by USRN
  15. work_reference_number: Search by work reference number (partial match)

Get FPNs

GET /fixed-penalty-notices

Retrieves a list of FPNs that have been added to any works record. The POST works/{workReferenceNumber}/fixed-penalty-notices endpoint which can be used to issue an FPN is part of the Work API. FPNs can be filtered using the query params described below. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

Query params:

  1. status: The FPN status i.e. issued, accepted, disputed
  2. start_date: Date range filtering by the issue_date_time
  3. end_date: Date range filtering by the issue_date_time
  4. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  5. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  6. offence_code: The Offence code i.e. offence_code_05, offence_code_08 etc.
  7. status_changed_date_from: Date range filtering by the status_changed_date
  8. status_changed_date_to: Date range filtering by the status_changed_date
  9. sort_column: The property of the FPN to order results by
  10. sort_direction: Ascending/descending
  11. organisation: Name of organisation associated with the permit (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  12. street_descriptor: Search by street, town or area (partial match)
  13. usrn: Search by USRN
  14. work_reference_number: Search by work reference number (partial match)

Get reinstatements

GET /reinstatements

Retrieves a list of Reinstatements that have been added to any works record. Reinstatements can be filtered by status. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of. The /works/{workReferenceNumber}/sites and POST ​/works​/{workReferenceNumber}​/sites​/{siteNumber}​/reinstatements endpoints to create a sites and reinstatements are part of the Work API. The relationship between a site and a reinstatement is explained in more detail here

Query params:

  1. sort_column: The column of the reinstatement to order results by
  2. sort_direction: Ascending/descending
  3. status: The status of the reinstatement - interim or permanent
  4. offset: The number of results to skip when returning the result set, used for pagination
  5. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  6. latest_reinstatements_only: When true will get the latest reinstatements only
  7. registration_date_from: Date range filtering based on the date_created property
  8. registration_date_to: Date range filtering based on the date_created property
  9. end_date_from: Date range filtering based on the end_date property
  10. end_date_to: Date range filtering based on the end_date property
  11. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  12. organisation: Name of organisation associated with the reinstatement (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  13. street_descriptor: Search by street, town or area (partial match)
  14. usrn: Search by USRN
  15. work_reference_number: Search by work reference number (partial match)
  16. work_reference_number_exact: Search by work reference number (exact match)

Get expiring interim reinstatements

GET /reinstatements/expiring-interims

Retrieves a list of Expiring Interim Reinstatements that have been added to any works record. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of. The /works/{workReferenceNumber}/sites and POST ​/works​/{workReferenceNumber}​/sites​/{siteNumber}​/reinstatements endpoints to create a sites and reinstatements are part of the Work API. The relationship between a site and a reinstatement is explained in more detail here. Note that for expiring interim reinstatements, a static database created using the previous day’s backup is used (as used for DAMD) to retrieve data. This will mean that any updates done in the current working day will not be included.

Query params:

  1. sort_column: The column of the reinstatement to order results by
  2. sort_direction: Ascending/descending
  3. offset: The number of results to skip when returning the result set, used for pagination
  4. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  5. registration_date_from: Date range filtering based on the date_created property
  6. registration_date_to: Date range filtering based on the date_created property
  7. end_date_from: Date range filtering based on the end_date property
  8. end_date_to: Date range filtering based on the end_date property
  9. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  10. organisation: Name of organisation associated with the reinstatement (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  11. street_descriptor: Search by street, town or area (partial match)
  12. usrn: Search by USRN
  13. work_reference_number: Search by work reference number (partial match)
  14. work_reference_number_exact: Search by work reference number (exact match)

Get alterations

GET /alterations

Query params:

  1. alteration_status: The alteration status i.e. submitted, granted
  2. work_status: The work status i.e. planned, completed
  3. work_category: The work category i.e. minor, standard
  4. lane_rental_assessment_outcome: The outcome of the lane rental assessment (if exists) i.e. chargeable, exempt
  5. sort_direction: Ascending/descending
  6. start_date_created: Date range filtering based on the date_created property
  7. end_date_created: Date range filtering based on the date_created property
  8. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  9. is_traffic_sensitive: When true this will return permit alterations where a traffic sensitive ASD has been selected
  10. is_high_impact_traffic_management: When true this will return permit alterations with a traffic management type of road closure, contra-flow, lane closure, convoy workings, multi-way signals or two-way signals
  11. is_duration_extension: When true this will return permit alterations that raised a duration extension
  12. is_early_start: When true this will return permit alterations that have been flagged as an early start
  13. is_deemed: When true this will return permit alterations that have been automatically deemed
  14. lane_rental_charges_not_agreed: When true this will return permit alterations whose associated permit has a lane rental assessment outcome of "chargeable" and charges have not been agreed
  15. lane_rental_charges_potentially_apply: When true this will return permit alterations whose associated permit has a lane rental assessment outcome of "chargeable" or "potentially chargeable", or the work is taking place on a lane rental applicable road
  16. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  17. status_update_date_from: Date range filtering based on the status_update_date property
  18. status_update_date_to: Date range filtering based on the status_update_date property
  19. organisation: Name of organisation associated with the permit alteration (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  20. street_descriptor: Search by street, town or area (partial match)
  21. usrn: Search by USRN
  22. permit_alteration_reference_number: Search by the reference number of the permit

Get forward plans

GET /forward-plans

Query params:

  1. forward_plan_status: The forward plan status i.e. raised, closed
  2. sort_column: The property of the forward plan to order results by
  3. sort_direction: Ascending/descending
  4. proposed_start_date: Date range filtering based on the proposed forward plan dates
  5. proposed_end_date: Date range filtering based on the proposed forward plan dates
  6. work_start_date_from: Date filtering based on the proposed forward plan start date
  7. work_start_date_to: Date filtering based on the proposed forward plan start date
  8. work_end_date_from: Date filtering based on the proposed forward plan end date
  9. work_end_date_to: Date filtering based on the proposed forward plan end date
  10. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  11. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  12. organisation: Name of organisation associated with the forward plan (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  13. street_descriptor: Search by street, town or area (partial match)
  14. usrn: Search by USRN
  15. forward_plan_reference_number: Search by the reference number of the forward plan

Activities

GET /activities

Retrieves a list of Activities. When called by a Highway Authority user, this list will be filtered to include only Activities raised by the authenticated user’s organisation. If called by a Promoter or Contractor user results will not be filtered by organisation. ha_organisation_name has been added to enable Promoter and Contractor users to filter by Highway Authority organisation.

Query params:

  1. ha_organisation_name: Organisation filtering for Promoter and Contractor users. Filter results by the name of the Highway Authority organisation which raised the Activity. This will be ignored if provided by a Highway Authority users. Supports partial matching of organisation names.
  2. activity_activity_type: The Activity Activity Type i.e. skips, scaffolding etc
  3. sort_column: The property used to order results by
  4. sort_direction: Ascending/descending
  5. query: Search field for activity reference number, street information or USRN. Partial matching is supported
  6. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  7. offset: The number of results to skip when returning the result set, used for pagination

Section 58s

GET /section-58s

Retrieves a list of Section 58s. When called by a Highway Authority user, this list will be filtered to include only Section 58s raised by the authenticated user’s organisation. If called by a Promoter or Contractor user results will not be filtered by organisation. ha_organisation_name has been added to enable Promoter and Contractor users to filter by Highway Authority organisation.

Query params:

  1. ha_organisation_name: Organisation filtering for Promoter and Contractor users. Filter results by the name of the Highway Authority organisation which raised the Section 58. This will be ignored if provided by a Highway Authority users. Supports partial matching of organisation names.
  2. start_date_from: Date filtering based on the Section 58 start date
  3. start_date_to: Date filtering based on the Section 58 start date
  4. section_58_status: The Section 58 Status i.e. proposed, in force, cancelled, closed
  5. sort_column: The property used to order results by
  6. sort_direction: Ascending/descending
  7. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  8. offset: The number of results to skip when returning the result set, used for pagination
  9. section_58_reference_number: The work reference filtering based on the Section 58 Reference Number. Partial matching is supported
  10. street_descriptor: Search by street, town or area (partial match)
  11. usrn: Search by USRN

Section 74s

GET /section-74s

Retrieves a list of section 74s which are associated with the authenticated user’s organisation.

Query params:

  1. section_74_ha_status: The Section 74 HA Status i.e. warning issued, resolved
  2. issue_date_from: Date filtering based on the Section 74 issue date
  3. issue_date_to: Date filtering based on the Section 74 issue date
  4. sort_column: The property used to order results by
  5. sort_direction: Ascending/descending
  6. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  7. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  8. offset: The number of results to skip when returning the result set, used for pagination
  9. organisation: Name of organisation associated with the section 74 (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  10. street_descriptor: Search by street, town or area (partial match)
  11. usrn: Search by USRN
  12. section_74_reference_number: Search by the reference number of the section 74

Section 81s

GET /section-81s

Retrieves a list of section 81s which are associated with the authenticated user’s organisation.

Query params:

  1. section_81_status: The Section 81 Status i.e. issued, accepted
  2. section_81_severity: The Section 81 Severity i.e. high, low
  3. sort_column: The property used to order results by
  4. sort_direction: Ascending/descending
  5. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  6. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  7. offset: The number of results to skip when returning the result set, used for pagination
  8. organisation: Name of organisation associated with the section 81 (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
  9. section_81_type: The Section 81 Type i.e. cabinet, marker post
  10. street_descriptor: Search by street, town or area (partial match)
  11. usrn: Search by USRN
  12. section_81_reference_number: Search by the reference number of the section 81

CSV Exports

GET /csv-exports

Retrieves a list of CSV exports which were generated by the authenticated user.

Contractors are able to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

Permits - Duration Challenges

GET /permits/duration-challenges

Retrieves a list of permits which have been duration challenged. Permits can be filtered using the query params described below. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

Query params:

  1. duration_challenge_review_status: The duration challenge review status i.e. duration_challenge_accepted, duration_challenge_not_accepted. A value of no_response will query for duration challenged permits where there is no duration challenge review status.
  2. duration_challenge_non_acceptance_response_status: The duration challenge non-acceptance response status i.e. reasonable_period_end_date_changed, reasonable_period_end_date_not_changed. A value of no_response will query for duration challenged permits where there is no duration challenge non-acceptance response status.
  3. work_status: The status of the work i.e. planned, in_progress
  4. sort_column: The property used to order results by
  5. sort_direction: Ascending/descending
  6. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  7. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  8. offset: The number of results to skip when returning the result set, used for pagination
  9. organisation: Name of organisation associated with the permits (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.

Permit Alterations - Duration Challenges

GET /alterations/duration-challenges

Retrieves a list of permit alterations which have been duration challenged. Permit alterations can be filtered using the query params described below. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

Query params:

  1. duration_challenge_review_status: The duration challenge review status i.e. duration_challenge_accepted, duration_challenge_not_accepted. A value of no_response will query for duration challenged permit alterations where there is no duration challenge review status.
  2. duration_challenge_non_acceptance_response_status: The duration challenge non-acceptance response status i.e. reasonable_period_end_date_changed, reasonable_period_end_date_not_changed. A value of no_response will query for duration challenged permit alterations where there is no duration challenge non-acceptance response status.
  3. work_status: The status of the work i.e. planned, in_progress
  4. sort_column: The property used to order results by
  5. sort_direction: Ascending/descending
  6. swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
  7. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  8. offset: The number of results to skip when returning the result set, used for pagination
  9. organisation: Name of organisation associated with the permit alterations (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.

Get PBI Sample Inspection Targets

GET /pbi-sample-inspection-targets

Retrieves a list of active sample inspection targets associated with the authenticated user’s organisation.

Query params:

  1. offset: The number of results to skip when returning the result set, used for pagination

Get PBI Sample Inspections

GET /pbi-sample-inspections

Retrieves a list of generated sample inspections associated with the authenticated user’s organisation.

Query params:

  1. offset: The number of results to skip when returning the result set, used for pagination
  2. sort_direction: Ascending/descending
  3. geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
  4. organisation: Name of organisation associated with the permit (partial match). This param will match Promoter name.
  5. street_descriptor: Search by street, town or area (partial match)
  6. usrn: Search by USRN
  7. work_reference_number: Search by work reference number (partial match)
  8. swa_code (unused): Not used by this endpoint as it is not accessible by Contractor users.

Work API

Work records and permits

It’s important to clarify the technical relationship between a work and a permit. When creating a permit for the first time, this will in effect create a works record. A work can have multiple permits. You can create a work and a permit at the same time, or you can create a permit against an existing work depending on the work records current status.

There is also a concept of a work record’s active permit, that is simply the most recently added permit on that works record. In essence, a work is a representation of all the permits, reinstatements, FPNs, inspections etc. that have been added to a particular location.

Delegated Users

All POST and PUT endpoints will contain two properties, internal_user_identifier and internal_user_name. These are intended to allow external systems to pass their internal users identifiers to Street Manager so that they are recorded against actions performed via the API (e.g. displaying the internal users name against a Street Manager comment).

Create work endpoint

POST /works

This endpoint takes all the information required to create a permit, as well as some key identification information about the works record as a whole.

If the user supplies a work_reference_number as part of the request body to POST /works then it must only contain alphanumeric characters, dashes (‘-‘ - Unicode number U+002D) and underscores (‘_’ - Unicode number U+005F). If the user does not supply a work_reference_number then it will be auto-generated with the following format:

<2 letter swa_org_prefix><3-letter workstream prefix><8 digit random number>

The generated work_reference_number is returned in the response.

The promoter_swa_code and highway_authority_swa_code are particularly important fields in the request. Currently only a promoter can create a permit and works record so the promoter SWA code provided in the request much match that of the user authenticated to the system. This is determined by the token header of the request, which contains the JWT. In effect this means the promoter can only add a work or permit for their own organisation.

All SWA codes are left-padded to 4 digits, so for example if the SWA code of your promoter organisation is 10, this should be entered as “0010”.

As a promoter, the HA SWA code you choose is the organisation which will be associated with the permit, and thus responsible for assessing the permit. This HA will also be the only organisation able to add inspections or issue FPNs against the work record. Although generally most information in the system is viewable by any organisation, only the HA and promoter responsible for the work can make actions against it.

You may provide a workstream_prefix, which corresponds to the workstream with which you would like to associate the works. A default workstream with prefix “000” exists for every organisation however this is NOT for permit applications. If you do not explicitly provide a workstream_prefix, we will try to find a non-default workstream associated with your organisation that the currently authenticated user has full-write access to. If this is not possible a work will not be creatable. When providing a prefix the workstream_prefix must match the prefix of a workstream associated with the user’s organisation that they have full-write access to. See access and permissions for further information.

NSG related fields are optional. If not provided; street_name, town, area_name and road_category will be inferred from NSG data relating to the provided USRN. Use Street Lookup API endpoint /nsg/streets or /nsg/usrn to lookup this information.

permit_asds for the provided USRN can be found at Street Lookup API endpoint /nsg/usrn

Get private street notice endpoint

GET /works/{workReferenceNumber}/private-street-notices/{privateStreetReferenceNumber}

Retrieves a private street notice matching a work reference number and a private street reference number.

Create permit endpoint

POST /works/{work reference number}/permits

This endpoint is used to add a new permit to an existing works. There are two main journeys that this endpoint can be used for:

Raise an additional permit on a works

A work can have multiple permits associated with it so it possible to add a new permit to an existing works. This endpoint requires some of the same fields as the create work request but much of the information from the first permit will be used as the value for additional permits, and so only a subset of information is required.

It’s not possible to add an additional permit to an existing works, unless the work is in an inactive state. The state of the work is derived by the status of the most recently added permit. So in short, an additional permit can only be added to a work if the most recently added permit on the existing works record has a status of closed, cancelled, refused or revoked.

Get earliest permit endpoint

GET /works/{work reference number}/earliest-permit

Once permits have been created, the summary details of the permit with the earliest actual start date for the work can be retrieved using this GET endpoint.

Progress a forward plan to a PAA or Permit

POST /works/{workReferenceNumber}/permits

When a forward plan is created, a works is created with no permits. In this scenario, this endpoint is used to raise the first permit on the works. This permit will be a PAA or Permit depending on the type of work and the duration. A forward plan with minor or standard duration, or any highway works will progress straight to a permit. A forward plan will progress to a PAA if the duration falls under the major category or if ttro is required. A forward plan will be progressed as a major if the duration is in the major category and the activity type is an optional permit. This endpoint requires some of the same fields as the create forward plan request but much of the information from the forward plan will be used as the value for the PAA/permit, and so only a subset of information is required.

In order to progress a forward plan, the forward plan must have a status of “raised”. Upon successful progression, the forward plan’s status will be updated to “closed”.

Progress a PAA to a Permit

POST /works/{workReferenceNumber}/permits

When a PAA is progressed, a permit will be added to the works. In this scenario, this endpoint is used to raise another permit on the works. This permit will have a work category depending on the type of work and the duration.

Upon successful progression, the PAA’s status will be updated to “progressed”.

Update status endpoint

POST /works/{work reference number}/permits/{permit reference number}/status

The sequence section shows how a permit can be assessed and actioned at various stages by promoters and highway authorities. This endpoint drives all of these functions.

A permit can only be actioned by the promoter and highway authority organisation it is associated with, these are specified when creating the work record.

Update permit current traffic management endpoint

PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/current-traffic-management-type

Once a permit is in progress, the current traffic management type and current traffic management type emergency contact details (name and number) can be updated using this PUT endpoint. Emergency contact details can only be added (and are mandatory) when current traffic management type is of two-way or multi-way signals.

On site (start/stop works)

Once a permit has been submitted, the promoter which raised the permit is able to:

  1. Start a work
  2. Stop a work
  3. Provide inspection units
  4. Update Final site registered

These actions control various stages of the works record life cycle as shown in the sequencing section.

Start work endpoint

PUT /works/{work reference number}/start

When a permit is submitted initially, a proposed start and end date for the work must be provided. The start endpoint is then used to provide the date the work has actually began, and thus officially starting the work.

By setting an actual start date, the active permit’s status will change to in-progress. This allows the promoter to add reinstatements against the works record if an excavation was carried out and it also allows highway authority users to add inspections, which will be covered in separate sections.

Revert start work endpoint

PUT /works/{work reference number}/revert-start

If a permit has been started accidentally, it can be reverted using this endpoint. This will remove the actual start date and change the active permit’s status back to proposed.

Stop work endpoint

PUT /works/{work reference number}/stop

When a permit is submitted initially, a proposed start and end date for the work must be provided. The stop endpoint is then used to provide the date the work has actually ended, and thus officially stopping the work.

A calculation will also take place in the background to determine the inspection units that should be saved for the work. If inspection units are calculated, the work will be updated to reflect the new total. The system will also keep a total of the annual inspection unit for each promoter/HA pairing.

By setting an actual stop date via this endpoint, the active permit’s status will change to closed. It’s still possible to add reinstatements and inspections to closed works as they may be added retrospectively.

Revert stop work endpoint

PUT /works/{work reference number}/revert-stop

If a permit has been stopped accidentally, it can be reverted using this endpoint. This will remove the actual end date and change the active permit’s status back to in-progress.

Any inspection units that were generated by the calculation that took place when the work stop was originally registered will also be reverted to the previous value on both the work record and the annual inspection unit count.

Final reinstatement endpoint

PUT /works/{work reference number}/final-reinstatement

Once a permit is in progress, and an excavation site has been added to the work, a promoter can flag that the final site has been registered for that work. Adding a reinstatement is covered in a separate section.

Reinstatements (Promoter)

As shown in the sequencing section, once a work has been started by the promoter then a promoter can add reinstatements and sites. A promoter can continue to create and view these even after the work has been stopped and completed, as they may need to do this retrospectively.

In a similar vein to the relationship between a works and a permit, it’s important to clarify the technical relationship between a site and a reinstatement. When creating a reinstatement for the first time, this will in effect create a site record. A site can have multiple reinstatement. You can create a site and a reinstatement at the same time, or you can create a reinstatement against an existing site. A site cannot exist without a reinstatement. All reinstatements belonging to a site will be of the same type e.g. excavation

A site is a representation of all the reinstatements carried out at a particular location but the most recently added reinstatement reflects the sites properties.

Create site endpoint

POST /works/{work reference number}/sites

This endpoint takes all the information required to create a reinstatement, a successful request will create a site with an associated reinstatement.

Get site endpoint

GET /works/{work reference number}/sites/{site reference number}

Once a site has been created it can be retrieved using the GET endpoint, passing the site reference number which is returned as part of the create request. The response includes the latest 50 reinstatements on the site.

Create reinstatement endpoint

POST /works/{work reference number}/sites/{site reference number}/reinstatements

A site can have multiple reinstatements associated with it so it is possible to add a new reinstatement to an existing site. This endpoint requires all of the same fields as the create site request.

Delete reinstatement endpoint

DELETE /works/{work reference number}/sites/{site reference number}/reinstatements/{reinstatement reference number}

If a reinstatement is created in error it can be deleted. Any reinstatement relating to a site can be deleted, not just the latest one. If the active reinstatement is deleted the previous (based on created date) will become the active one. If the site has only one reinstatement then the site will also be deleted. Both reinstatement and site deletions are audited and will appear in the work history.

Inspections (HA)

As shown in the sequencing section, once a work has been started then an HA can issue an inspection. Similar to reinstatements, this can be done even after the works has been stopped and completed, in cases where the HA needs to do this retrospectively.

Create inspection endpoint

POST /works/{work reference number}/inspections

Creating an inspection will return a inspection reference number which can be used to retrieve an individual inspection via the GET endpoint provided.

Delete inspection endpoint

DELETE /works/{work reference number}/inspections/{inspection reference number}

If an inspection has been created in error it can be deleted. Any files associated with the inspection will also be deleted. The deletion is audited and will appear in the work history.

Update inspection outcome status endpoint

PUT works/{work reference number}/inspections/{inspection reference number}/status

If an inspection has been failed, a planner or contractor can dispute or accept this outcome. The highway authorithy can then respond and resolve a disputed inspections failed outcome.

Fixed Penalty Notices (HA)

As shown in the sequencing section An HA user can issue a fixed penalty notice (FPN) against the work record at any point in the works life cycle. Promoters can view and dispute the FPN but they cannot issue their own. HA users may upload evidence to support their FPN but the workflow for this is explained in the file upload section.

Create FPN endpoint

POST /works/{work reference number}/fixed-penalty-notices

Creating a FPN will return a FPN reference number which can be used to retrieve the individual FPN via the GET endpoint provided.

Update FPN status endpoint

PUT /works/{work reference number}/fixed-penalty-notices/{FPN reference number}/status

Both a promoter and HA can action FPNs in different ways as shown in the sequencing section. When an FPN is created by the HA it is considered issued. A promoter can accept or dispute FPNs, whilst an HA officer can mark an FPN as withdrawn or paid.

Delete FPN endpoint

DELETE /works/{work reference number}/fixed-penalty-notices/{FPN reference number}

If an FPN has been created in error it can be deleted. Any files associated with the FPN will also be deleted. The deletion is audited and will appear in the work history.

File upload

Several flows discussed in the previous sections allow users to add files as part of their request:

  1. Submit permit application: planners can upload traffic management plans
  2. Add reinstatement: planners can upload evidence of the reinstatement
  3. Issue an inspection: HA users can upload evidence as part of issuing failed inspection
  4. Issue a fixed penalty notice: HA users can upload evidence as part of issuing an FPN
  5. Works record: Both promoters and HA users can upload files to the work record
  6. Add sites and inspections on historic works HA users can upload files when adding sites to a work record
  7. Non notifiable works Both promoters and contractor users can upload files when adding sites to a non notifiable works
  8. Add sites Both promoters and HA users can upload files when add sites to a work record
  9. Issue a Section 81: HA users can upload evidence as part of issuing a Section 81
  10. Issue a Section 74: HA users can upload evidence as part of issuing a Section 74

Uploading a file is achieved through the file upload endpoint. This endpoint is required as part of all the above flows as any files that the user wishes to associate with the above requests must first be uploaded using this endpoint.

Note: The sequence for uploading files may change to allow drafting permits before uploading files.

Upload file endpoint

POST /files

Once a file has been uploaded the response will contain a file ID. This is the unique identifier of the file in our system. Behind the scenes the file will be uploaded to S3 and virus scanned. This file ID can then be provided in the requests of the flows discussed above. Once a valid file ID is provided in the requests of the above flows, the file is then associated with the relevant entity.

One file can be uploaded at a time. A maximum of 50 files can be associated with an entity, as described above. A single file cannot exceed 10MB.

The optional swaCode parameter is required for contractor users only. Contractors should provide the swaCode of the organisation they are working on behalf of.

Get file endpoint

GET /files/{file ID}

Retrieves the file using the file ID.

As the file is virus scanned at the point of upload, it is not immediately available for retrieval. It’s possible that this endpoint could return a file not found error response if the file has not yet been virus scanned and marked as safe or if the file was deemed unsafe and removed from the system.

Typically the virus scanning process will only take a few seconds.

Delete file endpoint

DELETE /files/{file ID}

Deletes a file from the system. Users can only delete files which their organisation uploaded. You cannot remove a file that’s been linked to an entity. For example as soon as the file id is used as part of a create request for permits/reinstatements/FPNs/inspections etc. or the file was uploaded against a work reference number it is considered linked to that entity.

History

GET /works/{work reference number}/history

The history endpoint returns audit events associated with that works record such as when a permit is assessed, a comment is added etc.

Audit events in the history response will include a topic property to indicate what type of object triggered this audit. The topic property may contain one of following:

  1. Application: A permit action prior to assessment
  2. Permit: A permit action once it has been granted
  3. PAA: A permit action when it has a work_category of paa
  4. ChangeRequest: A permit alteration action
  5. FPN: A fixed penalty notice action
  6. Reinstatement: A site or reinstatement action
  7. Inspection: An inspection action
  8. ScheduledInspection: A scheduled inspection action
  9. Work: A work record action i.e. uploading a file
  10. ForwardPlan: A forward plan action
  11. Comment: Logging a comment
  12. Section81: A section 81 action

Note that the topic property is subject to change. A more reliable option is the event enum property that details what specific action trigger the audit. See the AuditEvent enum in the Work API Swagger definition for a full list of possible events in Street Manager.

Audit events in the history response will also include an object_reference. Where further information is required about what has changed this object_reference can be used to find more details on the object.

  1. Logging an Inspections: Inspection Reference Number
  2. Applying for a Permit: Permit Reference Number
  3. HA granting a permit application: Permit Reference Number
  4. Permit application deeming: Permit Reference Number
  5. Requesting a change: Change Request Reference Number
  6. Creating a site or reinstatement: Reinstatement Reference Number
  7. Raising a FPN: FPN Reference Number
  8. Adding or removing a File to a work record: File ID
  9. Updating on site details of a work: Permit Reference Number

As well as viewing comments on a work record level, you can also call the Reporting API comments endpoint to retrieve all comments associated with your users organization. See the Reporting API section of the resource guide.

Permit Alterations

Permit alterations allows promoters and HA users the ability to alter a permit once it’s been created. Not all properties of a permit are changeable and thus depending on what’s been changed and by who, the type of permit alterations are:

  1. Promoter change request: Promoter submitted alteration after permit has been granted or in-progress
  2. Promoter imposed change: Promoter submitted alteration before permit has been granted or in response to a permit modification request.
  3. Work extension: Promoter submitted proposed end date alteration to in-progress work
  4. HA imposed change: HA users impose changes to permit conditions after permit is granted or in-progress
  5. HA change request: Currently in the road map for future release (post April 2020)
  6. Duration challenge: A work extension which has been challenged by the HA with a reasonable_period_end_date

Creating an alteration will return a alteration reference number which can be used to retrieve an individual alteration via the GET endpoint provided.

While HA imposed changes are applied to the permit automatically, promoter change requests need to be granted (or deemed) before the changes are applied to the target permit.

Create alteration endpoint

POST /works/{work reference number}/permits/{permit reference number}/alterations

Creates a permit alteration. The model takes all editable fields on the permit. When a promoter uses this endpoint, the alteration will have an AlterationType of PROMOTER_CHANGE_REQUEST in the case that they do not extend the end date of the permit while it in in progress, or WORK_EXTENSION in the case that they do. Once the alteration is create it is required to be assessed by the associated HA.

Impose change endpoint

POST /works/{work reference number}/permits/{permit reference number}/alterations/impose

This endpoint allows HA users to impose changes to permit conditions. The AlterationType in this case will be HA_IMPOSED_CHANGE. When an HA imposes a change that change is automatically applied to the permit. It will continue to have a status of Submitted but the permit will reflect the changes submitted.

Update alteration status endpoint

PUT /works/{work reference number}/permits/{permit reference number}/alterations/{permit alteration reference number}/status

The sequence section shows how an alteration can be assessed and actioned at various stages by promoters and highway authorities. This endpoint drives all of these functions. Work extensions or alterations that have changed the reasonable period end date can be duration challenged by highway authorities.

Get alteration endpoint

GET /works/{work reference number}/permits/{permit reference number}/alterations/{permit alteration reference number}

This alteration endpoint returns both the original and the proposed changes of a permit in addition to the reason for the alteration, assessment information and other information relevant to the alteration.

Permit Discount

PUT /works/{work reference number}/permits/{permit reference number}/permit-discount

This alteration endpoint allows a HA to amend permit discounts applied and reason after assessment.

Acknowledge HS2 applications endpoint

PUT /works/{work reference number}/permits/{permit reference number}/hs2_acknowledgement

This endpoint allows HAs to acknowledge a HS2 consultation application.

Events and Activities

POST /activity

GET /activity/{activity reference number}

PUT /activity/{activity reference number}/cancel

Events or Activities allow a HA to represent different activities within Street Manager. There are 9 activity types currently supported by Street Manager:

  1. Skips
  2. Scaffolding
  3. Hoarding
  4. Crane Mobile Platform
  5. Event
  6. Section 50
  7. Section 58
  8. Compound
  9. Other

Creating an activity using the POST endpoint will return an activity reference number which can be used to retrieve an individual activity via the GET endpoint provided

Activities can be flagged as being cancelled by HA which initially raised the activity. The activity reference number is required. Optionally a reason for cancelling the activity can be provided. Activities are cancelled via the PUT endpoint provided.

Forward Plans

POST /forward-plans

GET /works/{work reference number}/forward-plans/{forward plan reference number}

PUT /works/{work reference number}/forward-plans/{forward plan reference number}

PUT /works/{work reference number}/forward-plans/{forward plan reference number}/cancel

Forward plans allow a Planner to supply information about road or street works in their long term programme, which may include those works in their annual operating programme, or three or five year rolling programmes. Giving advance notice with a forward plan helps with collaboration of works.

The POST endpoint will create a forward plan and return a work reference number and a forward plan reference number, which can be used to retrieve an individual forward plan via the GET endpoint provided.

The GET endpoint will require the work reference number and forward plan reference number of the intended forward plan to return information.

There are two PUT endpoints, one to update and one to cancel the forward plan.

The first PUT endpoint will update a forward plan and will require a work reference number, forward plan reference number and a minimum of the mandatory information that you wish to update.

The second PUT endpoint (labeled ‘cancel’) will cancel the forward plan, and subsequently, the work it supersedes. This will require a work reference number, forward plan reference number and a cancellation reason.

There is no versioning available when updating information, so information changed is lost.

Section 81s

POST /section-81-works/section-81s

GET /works/{work reference number}/section-81s/{section 81 reference number}

PUT /works/{work reference number}/section-81s/{section 81 reference number}/status

S81 is a part of NRSWA that details the need for works promoters to maintain and inspect their assets within the highway. A failure in these assets is commonly known as a S81 failure and could include covers that are broken.

The POST endpoint will create a section 81 or Unattributed works and return a work reference number and a section 81 reference number. The section_81_severity and made_safe_by_ha properties are not required for Unattributed works.

The GET endpoint will require the work reference number and section 81 reference number of the intended section 81 or Unattributed works to return information. The section_81_severity and made_safe_by_ha properties are not returned for Unattributed works.

The PUT endpoint will update the status of a section 81 or Unattributed works and will require a work reference number, section 81 reference number and optionally a promoter response or work type depending on the desired status outcome.

Geographical Areas

POST /geographical-areas

PUT /geographical-areas/{geographicalAreaReferenceNumber}

Geographical Areas allow Admins of a Highway Authority organisation to divide works and records geographically for HA users (such as permit officers or inspectors). Organisations can have a maximum of 100 Geographical Areas.

The POST endpoint accepts a CSV file of USRNs and will create a Geographical Area containing those USRNs.

The PUT endpoint accepts a CSV file of USRNs and will update the Geographical Area specified by the Geographical Area Reference number in the request, with the USRNs in the file.

The file must:

  1. Be a valid .csv file type
  2. Contain max 10,000 USRNs
  3. Contain a single column of USRNs (without a heading)
  4. Contain unique USRNs
  5. Contain valid USRNs

Section 58s

POST /section-58s

GET /section-58s/{section58ReferenceNumber}

PUT /section-58s/{section58ReferenceNumber}/status

The POST endpoint will create a section 58 and return a section 58 reference number.

The GET endpoint will require the section 58 reference number of the intended section 58 to return information.

The PUT /status endpoint will allow the issuing Highway Authority to update the status of the Section 58. When a Highway Authority user creates a Section 58 it is considered proposed. Users of the issuing organisation with the Highway Authority role are then able to progress the Section 58 to in_force or to cancel it. The available statuses are -

  1. proposed
  2. in_force
  3. cancelled
  4. closed

Section 74s

POST /works/${work reference number}/section-74s

GET /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}

PUT /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}/highway-authority-status

PUT /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}/promoter-status

The POST endpoint will allow a Highway Authority user to create a section 74 Overrun warning for a permit under the work reference number provided in the url parameter. The permit_reference_number is specified in the request body. There can only be one Section 74 issued against a permit. If one is raised in error, marking it as cancelled will allow a new Section 74 to be raised. This endpoint will return the section 74 reference number.

The GET endpoint requires the work reference number and section 74 reference number to be specified. The information which will be returned as part of this endpoint depends on the current ha and promoter status. Only fields which are relevant to the current status will be returned. Some fields will contain sensitive financial information, these will be excluded from the response if the user does not have the StreetWorksAdmin role.

The table below outlines some of the fields that users with a StreetWorksAdmin role can see. Note that some fields will be returned for Promoters and HAs but only mentioned once below. For example draft_invoice_amount will be returned for users with a StreetWorksAdmin role when the promoter status is changes_agreed, acknowledged_draft_invoice and charges_under_review because the HA status will have been set as draft_invoice_issued.

HA Statuses
Status Status specific fields for all users Status specific fields for only StreetWorkAdmins UI value
warning_issued ~ ~ Warning Issued
warning_disputed ha_reason_for_dispute ~ Warning Disputed
charges_ended site_cleared_date and latest_ha_additional_details ~ Site clear
withdrawn ~ latest_ha_additional_details Withdrawn
draft_invoice_issued ~ draft_invoice_reference, draft_invoice_amount, ha_response_number_of_days_overrun, latest_ha_additional_details Draft invoice issued
resolved ~ invoice_reference, draft_invoice_amount, final_agreed_amount, ha_response_number_of_days_overrun and latest_ha_additional_details Resolved
Promoter Statuses
Status Status specific fields for all users Status specific fields for only StreetWorkAdmins UI value
acknowledge_overrun_warning latest_promoter_additional_details ~ Warning received
site_visited_and_rectified site_visited_date, latest_promoter_additional_details ~ Site visited works closed
warning_disputed promoter_reason_for_dispute ~ Warning disputed
acknowledge_draft_invoice ~ latest_promoter_additional_details Received draft invoice
charge_under_review ~ latest_promoter_additional_details Reviewing draft invoice
charges_agreed ~ latest_promoter_additional_details Reviewing draft invoice

The PUT /highway-authority-status endpoint will allow the issuing Highway Authority to update the status of the Section 74. When a Highway Authority user creates a Section 74 it is considered issued. Users of the issuing organisation with the Highway Authority role are then able to progress the Section 74 by providing the information required at each stage. While the promoter is also able to update the status of the Section 74, this is not required. Highway Authority users can progress through each of the status options without any promoter interaction with Street Manager. The available statuses are -

  1. warning_issued
  2. charges_ended
  3. warning_disputed
  4. withdrawn
  5. draft_invoice_issued
  6. resolved

The PUT /promoter-status endpoint will allow the Planner to update the status of the Section 74. The available statuses are -

  1. acknowledge_overrun_warning
  2. site_visited_and_rectified
  3. acknowledge_draft_invoice
  4. charge_under_review
  5. charge_agreed
  6. warning_disputed

Duration challenge non acceptance

The PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-review endpoint will allow the Planner to accept or not accept a duration challenge on a change request; if the Planner does not accept the duration challenge, a reason must be given. Relevant fields are returned in the PermitAlterationResponse.

The PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-non-acceptance-response endpoint will allow the Highway Authority user to respond to a duration challenge review requested by a promoter. The Highway Authority can choose to update the reasonable period end date, or to keep the date as submitted when providing the original duration challenge details. Relevant fields are returned in the PermitAlterationResponse.

The PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-review endpoint will allow the Planner to accept or not accept a duration challenge on an immediate permit; if the Planner does not accept the duration challenge, a reason must be given. Relevant fields are returned in the PermitResponse.

The PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-non-acceptance-response endpoint will allow the Highway Authority user to respond to a duration challenge on an immediate permit requested by a promoter. The Highway Authority can choose to update the reasonable period end date, or to keep the date as submitted when providing the original duration challenge details. Relevant fields are returned in the PermitResponse.

Fee Matrix

The GET fee-matrix/{organisationReference} endpoint will allow any authenticated user to return the fee matrix values for a provided Highway Authority SWA code, provided that the given HA has populated their fee matrix with values.

Ancillary Information

The POST works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations endpoint will allow a Planner or Contractor to add an Ancillary Information to a permit. The data in a Ancillary Information request include:

  1. location_description
  2. ancillary_info_description
  3. ancillary_info_coordinates
  4. usrns
  5. ancillary_info_type

There is a limit of 20 Ancillary Informations per permit. Within an Ancillary Information there is a limit of 10 coordinates and 25 USRNs per Ancillary Information.

The PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations/{ancillaryInformationReferenceNumber}/remove endpoint will allow a Planner or Contractor to mark Ancillary Information as removed.

The GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations/{ancillaryInformationReferenceNumber} endpoint will allow a Planner, Contractor or Highway Authority to get all the relevant data for a single Ancillary Information.

Non-compliance

This section denotes changes across the application for the upcoming non-compliance functionality, expected to be released by September 2024. Functionality described here will not be available until the full release of non-compliance.

POST /works/{workReferenceNumber}/inspections

When an inspection is created via this endpoint where it has an inspection_type of reinstatement or non_compliance_follow_up, and an inspection_outcome of failed_high or failed_low, a new non-compliance will be automatically created in the background and linked to the newly created inspection.

If a non_compliance_reference_number is provided as part of the request, and it has an inspection_type of reinstatement or non_compliance_follow_up, the newly created inspection will be linked to the non-compliance matching the reference number provided. The non-compliance reference number must refer to a non-compliance with a status of issued and be linked to the same work the inspection is being created under. If a failed inspection is created, details on the non-compliance will be reset. If a passed follow up completion inspection is created, the non-compliance will be marked as resolved. If an unable to complete inspection is created, the inspection will be linked to the non-compliance but no changes will be made to the non-compliance.

GET works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber}

This endpoint will allow a Planner, Contractor or Highway Authority user to get all the relevant data for a single non-compliance.

POST /works/{workReferenceNumber}/permits

If a non_compliance_reference_number is provided as part of the request, and the non-compliance has not been resolved, then the newly created permit will be linked to the non-compliance matching the reference number provided. The non-compliance reference number must refer to a non-compliance with a status of issued and be linked to the same work the permit is being created under.

GeoJSON API

This API returns data in the form of GeoJSON using BNG (British National Grid EPSG:27700) as the Coordinate Reference System, as per Street Works industry standard.

Get works endpoint

GET /works

This endpoint takes min and max easting and northing values to select all works within a bounding box. The works selected can be optionally filtered using the start and end date params.

Get activities endpoint

GET /activities

This endpoint takes min and max easting and northing values to select all activities within a bounding box. The activities selected can be optionally filtered using the start and end date params.

Get forward plans endpoint

GET /forward-plans

This endpoint takes min and max easting and northing values to select all raised forward plans within a bounding box. The forward plans selected can be optionally filtered using the start and end date params.

Get HS2 Act Limits endpoint

GET /hs2-act-limits

This endpoint takes min and max easting and northing values to select all HS2 act limits within a bounding box.

Get Section 58s endpoint

GET /section-58s

This endpoint takes min and max easting and northing values to select all proposed and in-force Section 58s within a bounding box. Start and end date filters can also be provided.

Get Ancillary Informations endpoint

GET /ancillary-informations

This endpoint takes min and max easting and northing values to select all added Ancillary Informations within a bounding box. Start and end date filters can also be provided.

Street Lookup API

The Street Lookup API provides a means of querying the NSG dataset. The endpoints described below return a filtered, formatted subset of the data available within the NSG dataset.

USRNs which are marked as Closed (street state 4) or Addressing Purposes Only (street state 5) are excluded from results. Street Manager also filters results based on the reinstatement type code, as described below.

Reinstatement type codes

Below is a list of Reinstatement type codes currently supported by Street Manager, these codes correspond to the reinstatement_type_codes found in the NSG specification:

  1. 0 - This is currently mapped to reinstatement type code 5 for backward compatibility purposes, but this will be removed in a future version of Street Manager so we recommend providing reinstatement type code 5 (see below)
  2. 1 - Carriageway type 1 (10 to 30 MSA)
  3. 2 - Carriageway type 2 (2.5 to 10 MSA)
  4. 3 - Carriageway type 3 (0.5 to 2.5 MSA)
  5. 4 - Carriageway type 4 (up to 0.5 MSA)
  6. 5 - Carriageway type 0 (30 to 125 MSA)
  7. 6 - High Duty Footway
  8. 7 - High Amenity Footway
  9. 8 - Other Footways
  10. 9 - Private Street – No definition information held by Street Authority
  11. 10 - Carriageway type 6 (over 125 MSA)

The remaining reinstatement type codes (11 - Street maintained by another Highway Authority and 12 Street outside scope of EToN) are not supported by Street Manager. USRNs with these codes are not returned by the endpoints below.

Get streets endpoint (coordinates)

POST /nsg/streets/search

Returns NSG data within 25 meters of each coordinate pair point provided. The information returned can be used to populate a PermitCreateRequest or a WorkCreateRequest. The additional_special_designations_response property values are returned in the format defined by the NSG specification.

Get streets endpoint (USRN)

GET /nsg/streets/{usrn}

Returns NSG data based on a USRN. The information returned can be used to populate a PermitCreateRequest or a WorkCreateRequest. The additional_special_designations_response property values are returned in the format defined by the NSG specification.

Get nsg search (Available in public beta)

GET /nsg/search

Returns street data based on a query search across the NSG street_descriptor, locality_name, town_name and administrative_area.

Party API

Get user

GET /users/{username}

Returns the UserResponse associated with the base 64 encoded username provided. An optional swaCode query param can be provided by contractors to see the associated workstreams available to them for a particular organisation.

Get workstream

GET /organisations/{organisationReference}/workstreams/{workstreamId}

Returns the WorkstreamResponse associated with the organisation and workstream provided.

Get workstreams

GET /organisations/{organisationReference}/workstreams

Returns all workstreams associated with the organisation provided.

Post workstreams

POST /organisations/{organisationReference}/workstreams

Creates a new workstream associated with the organisation provided.

Put workstream

PUT /organisations/{organisationReference}/workstreams/{workstreamPrefix}

Updates the workstream details associated with the organisation and workstream provided.

Get organisation

GET /organisations

Returns a list of OrganisationSummaryResponses. Optionally these can be filtered using the query params type: Filter by organisation type. Available values include PROMOTER, HA and CONTRACTOR query: Filter by organisation name. This will perform a partial search on the organisations name.

GET /organisations/{organisationReference}

Returns the OrganisationResponse associated with the organisation provided.

Refresh tokens

POST /refresh

Accepts the user’s Refresh JWT token and returns new ID and Access JWT tokens that are valid for 1 hour.

Logout

POST /logout

Accepts the user’s Access JWT token and invalidates all JWTs associated with a user.

Forgot Password

POST /forgot-password

Accepts the user’s email address. An email will be sent to this address with a verification code, if a user with the address exists in Street Manager. This will only work if the user has activated their account by using the POST /set-password endpoint.

Reset Forgotten Password

POST /reset-password

Accepts the user’s email address, verification code and the new password. The verification code can be found in the email that was sent following a POST to /forgot-password.

Set password

POST /set-password

Accepts the user’s email address, new password and token (returned from the Work API /authenticate/initial endpoint). This will overwrite the temporary password received by email and activate the user’s account. The response will include the same authentication tokens returned from the Work API /authenticate endpoint.

Data Export API

Get Data CSV

GET /activity-data

Retrieves data of activities across all organisations which have been added, changed, or deleted within the last hour in CSV format. See Data Export API and Open Data in the Technical Overview section for details.

An optional csvExportDate query parameter can be provided to retrieve a CSV (within the last two weeks) that was available for download at the datetime provided. csvExportDate should be an ISO 8601 Date and time format. If no datetime is provided, the current datetime is used as the default (which will retrieve the latest generated CSV).

Note: If the datetime now, for example, is 2020-01-01T15:00:00Z, and a csvExportDate of 2020-01-01T15:00:00Z is provided, the generated CSV at 2020-01-01T14:00:00Z will most likely be retrieved.

This is due to the time it takes for the scheduled job to process and upload the CSV data. So the value of the csvExportDate query parameter should be more specific to ensure the correct CSV is retrieved (e.g., 2020-01-01T15:05:00Z).

In the response, the Content-Disposition HTTP header will contain the name of the CSV file retrieved, which contains the file period information.

Generate Section 58s CSV

POST /section-58s/csv

Generates a CSV list of Section 58s which, if logged in as a Highway Authority, are associated with the authenticated user’s organisation. Otherwise, all Section 58s will be returned.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Section 74s CSV

POST /section-74s/csv

Generates a CSV list of Section 74s which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Section 81s CSV

POST /section-81s/csv

Generates a CSV list of Section 81s which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Reinstatements CSV

POST /reinstatements/csv

Generates a CSV list of reinstatements which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Expiring Interim Reinstatements CSV

POST /reinstatements/expiring-interims/csv

Generates a CSV list of expiring interim reinstatements which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate FPNs CSV

POST /fixed-penalty-notices/csv

Generates a CSV list of FPNs which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Fees CSV

POST /fees/csv

Generates a CSV list of fees which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Chargeable activities include:

  1. Granting of a permit application
  2. PAA progressed to PA - note, this occurs when a PA is received, not when it’s granted
  3. Granting of a change request
  4. Change in work category

Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

Users can also provide the parameters fee_report_format and swa_code_filter to get a fee report for a specific organisation. Setting fee_report_format to single_org_one_csv and providing the organisation reference in the swa_code_filter will generate a single fees CSV for a specific organisation. Setting fee_report-format to all_orgs_multiple_csvs will generate a ZIP file containing a CSV for each of the organisations contained in the report.

Generate Permits CSV

POST /permits/csv

Generates a CSV list of permits which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Inspections CSV

POST /inspections/csv

Generates a CSV list of inspections which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Forward Plans CSV

POST /forward-plans/csv

Generates a CSV list of forward plans which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Alterations CSV

POST /alterations/csv

Generates a CSV list of alterations which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate Comments CSV

POST /comments/csv

Generates a CSV list of comments which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Generate PBI Sample Inspections Due CSV

POST /pbi-sample-inspections-due/csv

Generates a CSV list of PBI sample inspections due which are associated with the authenticated user’s organisation.

A csv_id is returned in the Response body. This csv_id can be used with the GET /csv/{csvId} endpoint to retrieve the CSV after generation.

Get Generated CSV

GET /csv/{csvId}

Returns a CSV generated by one of the POST /{entity}/csv endpoints listed above.

Any values within the CSV which could potentially contain formulas will have been prepended with a single quote character '. This includes values beginning with = + - @ \t \r or including a comma , or semi-colon ; followed by any of = + - @ \t \r.

Event API

Pagination

The polling endpoint on the Event API is driven by cursor-based pagination. This can be controlled by the update_id query param.

{ "rows": [...], "next_update": 1234 }

A next_update property is returned which indicates the ID of the next item that is available to be returned. If there are no more results available to returned, then null is returned.

100 results will be returned by default. A maximum of 250 results can be requested by supplying the required page size in the page_size field.

Polling

GET /works/updates

Retrieves a list of works which have had changes within a defined time period. This allows external integrators to provide a start and end date to poll Street Manager for changes and use the results to retrieve further information from the Works or Reporting API.

In order to retrieve all updates since last usage, the start date could be set to the last date and time the user called the endpoint. Alternatively the user could provide the event date returned in the last entry of a previous result set.

The list of updates can be refined by populating the optional update_id field. When this is populated, only results with update ids above the given id will be returned. As an alternative to providing a defined time period, update_id can be populated without providing a start and end date.

By default 100 results will be returned per request, a maximum of 250 results can be requested by supplying the required page size in the page_size field. If additional results exist the next_update property will be populated with the update_id of the next result allowing for further queries on the remaining results.

Updates for a particular user can be excluded by populating the optional exclude_events_from field with their username.

Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

API Notifications

POST /api-notifications/subscribe

This endpoint will allow users to create a subscription to be notified about events regarding their organisation. Supply your endpoint as an authenticated user in the organisation you want to subscribe to. Subscriptions are limited to one per organisation. Contractors will be subscribed to all the organisations that they are contracting for. Make sure to confirm the endpoint for notifications within 48 hours and do not unsubscribe unless you have confirmed a subscription. If you do not confirm, you will get stuck receiving notifications and will be unable to change/update your subscription.

POST /api-notifications/unsubscribe

This endpoint will allow users to remove a subscription to no longer be notified about events regarding their organisation. Contractors will be unsubscribed from all the organisations that they were contracting for.

Sampling API

More usable endpoints will be added in upcoming releases.

GET /sample-inspection-quota

This endpoint will be used by HA users to calculate the maximum number of samples that can be completed per quarter based on previous number of inspections units and inspection rate.

The request body will take a list of inspection_units, requiring a minimum of 1 and maximum of 3, and an inspection_rate between 20 and 100. The response will return a quota which represents the maximum number of samples that could be completed in a quarter by taking an average of the inspection units, taking the percentage of the inspection rate and dividing that across 4 quarters.

POST /sample-inspection-targets

This endpoint will be used by HA users to create sample inspection targets for promoters.

Users must provide either a baseline estimate of inspection units for the given promoter, or the last two years of inspection units, if three previous years of inspection units do not exist on the system. The last three years of inspection units can be provided after 1st April 2024. The initial target for a promoter must have an inspection rate of either 30 or 50. If not the first quarter, the inspection rate must be the same as last quarter or increased/decreased by 5. If the target is not in the first quarter, the inspection rate must be the same as last quarter or increased/decreased by 5. If the last quarter the promoter was sampled in is more than 3 years in the past the inspection rate must be 30. The targets must be at least 5% of the calculated quarterly quota, unless quota less than 20 in which case can be zero or greater. The sum of the targets that the user provides must not exceed the calculated quarterly quota.

POST /sample-inspections

This endpoint will be used by HA users to begin the sample inspection generation process based on their targets. A job will be started in the background to generate sample inspections.

DELETE /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}

This endpoint will be used by HA users to remove promoters from sample inspection targets. This can happen when there is currently no active quarter or before progress has occurred for that promoter on an active quarter

The request body will take a promoter_org_ref and return a success/failure status code.

PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}

This endpoint will be used by HA users to edit targets for a specific promoter. A active target can only be updated before any sample inspections are completed against that target.

Users must provide either a baseline estimate of inspection units for the given promoter, or the last two years of inspection units, if three previous years of inspection units do not exist on the system. The last three years of inspection units can be provided after 1st April 2024. The initial target for a promoter must have an inspection rate of either 30 or 50. If not the first quarter, the inspection rate must be the same as last quarter or increased by 5. It may be decreased in 5% increments, with a lower limit of 20%. If the target is not in the first quarter, the inspection rate must be the same as last quarter or increased by 5. It also may be decreased in 5% increments, with a lower limit of 20%. If the last quarter the promoter was sampled in is more than 3 years in the past the inspection rate must be 30. The targets must be at least 5% of the calculated quarterly quota, unless quota less than 20 in which case can be zero or greater. The sum of the targets that the user provides must not exceed the calculated quarterly quota.

POST /sample-inspections/start-quarter

This endpoint will be used by HA users to start a sample inspection quarter.

This can be done when a quarter is not already in progress, the upcoming quarter is not in a different financial year, and there are a sufficient number of samples. Users must provide a start_date that aligns with the start of a financial quarter and is today or in the past. The sample inspection targets for the upcoming quarter are then started. Any new targets created while a quarter is in progress are automatically assigned to that quarter.

POST /sample-inspections/end-quarter

This endpoint will be used by HA users to end a sample inspection quarter.

This can be done when a quarter has been previously started. The sample inspection targets for the quarter are then closed. Any samples that were not completed will be automatically expired. If the quarter being closed is not Q4, the targets will be copied across to the next quarter so promoters with existing targets do not need to be setup again. This action cannot be undone.

GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}

This endpoint will be used by HA users to get details of an individual sample inspection target by its target reference number.