API specification
Version 6.0
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.
Work API Resource Guide
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
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
Create permit endpoint
POST /works/{workReferenceNumber}/permits
This endpoint is used to add a new permit to an existing works. There are three 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.
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.
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”.
Add files to a work
POST /works/{workReferenceNumber}/files
This endpoint can be used to associate uploaded files to the work. See file upload endpoint for more details
Get work
GET /works/{workReferenceNumber}
This endpoint can be used to retrieve all information relating to a work. Any records linked to a work will also be returned however these will be summarised details and will limited to the most recent 50.
Calculate work duration
This endpoint can be used to check what durations will be assigned to a work/permit based on start and end date.
Get Permit
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
This endpoint can be used to retrieve all information relating to a permit. Any records linked to a permit will also be returned however these will be summarised details and will limited to the most recent 50.
Permit assessment
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
This endpoint can be used to by a HA user to assess a permit.
Lane rental assessment
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/lane-rental-assessments
This endpoint can be used to by a HA user to add a lane rental assessment to a permit.
Permit Duration challenge
POST works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-review
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.
Permit Duration challenge non acceptance
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.
Get permit category
This endpoint can be used to check what category will be assigned to a permit.
Get earliest permit endpoint
GET /works/{workReferenceNumber}/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.
Update status endpoint
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/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.
Permit Discount
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/permit-discount
This alteration endpoint allows a HA to amend permit discounts applied and reason after assessment.
Acknowledge HS2 applications endpoint
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/hs2_acknowledgement
This endpoint allows HAs to acknowledge a HS2 consultation application.
Mark permit as under assessment endpoint
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/under-assessment
This endpoint allows HAs to mark a permit as under assessment.
History
GET /works/{workReferenceNumber}/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:
- Application: A permit action prior to assessment
- Permit: A permit action once it has been granted
- PAA: A permit action when it has a work_category of paa
- ChangeRequest: A permit alteration action
- FPN: A fixed penalty notice action
- Reinstatement: A site or reinstatement action
- Inspection: An inspection action
- ScheduledInspection: A scheduled inspection action
- Work: A work record action i.e. uploading a file
- ForwardPlan: A forward plan action
- Comment: Logging a comment
- 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.
- Logging an Inspections: Inspection Reference Number
- Applying for a Permit: Permit Reference Number
- HA granting a permit application: Permit Reference Number
- Permit application deeming: Permit Reference Number
- Requesting a change: Change Request Reference Number
- Creating a site or reinstatement: Reinstatement Reference Number
- Raising a FPN: FPN Reference Number
- Adding or removing a File to a work record: File ID
- 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.
Create private street notice endpoint
This endpoint is used to create a private street notice. A private street notice can only be created on a USRN with either a road_category of 9 (private street) or a USRN with reinstatement_types containing a reinstatement_type_code of 9 (private street). A USRN can be fully or partially private. If it is fully private then road_category is not required, however this will be validated against the NSG data (See below). If creating on a partially private street then the road_category is required and must indicate the private part of the street (9 - private street), this is also validated against the NSG data (See below). In both scenarios the USRN provided must return a street that is either fully or partially private.
The Street Lookup API endpoint /nsg/usrn can be used to determine if a street is private. If the response returns a road_category of 9 the street is considered fully private. If the response contains reinstatement_types containing a reinstatement_type_code of 9 (private street), then the street will be considered partially private.
As well as creating a private street notice, a corresponding Work will also be generated. If the user supplies a work_reference_number as part of the request body to POST /private-street-notices 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 work_reference_number is used to generate the private_street_notice_reference_number with the following format.
{workReferenceNumber}-PSN
Both the work_reference_number and the private_street_notice_reference_number are returned in the response.
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.
Cancel private street notice endpoint
PUT /works/{workReferenceNumber}/private-street-notices/{privateStreetReferenceNumber}/cancel
Cancels a private street notice matching a work reference number and a private street reference number provided the private street notice has been issued.
On site (start/stop works)
Once a permit has been submitted, the promoter which raised the permit is able to:
- Start a work
- Stop a work
- Provide inspection units
- 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/{workReferenceNumber}/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/{workReferenceNumber}/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/{workReferenceNumber}/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.
If an immediate permit is still awaiting assessment when the work stop is logged, the assessment status will be updated to granted (auto). If the permit is in any other state e.g. under assessment, it will remain available to be assessed.
Revert stop work endpoint
PUT /works/{workReferenceNumber}/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/{workReferenceNumber}/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.
Update excavation carried out
PUT /works/{workReferenceNumber}/excavation-carried-out
This endpoint can be used to update the excavation status of a work.
Permit Alterations (note this functionality has been deprecated - See Change Requests
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:
- Promoter change request: Promoter submitted alteration after permit has been granted or in-progress
- Promoter imposed change: Promoter submitted alteration before permit has been granted or in response to a permit modification request.
- Work extension: Promoter submitted proposed end date alteration to in-progress work
- HA imposed change: HA users impose changes to permit conditions after permit is granted or in-progress
- HA change request: Currently in the road map for future release (post April 2020)
- 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/{workReferenceNumber}/permits/{permitReferenceNumber}/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/{workReferenceNumber}/permits/{permitReferenceNumber}/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
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
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.
Alteration Duration challenge
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.
Create change request endpoint
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests
This endpoint allows a Planner or Contractor user with write access to the work to create a new permit change request. The request body takes a change reason and at least one of the editable properties on the permit. Omitted properties will not be updated, and providing null will unset optional properties on the permit. The provided changes will be ‘applied’ to the current permit version before validation to ensure the changes requested would not result in an invalid scenario, for example if the traffic_management_type is changed and the emergency_contact_name is not already set then it will throw a validation error. When a promoter uses this endpoint, the change request will have a ChangeRequestType 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 change request is created it is required to be assessed by the associated HA. NOTE: This has significant differences from the current alteration endpoint - The new permit version will not be created when a change request is raised, it will instead be created when granted (or deemed) and the changes will be applied to the current permit version.
Update change request status
This endpoint allows a Highway Authority user with write access to the work to update the status of the given change request to granted, refused or granted_with_duration_challenge. The sequence section shows how a change request can be assessed and actioned at various stages by promoters and highway authorities. This endpoint drives all of these functions. Work extensions or change requests that have changed the reasonable period end date can be duration challenged by Highway Authorities. Assessment comments must be provided if the change request is being refused or granted with duration challenge. Assessment discount must be provided if the change request is being granted. Granting a change request will apply the change to the permit.
NOTE: This has significant differences from the current alteration endpoint. The changes will be applied to the current permit version rather than the version that existed when the change request was raised. Once the permit has been assessed the current permit details will be recorded and its details become fixed.
Get change request
This change request endpoint returns both the current and the proposed changes of a permit in addition to the reason for the change request, assessment information and other information relevant to the change request. NOTE: This has significant differences from the current alteration endpoint - This endpoint will return the current permit details which may change over time, the alteration endpoint returns the original permit details recorded at the point of alteration creation, which never changes. Once the permit has been assessed the current permit details will always return the version that existed at the point of assessment.
Impose change endpoint
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/impose
This endpoint allows HA users to impose changes to permit conditions. The ChangeRequestType 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.
Change Request Duration challenge
The PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/{changeRequestReferenceNumber}/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 ChangeRequestResponse.
The PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/change-requests/{changeRequestReferenceNumber}/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 ChangeRequestResponse.
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/{workReferenceNumber}/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/{workReferenceNumber}/sites/{siteReferenceNumber}
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/{workReferenceNumber}/sites/{siteReferenceNumber}/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. The response_to_remedial_works and base_courses_affected properties should only be supplied when submitting a permanent reinstatement to a site where the last reinstatement was also permanent. You must provide both fields together. If response_to_remedial_works is false, or response_to_remedial_works is true and base_courses_affected is false, the end_date on the resulting reinstatement will remain the same as on the prior reinstatement. Otherwise, the end date will be calculated as normal.
Delete reinstatement endpoint
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.
Subsume site
PUT /works/{workReferenceNumber}/sites/{siteReferenceNumber}/subsume
This endpoint can be used indicate that a site has been subsumed by another reinstatement.
Update final reinstatement
PUT /works/{workReferenceNumber}/final-reinstatement
This endpoint can be used indicate whether the final reinstatement has been recorded or not.
Create non-notifiable site
POST /non-notifiable-works/sites
This endpoint can be used create a non-notifiable site.
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/{workReferenceNumber}/inspections
Creating an inspection will return a inspection reference number which can be used to retrieve an individual inspection via the GET endpoint provided. See non-compliance for more details.
Delete inspection endpoint
DELETE /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
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/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/status
If an inspection has been failed, a planner or contractor can dispute or accept this outcome. The highway authority can then respond and resolve a disputed inspections failed outcome. {: .govuk-body}Ù
Get inspection
GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
This endpoint can be used to get details of an inspection.
Withdraw inspection
PUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw
This endpoint can be used to withdraw an inspection.
Create Scheduled inspection
POST /works/{workReferenceNumber}/scheduled-inspections
This endpoint can be used to create a scheduled inspection.
Delete Scheduled inspection
DELETE /works/{workReferenceNumber}/scheduled-inspections
This endpoint can be used to delete a scheduled inspection.
Create historic inspection
POST /historic-works/inspections
This endpoint can be used to create a historic inspection.
Create Non-compliance
When an inspection is created via the Create inspection endpoint where it has an inspection_type of reinstatement, investigatory_works 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, investigatory_works 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 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.
Update non-compliance status
PUT works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber}/status
This endpoint will allow a Planner, Contractor or Highway Authority user to update the response status for a single non-compliance. The statuses issued and works_completed_and_passed cannot be submitted by any user. The withdrawn status can only be submitted by HAs, and the works_complete_ready_for_inspection status can only be submitted by promoters. See section 4.7. Non-Compliance in the business rules for further information on valid responses to submit to this endpoint.
If no party has yet suggested a joint site meeting, submitting a status of joint_site_meeting_suggested will set the non-compliance’s jsm_requested_by field to the organisation that first suggests a joint site meeting. The opposite party can then submit the will_attend_joint_site_meeting status to confirm attendance. If the opposite party suggests a different joint site meeting date, the party that originally suggested the joint site meeting can submit the accept_suggestion status to confirm attendance. Both of these statuses will update the non-compliance’s jsm_status to date_and_time_agreed, and set the jsm_suggested_time to the time agreed upon.
Submitting a status of withdrawn will withdraw the non-compliance, and also automatically withdraw any inspections linked to the non-compliance.
Link permit to a non-compliance
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/link-non-compliance
After a permit has been created it may be linked to a non-compliance by using this PUT endpoint. A non_compliance_reference_number must be supplied, the non-compliance and permit must be on the same work, the non-compliance must not be withdrawn or resolved and the permit must not be progressed, cancelled, refused or revoked.
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/{workReferenceNumber}/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/{workReferenceNumber}/fixed-penalty-notices/{FpnReferenceNumber}/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/{workReferenceNumber}/fixed-penalty-notices/{FpnReferenceNumber}
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.
Get FPN
GET /works/{workReferenceNumber}/fixed-penalty-notices/{fpnReferenceNumber}
This endpoint can be used to get details of an FPN.
Create Historic FPN
POST /historic-works/fixed-penalty-notices
This endpoint can be used to create an FPN for a historical work.
Forward Plans
GET /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber}
PUT /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber}
PUT /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber}/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/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/status
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/reassign-section-81
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.
The reassign section 81 endpoint will reassign an existing section 81 to a new organisation. The original section 81 must have a status of rejected or cancelled, the original section 81 will have its status set as reassigned and remain with the original organisation. A new works record and section 81 will be created and assigned to the new organisation. All original details including uploaded files and scheduled inspections will be preserved on the new section 81 (existing scheduled inspections will be removed from the original section 81).
The work reference number of the new works record will be similar to the original, but with an incrementing suffix each time it is re-assigned for example
- Original WRN -
CTS8115245959- S18RN -CTS8115245959-S81-UW - First reassignment WRN -
CTS8115245959-01- S18RN -CTS8115245959-01-S81-UW - Second reassignment WRN -
CTS8115245959-02- S18RN -CTS8115245959-02-S81-UW - etc
Link section 81 to permit
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/link-section-81
This endpoint can be used to link a Section 81 to a permit.
Unlink section 81 from permit
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/unlink-section-81
This endpoint can be used to unlink a Section 81 from a permit.
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 -
proposedin_forcecancelledclosed
Section 74s
POST /works/{workReferenceNumber}/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.
| 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 |
| 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 -
warning_issuedcharges_endedwarning_disputedwithdrawndraft_invoice_issuedresolved
The PUT /promoter-status endpoint will allow the Planner to update the status of the Section 74.
The available statuses are -
acknowledge_overrun_warningsite_visited_and_rectifiedacknowledge_draft_invoicecharge_under_reviewcharge_agreedwarning_disputed
Get comment
TOOD POST /works/{workReferenceNumber}/comments
TOOD PUT /works/{workReferenceNumber}/comments/{commentReferenceNumber}/read
GET /works/{workReferenceNumber}/comments/{commentReferenceNumber}
GET /works/{workReferenceNumber}/comments/{commentReferenceNumber}
This endpoint allows a Planner, Contractor or Highway Authority user with read access to the work to fetch the details of a single comment.
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:
location_descriptionancillary_info_descriptionancillary_info_coordinatesusrnsancillary_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.
Events and Activities
GET /activity/{activityReferenceNumber}
PUT /activity/{activityReferenceNumber}/cancel
PUT /activity/{activityReferenceNumber}
Events or Activities allow a HA to represent different activities within Street Manager. There are 9 activity types currently supported by Street Manager:
- Skips
- Scaffolding
- Hoarding
- Crane Mobile Platform
- Event
- Section 50
- Section 58
- Compound
- 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.
File upload
Several flows discussed in the previous sections allow users to add files as part of their request:
- Submit permit application: planners can upload traffic management plans
- Add reinstatement: planners can upload evidence of the reinstatement
- Issue an inspection: HA users can upload evidence as part of issuing failed inspection
- Issue a fixed penalty notice: HA users can upload evidence as part of issuing an FPN
- Works record: Both promoters and HA users can upload files to the work record
- Add sites and inspections on historic works HA users can upload files when adding sites to a work record
- Non notifiable works Both promoters and contractor users can upload files when adding sites to a non notifiable works
- Add sites Both promoters and HA users can upload files when add sites to a work record
- Issue a Section 81: HA users can upload evidence as part of issuing a Section 81
- 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
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
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
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.
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:
- Be a valid .csv file type
- Contain max 10,000 USRNs
- Contain a single column of USRNs (without a heading)
- Contain unique USRNs
- Contain valid USRNs
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.
Create Material Classification
This endpoint can be used to create a Material Classification. A Material Classification can be used to indicate if there are hazardous/non-hazardous materials in the area. When creating a Material Classification, you may only provide one coordinate with the type of point. Additionally, you may only provide one file_id to this endpoint.
material_classification_reference_number is generated with the following format: {organisation-prefix}{8 digit random number}-MC.
The material_classification_reference_number is returned in the response.
Get Material Classification
GET /material-classifications/{materialClassificationReferenceNumber}
Once a material classification has been created this GET endpoint can be used to retrieve the details of the material classification for the provided material classification reference number.