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 latest version of the API is available here.
Worklist API
Get permits about to deem
This endpoint will be used by HA users to retrieve information on permits that are due to deem ‘today’. The response will be an array of objects containing the following properties:
- work_reference_number – The work reference number associated with the permit
- permit_reference_number – The permit reference number of the permit
- works_location – The street name the permit was raised against
- promoter – The name of the organisation associated with the permit
- deem_date – The deem date of the permit
- application_submission_date – The date the permit was created
- works_category – The work category of the permit
- highest_traffic_management_type – The highest known traffic management type associated with the permit
- start_date – The date the permit works were intended to start
- end_date – The date the permit works were intended to finish
Get work stops due
This endpoint will be used by promoter and contractor users to retrieve information on works that have been started. It will only return works that have not net been stopped where the proposed end date is ‘yesterday’, ‘today’, or ‘tomorrow’. The response will be an array of objects containing the following properties:
- work_reference_number – The work reference number of the permit
- permit_reference_number – The permit reference number of the permit
- works_location – The street name the permit was raised against
- highway_authority – The name of the organisation associated with the permit
- start_date – The start date of the permit
- proposed_end_date – The proposed end date of the permit
- reasonable_period_end_date – The reasonable period end date of the permit set by the Highway Authority
- workstream_id – The workstream id that was used to create the permit
Get potential works overrunning
GET /potential-works-overrunning
This endpoint is available to Highway Authority users only. It returns information on works that have been started but not yet stopped, where the reasonable period end date elapsed between 1 and 7 days ago. The response will be an array of objects containing the following properties:
- work_reference_number – The work reference number associated with the permit
- permit_reference_number – The permit reference number of the permit
- works_location – The street name the permit was raised against
- promoter – The name of the promoter organisation associated with the permit
- start_date – The date the permit works actually started
- end_date – The proposed end date of the permit
- reasonable_period_end_date – The reasonable period end date of the permit set by the Highway Authority
Entries can be dismissed using the Delete endpoint below. A dismissed entry will reappear if a subsequent duration-challenge resolution event changes the reasonable period end date so that it falls back within the 1–7 day window.
Delete potential works overrunning entry
DELETE /potential-works-overrunning/{permitReferenceNumber}
This endpoint is available to Highway Authority users only. It removes a single permit from the potential works overrunning worklist. The endpoint is idempotent — if the entry does not exist the response will still be 204 No Content.
Get refused permits
This endpoint will be used by promoter and contractor users to retrieve information on permits that have been refused in the last 7 days. The response will be an array of objects containing the following properties:
- work_reference_number – The work reference number associated with the permit
- permit_reference_number – The permit reference number of the permit
- works_location – The street name the permit was raised against
- highway_authority – The name of the Highway Authority organisation associated with the permit
- proposed_start_date – The proposed start date of the permit
- proposed_end_date – The proposed end date of the permit
- refused_date – The date the permit was refused
- reasons_for_refusal – A list of reasons provided for the refusal of the permit
Get work starts due
This endpoint will be used by Planner and Contractor users to retrieve information on granted permits where the works start has not yet been logged and the proposed start date falls within today through the next 7 days. Results are sorted by proposed_start_date ascending. An optional swa_code query parameter may be supplied by Contractor users to filter results to a specific Highway Authority.
Only permits meeting all of the following criteria are included:
- Permit status is granted
- Works start has not been logged
- Proposed start date is today or within the next 7 days (end of day)
- Validity period has not yet ended
- The requesting user has view access to the permit's workstream
The response will be an array of objects containing the following properties:
- work_reference_number – The work reference number associated with the permit
- permit_reference_number – The permit reference number of the permit
- works_location – The street name the permit was raised against
- highway_authority – The name of the Highway Authority organisation associated with the permit
- proposed_start_date – The proposed start date of the permit
- proposed_end_date – The proposed end date of the permit
- validity_period_end_date – The date the permit validity period ends
- workstream_prefix – The prefix of the workstream used to create the permit
Get change requests about to deem
GET /change-requests-about-to-deem
This endpoint will be used by Highway Authority users to retrieve information on change requests that are due to deem ‘today’. The response will be an array of objects sorted by work status (in progress first) then change submission date (oldest first), containing the following properties:
- change_request_reference_number – The change request reference number of the change request
- work_reference_number – The work reference number associated with the change request
- permit_reference_number – The permit reference number of the permit associated with the change request
- works_location – The street name the works were raised against
- promoter – The name of the organisation associated with the change request
- deem_date – The deem date of the change request
- change_submission_date – The date the change request was created
- works_category – The work category of the associated permit
- work_status – The current work status of the associated works
- start_date – The proposed start date of the works
- end_date – The proposed end date of the works