API Versions and Changes
This section lists any significant changes made to this document (and by extension, the API interfaces themselves) introduced by each recent and upcoming future release.
Version 4.15.37 (12/09/2024):
Updated Works API with the following changes:
-
SM-11673: The endpoint
POST /works/{workReferenceNumber}/permits
will now, in cases where a PAA is progressed to a PA, create ancillary information based off what was present on the PAA. Any ancillary information on the PAA will be removed with the reason "Transferred from PAA to PA". -
SM-11915: Updated
POST /works
andPOST /forward-plans
to automatically save interested parties for the USRN returned from the Street Lookup API.
Updated Street Lookup API with the following changes:
-
SM-11915: Updated
POST /nsg/streets/search
andGET /nsg/streets/{usrn}
to return theswa_code
for each organisation returned in theinterest_authorities
property. Any SWA code returned by these endpoints will also now be correctly padded to 4 characters with leading zeroes.
Version 4.15.36 (29/08/2024):
Updated Works API with the following changes:
-
SM-12268: Updated
POST /works/{workReferenceNumber}/inspections
andPUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw
to use the correct user (Automated) for works history entries when withdrawing or resolving an inspection or non-compliance, where appropriate.
Updated Sampling API with the following changes:
-
SM-12192: Updated
POST /sample-inspections
to only consider permanent reinstatements as eligible for Category B sample inspections.
Version 4.15.35 (18/07/2024):
Updated Works API with the following changes:
-
SM-11642: Updated
PUT /works/{workReferenceNumber}/revert-stop
to correctly set status of permit if permit was marked asunder_assessment
when work stop was logged. If an immediate permit wasunder_assessment
when work stop was logged, revert work stop will set the permit asunder_assessment
. If a planned permit wasunder_assessment
when work stop was logged, revert work stop will set the permit assubmitted
Version 4.15.34 (04/07/2024):
Updated Works API with the following changes:
-
SM-12058: Updated
GET /works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber}
to returnjsm_requested_by
as organisation name rather than organisation ID.
Version 4.15.33 (20/06/2024):
Updated Works API with the following changes:
-
SM-11843:
POST works/{workReferenceNumber}/inspections
updated to automatically add aninspection_category
for section 81 inspections (initial on first and follow up on subsequent). These will be returned asupcoming_enum
on v4.
Updated Sampling API with the following changes:
-
SM-11770: Includes the following changes:
-
POST /sample-inspection-targets
constraints updated to allow atarget_c
of 0 when less than two years worth (not including current FY) ofauto_calculated
annual inspection units exist. -
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
constraints updated to allow atarget_c
of 0 when less than two years worth (not including current FY) ofauto_calculated
annual inspection units exist.
-
Version 4.15.32 (23/05/2024):
Updated Data Export API with the following changes:
-
SM-11981: Includes the following changes:
- Re-named two properties of the returned CSV for
GET inspections/csv
. Details below -- 'Promoter reason for dispute' renamed to 'Promoter response details'.
- 'Highway authority reason for accepting' renamed to 'Highway authority response details'.
- Re-named two properties of the Download all my data Inspection CSV. Details below -
- 'promoter_reason_for_dispute' renamed to 'promoter_response_details'.
- 'ha_reason_for_accepting' renamed to 'ha_response_details'.
- Re-named two properties of the returned CSV for
Updated Works API with the following changes:
-
SM-11422: Includes the following changes:
-
PUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw
updated to withdraw the linked non-compliance when withdrawing an inspection linked to only one non-compliance. -
GET /works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber}
updated to support thepromoter_response_status
andha_response_status
ofaccept_suggestion
.
-
Version 4.15.31 (09/05/2024):
Updated Sampling API with the following changes:
-
SM-11902: Updated
POST /sample-inspections/end-quarter
to insert zeroed performance statistics for any promoter that has no progress made on their target during a quarter to enable HAs to end the quarter.
Version 4.15.30 (25/04/2024):
Updated the Reporting API with the following changes:
-
SM-11832: Removed duplicate filter usage for geographical areas from
GET /reinstatements/expiring-interims
to prevent errors.
Updated Works API with the following changes:
-
SM-8319: Updated
PUT /works/{workReferenceNumber}/stop
so that immediate permits indicated to be under assessment are not automatically granted when works are completed.
Update Event API with the following changes:
-
SM-11866: Updated
POST /api-notifications/unsubscribe
. In the event a user does not confirm a subscription within 48 hours it is removed from SNS. In this event the subscription will also be removed from the database. Users may usePOST /api-notifications/subscribe
to set up their subscription again.
Version 4.15.29 (28/03/2024):
Updated Sampling API with the following changes:
-
SM-11519:
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
now allows for the inspection rate to be increased to 100%, in increments of 5%.
Updated Work API with the following changes:
-
SM-11806: Updated the
POST works/{workReferenceNumber}/inspections
now increments non compliance inspections count when posting linked non compliance inspections. -
SM-11769: Updated the
PUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw
endpoint so that when an inspection is withdrawn, the PBI quarterly progress for completed inspections in the current quarter is decremented accordingly. Re-generating PBI samples will provide an additional sample inspection if the withdrawn inspection was a Category B/C inspection. Note that the withdrawn inspection will not be removed from the performance statistics. -
SM-11850: Updated
POST /works/{workReferenceNumber}/sites
andPOST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
to setreinstatement_registration_due_date
asnull
to the provided permit or active permit, if none provided, if thereinstatement_type
isexcavation
.
Updated Reporting API with the following changes:
-
SM-11806:
GET /non-compliances
now returns the number of linked inspections for non compliances.
Version 4.15.28 (14/03/2024):
Updated Work API with the following changes:
-
SM-11029: Updated the
GET /works/{workReferenceNumber}/start
endpoint so that when a work is started after the proposed end date but before the validity period end date, then the end date slides correctly.
Updated Event API with the following changes:
-
SM-11783: Removed the optional
org_ref
from thePOST /api-notifications/subscribe
andPOST /api-notifications/unsubscribe
endpoints. This means that when a contractor subscribes to notifications they will receive notifications from all the organisations they contract for.
Version 4.15.27 (29/02/2024):
Updated Work API with the following changes:
-
SM-6087: Updated the
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
endpoint to audit the correctobject_reference
,internal_user_identifier
, andinternal_user_name
for the superseded PAA when a PAA is progressed to a PA and granted by the HA.
Updated Event API with the following changes:
-
SM-7524: Added new endpoint
POST /api-notifications/unsubscribe
. This will allow users to stop receiving notifications of events regarding their organisation.
Updated Party API with the following changes:
- SM-7524: Updated organisation contract functionality to automatically remove any existing event subscriptions between the contractor and contracting organisations when the contract is removed.
Updated Sampling API with the following changes:
-
SM-11565: Updated
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to allow updating a target if samples have been generated or progress has been made against a target. Added a new constraint toPUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to ensure the new value oftarget_a
must be greater than the value of the current completed inspections and the new values oftarget_b
andtarget_c
must be greater than the value of the current completed inspections plus the number of generated samples for each category.
Version 4.15.26 (15/02/2024):
Updated Work API with the following changes:
-
SM-11550: Updated the
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
endpoint to returnreinstatement_registration_due_date
as part of the response.
Updated Sampling API with the following changes:
-
SM-11454: Updated the following endpoints to support automatically adjusting inspection rate on quarter end based on sampling performance:
POST /sample-inspections/end-quarter
will now automatically adjust inspection rate for the next quarter's targets based on the calculated failure rate. If a target has been automatically adjusted, it will have itstarget_a
,target_b
andtarget_c
values set to 0. These must be updated before generating samples.POST /sample-inspections/start-quarter
will now allow starting a quarter with no targets set.POST /sample-inspections
will now prevent samples being generated if any targets that have been automatically adjusted have not been updated.
Updated Event API with the following changes:
-
SM-7523: Added new endpoint
POST /api-notifications/subscribe
. This will allow users to create a subscription to the events which occur regarding their organisation. Contractors will provide anorg_ref
property to specify which organisation they wish to subscribe to.
Version 4.15.25 (01/02/2024):
Updated Work API with the following changes:
-
SM-8167: Updated
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status
to prevent users from settingalteration_status
togranted_with_duration_challenge
when the change request is not a Works extension.
Version 4.15.24 (18/01/2024):
Updated Work API with the following changes:
-
SM-11684: Updated
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status
to prevent users from addingassessment_comments
whenalteration_status
is granted. -
SM-11652: Updated
GET /works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber}
endpoint to return the following HA and promoter response fields as part of thelinked_inspections
field:- ha_response_status
- ha_response_status_string
- ha_response_status_change_date
- ha_reason_for_accepting
- promoter_response_status
- promoter_response_status_string
- promoter_response_status_change_date
- promoter_reason_for_dispute
Updated Sampling API with the following changes:
-
SM-11524: Updated
GET /sample-inspection-quota
endpoint to return a quota of 1 when low average inspection units are provided which would otherwise return a quota of 0.
Updated Reporting API with the following changes:
- SM-11602: Minor performance refactor to workstream matching for promoter and contractor users. Affects all endpoints.
-
SM-11221: Updated
GET /expiring-interims
to return the correct expiring interim reinstatements based on confirmed business criteria.
Updated Data Export API with the following changes:
-
SM-11221: Updated
POST /reinstatements/expiring-interims/csv
to return the correct expiring interim reinstatements based on confirmed business criteria.
Updated Party API with the following changes:
-
SM-11503: Updated
POST /users
andPOST /re-onboard-user
to increase the minimum limit for passwords to 12 characters.
Version 4.15.23 (04/01/2024):
Updated Reporting API with the following changes:
-
SM-8303: The endpoints
GET /activities
andGET /section-58s
now return a validation error if a providedha_organsation_name
is over 100 characters long.
Updated Data Export API with the following changes:
-
SM-8303: Endpoint
POST /section-58s/csv
now returns a validation error if a providedha_organsation_name
is over 100 characters long.
Updated Work API with the following changes:
- SM-11669: All endpoints checked/updated to ensure supplied reference numbers are case insensitive.
-
SM-11414:
GET /works/{workReferenceNumber}
will now return a summary of any associated Non-Compliances as part of the response. Data returned innon_compliances
are:-
non_compliance_reference_number
-
non_compliance_date
-
non_compliance_status
-
non_compliance_status_string
-
-
SM-8407: The following endpoints will validate coordinates, when providing a point, to ensure no more than two coordinates are supplied:
-
POST /activity
-
POST /ancillary-informations
-
POST /forward-plans
-
POST /historic-works/fixed-plenty-notices
-
POST /historic-works/inspections
-
POST /non-notifiable-works/sites
-
POST /section-81-works/section-81s
-
POST /works/{workReferenceNumber}/sites
-
POST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
-
Version 4.15.22 (07/12/2023):
Updated Sampling API with the following changes:
-
SM-11453: Updated
POST /sample-inspection-targets
andPUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
endpoints to accept a new optionalinspection_units_year_three
value. This can only be provided from 1st April 2024. -
SM-11519:
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
now allows for the inspection rate to be decreased to 20%, in increments of 5%.
Version 4.15.21 (23/11/2023):
Updated Work API with the following changes:
- SM-11533: Only passed non-compliance follow up or follow up completion inspections resolve a non-compliance. Non-compliances cannot currently be raised in the Production Street Manager environment therefore there will be no non-compliance to resolve.
Version 4.15.20 (09/11/2023):
Updated Work API with the following changes:
-
SM-9101: Updated validation for
POST /works/{workReferenceNumber}/permits
to provide meaningful error whenworks_coordinates
are missing. -
SM-11359: Updated
GET /works/{workReferenceNumber}
endpoint to return private street notice summary information when a private street notice is associated with the works. -
SM-11420: Updated
POST /works/{workReferenceNumber}/permits
endpoint to allow linking a non-compliance to a permit via anon_compliance_reference_number
. Non-compliances cannot currently be raised in the Production Street Manager environment and as such, non-compliance reference numbers should not be provided via this endpoint until further notice.
Updated Reporting API with the following changes:
-
SM-11223: Updated
GET /reinstatements/expiring-interims
to use static database created using the previous day's backup (as used for DAMD) to retrieve data. This will mean that any updates done in the current working day will not be included.
Updated Data Export API with the following changes:
-
SM-11223: Updated
POST /reinstatements/expiring-interims/csv
to use static database created using the previous day's backup (as used for DAMD) to retrieve data. This will mean that any updates done in the current working day will not be included.
Version 4.15.19 (26/10/2023):
Updated Work API with the following changes:
-
SM-11277: Updated
POST /works/{workReferenceNumber}/start
endpoint to correctly slide end dates for works lasting less than 24 hours when the work start is within 24 hours of the proposed end date. -
SM-11415: Added new endpoint
GET /works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber}
for upcoming non-compliance functionality. -
SM-11538: Added new endpoint
GET /works/{workReferenceNumber}/private-street-notices/{privateStreetReferenceNumber}
to retrieve a private street notice.
Updated Data Export API with the following changes:
-
SM-8497: Error message when the
swa_code
is missing forPOST /section-58s/csv
,POST /permits/csv
,POST /section-74s/csv
andPOST /alterations/csv
updated to be more descriptive.
Version 4.15.18 (12/10/2023):
Updated Work API with the following changes:
-
SM-11413: Updated
POST /works/{workReferenceNumber}/inspections
endpoint to accept a new optional fieldnon_compliance_reference_number
for upcoming non-compliance functionality. -
SM-11228: Updated
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status
to remove associated ancillary information when a permit is cancelled.
Version 4.15.17 (28/09/2023):
Updated Work API with the following changes:
-
SM-11465: Updated
PUT /works/{workReferenceNumber}/fixed-penalty-notices/{fpnReferenceNumber}/status
to allow HAs to withdraw already accepted FPNs. -
SM-11025: Updated
PUT/works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/status
andPUT/works/{workReferenceNumber}/permits/{permitReferenceNumber}/current-traffic-management-type
to includeinternal_user_name
andinternal_user_identifier
as part of their request body.
Updated Sampling API with the following changes:
-
SM-11449: Updated
POST /sample-inspections
to omit works when generating samples if their most recent inspection has failed.
Version 4.15.16 (14/09/2023):
Updated Sampling API with the following changes:
-
SM-11010: Updated
POST /generate-samples
to no longer generate samples that would exceed the selected sample inspection rate after sample inspections had been marked as completed.
Updated Work API with the following changes:
-
SM-11226: Updated
POST works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
to calculate inspection units if the Permit has anactual_end_date
. Also as part of this change the following endpoints were updated to check foractual_end_date
before calculating inspection units:PUT /works/{workReferenceNumber}/excavation-carried-out
PUT /works/{workReferenceNumber}/start
PUT /works/{workReferenceNumber}/revert-start
- SM-11446: Updated the Swagger docs definition for the
POST /files
endpoint to correctly showswaCode
as a query param rather than as a request body property. No functional changes to the interface.
Version 4.15.15 (17/08/2023):
Updated Event API with the following changes:
- SM-11185: Updated the version of the component that handles http status codes.
Updated Data Export API with the following changes:
- SM-11185: Updated the version of the component that handles http status codes.
Updated Work API with the following changes:
- SM-11185: Updated the version of the component that handles http status codes.
Version 4.15.14 (20/07/2023):
Updated Work API with the following changes:
-
SM-11155: Updated
PUT /works/{workReferenceNumber}/stop
to filter out permits with the status ofcancelled
when calculatinginspection_units
.
Version 4.15.13 (06/07/2023)
Updated Reporting API with the following changes:
-
SM-11187: Added a new endpoint
POST /works/files
to return theid
andname
all files associated with a work.
Updated Data Export API with the following changes:
-
SM-10966: Updated
POST /comments/csv
to add two new additional filtersis_incoming
andis_outgoing
.is_incoming
will only return comments from outside the users organisation.is_outgoing
will only return comments from within the users organisation. -
SM-11180: All POST endpoints ending in
/csv
now have an optional parameterexport_description
which is limited to 50 characters and added as a description of a csv export.
Updated Reporting API with the following changes:
-
SM-10966: Updated
GET /comments
to add two new additional query paramsis_incoming
andis_outgoing
.is_incoming
will only return comments from outside the users organisation.is_outgoing
will only return comments from within the users organisation. -
SM-11180:
GET /csv-exports
now returns the following new optional properties for each export:export_description
csv_export_type
csv_export_type_string
filters
Version 4.15.12 (22/06/2023)
Updated Work API with the following changes:
-
SM-11052: Updated
POST /works/{workReferenceNumber}/inspections
to no longer count unable to complete category A inspections against sample inspection target progress when adding a new category A inspection
Version 4.15.11 (08/06/2023)
Updated Work API with the following changes:
-
SM-11061: The
POST /works
,POST /works/{workReferenceNumber}/permits
endpoints now defaults theis_covid_19_response
value to false because the COVID measures are no longer applicable. -
SM-10878: Inspections created via the
POST /works/{workReferenceNumber}/inspections
andPOST /historic-works/inspections
endpoints will now set an auto-acceptance due date in the background.
Version 4.15.10 (25/05/2023)
Updated Work API with the following changes:
-
SM-11066: Updated
POST /authenticate
to send an email when a user isdisabled
to tell them to contact their admin. - SM-10910: Updated the following endpoints to allow 1500 characters for the comment property on permit conditions:
POST works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
POST /works
POST /works/{workReferenceNumber}/permits
POST works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/impose
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status
to allow 1500 characters on theassessment_comments
property. And updatedPUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
to allow 1500 characters on theadditional_comments
property.
Version 4.15.9 (11/05/2023)
Updated Work API with the following changes:
-
SM-8539: Removed the following deprecated endpoints:
POST /sample-inspection-targets
GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
POST /sample-inspection
sample_inspections
property from theWorkResponse
. -
SM-10871: Increased
internal_user_name
valid length to 100 characters. Increasedusername
property ofinspectionCreateRequest
andhistoricInspectionCreateRequest
valid length to 100 characters. - SM-7076: Updated the version of the component that handles the http status codes.
-
SM-8555: Updated
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations
to verify the providedusrns
exist. This endpoint will now also return a404 Not found
error along with the usrn(s) which do not exist, if any. -
SM-11063: Refused permits are no longer included in the total inspection unit calculation when a work is stopped or when updating a work about an excavation being carried out. This affects:
PUT /works/{workReferenceNumber}/excavation-carried-out
,PUT /{workReferenceNumber}/stop
,PUT /{workReferenceNumber}/revert-stop
.
Updated Reporting API with the following changes:
-
SM-8539: Removed the following deprecated endpoints:
GET /sample-inspection-targets
GET /sample-inspections
Updated Data Export API with the following changes:
-
SM-8539: Removed the deprecated endpoint
POST /sample-inspections-due/csv
.
Updated Sampling API with the following changes:
-
SM-11026: Updated
POST /sample-inspections
so works with previous category B or C inspections will be ignored. This will mean that duplicates do not need to be managed manually by users. -
SM-11031: Fixed a bug in
GET /sample-inspection-quota
,POST /sample-inspection-targets
andPUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to ensure the yearly average inspection units are consistently rounded
Version 4.15.8 (27/04/2023)
Updated Reporting API with the following changes:
-
SM-10961: Minor bug fix on
GET /permits
. The returned value ofdate_created
is now the permit created date instead of the latest permit version created date.
Version 4.15.7 (13/04/2023)
Updated Work API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages. -
SM-5431: Changed the error message when the user does not have read access from "Access restricted" to "Unauthorised. Workstream or Organisation access is required." on the following endpoints:
GET /works/{workReferenceNumber}/fixed-penalty-notices/{fpnReferenceNumber}
GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
GET /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}
GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
GET /works/{workReferenceNumber}/sites/{siteReferenceNumber}
GET /works/{workReferenceNumber}/all-sites
GET /works/{workReferenceNumber}
GET /works/{workReferenceNumber}/history
GET /files/{fileId}
-
SM-10973: Updated
PUT /works/{workReferenceNumber}/sites/{siteReferenceNumber}/subsume
to no longer set inspection units to zero if there was only one site on the work. -
SM-8451: Updated
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
to prevent multiple permit modification requests being made via the API. -
SM-10855: Updated
POST /fee-matrix
to create an audit entry when a fee matrix is created or updated.
Updated Event API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages.
Updated Data Export API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages. -
SM-7638: Updated
POST /fees/csv
endpoint with 2 new optional request parameters:fee_report_format
andswa_code_filter
. Thefee_report_format
property can only be set tosingle_org_one_csv
at the moment. Usingsingle_org_one_csv
&swa_code_filter
can give API users the functionality to download a CSV for one org. -
SM-7637: Updated
POST /fees/csv
to accept a new optionalfee_report_format
value ofall_orgs_multiple_csvs
. This will generate a ZIP file containing a CSV for each of the organisations contained in the report.
Updated GeoJSON API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages.
Updated Party API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages.
Updated Reporting API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages. -
SM-9581: Fixed a bug in
GET /reinstatements/expiring-interims
to ensure it returns all expiring interim reinstatement for a work when there are multiple sites, some with permanent reinstatement.
Updated Sampling API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages. - SM-10880: Highway authority users with the Street Works Admin role will now be able to manage Performance Based Inspections (PBI). Promoters with the Street Works Admin role will now be able to view PBI sample inspection targets.
Updated Street Lookup API with the following changes:
-
SM-8602: Updated dependency
class-validator
to version14.0.0
. As a result, validation error messages may differ from previous messages.
Version 4.15.6 (21/03/2023)
Updated Work API with the following changes:
-
SM-8302: Removed
PUT works/{workReferenceNumber}/inspection-units
endpoint. Also removed theinspection_units
property from the following endpoints:POST /works/{workReferenceNumber}/sites
POST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
POST /non-notifiable-works/sites
-
SM-8488: The following endpoints relating to deprecated sample inspections functionality will now return a
410 Gone
response code:POST /sample-inspection-targets
GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
POST /sample-inspection
-
SM-8360: Updated
POST /works/{workReferenceNumber}/inspections
endpoint to prohibit:- raising a category A inspection unless an active target is present that has not yet met the quota for category As;
- raising a category B inspection unless a category B sample is present on the work;
- raising a category C inspection unless a category C sample is present on the work.
POST /historic-works/inspections
endpoint to prevent raising a category A, B or C inspection.
Updated Reporting API with the following changes:
-
SM-8488: The following endpoints relating to deprecated sample inspections functionality will now return a
410 Gone
response code:GET /sample-inspections
GET /sample-inspection-targets
GET /pbi-sample-inspections
GET /pbi-sample-inspection-targets
Updated Data Export API with the following changes:
-
SM-8488: The
POST /sample-inspections-due/csv
endpoint relating to deprecated sample inspections functionality will now return a410 Gone
response code. The newPOST /pbi-sample-inspections-due/csv
endpoint should be used instead.
Version 4.15.5 (16/03/2023)
Updated Works API with the following changes:
-
SM-10889: Newly created works will now include
street_line
.GET /works/{workReferenceNumber}
andGET /works/{workReferenceNumber}/permitReferenceNumber
will now returnstreet_line
.
Updated Sampling API with the following changes:
-
SM-10866: Updated
POST /sample-inspection-targets
andPUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to calculate the minimum amount of targets that can be scheduled across categories A, B and C as 5% of the average inspection units divided by four. This new rule applies if the average inspection units is greater than or equal to 80. -
SM-10908: Updated
POST /sample-inspections/end-quarter
to prevent ending of a quarter while a generate samples job is in progress.
Updated Data Export API with the following changes:
-
SM-8531: Updated the 'Download all my data' export to include
pbi_sample_inspection
andpbi_sample_inspection_target
tables. Additionally removed thesample_inspection
table. -
SM-10852: Updated validation on
POST /sample-inspection-targets
andPUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
endpoints to prevent creating or updating a target with all targets set to zero.
Version 4.15.4 (02/03/2023)
Updated Street Lookup API with the following changes:
-
SM-7737: Expired ASDs will no longer be returned within the response of
GET /nsg/streets/search
andGET /nsg/streets/{usrn}
.
Updated Reporting API with the following changes:
-
SM-5049: Updated
GET /comments
to include optional query params forwork_reference_number
andauthor_email_address
.
Updated Data Export API with the following changes:
-
SM-5049: Updated
POST /comments/csv
to include optional query params forwork_reference_number
andauthor_email_address
. -
SM-8675: Changed the SQL query used by the
POST /reinstatements/expiring-interims/csv
endpoint to be more performant and excludes subsumed sites. This aligns with the update made to the Reporting API (SM-8614).
Updated Work API with the following changes:
-
SM-10872: Updated
PUT /works/{workReferenceNumber}/excavation-carried-out
endpoint to fix a bug so that inspection units are only calculated when a work has been completed and has a valid actual end date.
Version 4.15.3 (16/02/2023)
Updated Reporting API with the following changes:
-
SM-8614: Changed
GET /reinstatements/expiring-interims
to improve the API performance by enhancing the SQL query.
Updated Party API with the following changes:
- SM-8163: Add a 30s timeout to party api endpoints
Updated Work API with the following changes:
-
SM-8654: Changed
PUT /works/{workReferenceNumber}/excavation-carried-out
to recalculateinspection_units
when theexcavation_carried_out
value differs between the active permit and request. Also madeGET /workReferenceNumber
to always returninspection_units
and changed when creating a work to default the number ofinspection_units
to 0 instead of 1.
Updated Sampling API with the following changes:
-
SM-8670: Updated
POST /sample-inspection-targets
to set thefinancial_quarter_id
to the ID of the active quarter if one has been started. -
SM-9190: Updated
POST /sample-inspections/end-quarter
to save the current date and time at which the quarter was ended. -
SM-9580: Updated
POST /sample-inspections/end-quarter
to correctly retrieve theorganisation_id
's of the organisations for which targets had been created when copying targets when the quarter was ended.
Version 4.15.2 (02/02/2023)
Updated Work API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version -
SM-8641: Updated
POST /ancillary-informations
to no longer requirelocation_description
as a mandatory field whenancillary_info_type
isportable_traffic_signals_or_other_traffic_controls
-
SM-6385: Bug fix addressing issue on endpoint
PUT {workReferenceNumber}/start
where the sliding date calculation would estimate the end date to be on a weekend when works was started after the proposed start date in some scenarios. Now the end date slides to accommodate the later starting date.
Updated Data Export API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version -
SM-8431: Added additional optional filtering to the
POST /inspections/csv
endpoint. New filter params includes:promoter_outcome_status
ha_outcome_status
Updated Event API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version
Updated GeoJSON API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version
Updated Party API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version
Updated Reporting API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version -
SM-8431: Added additional optional filtering to the
GET /inspections
endpoint. New filter params includes:promoter_outcome_status
ha_outcome_status
Updated Sampling API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version
Updated Street Lookup API with the following changes:
-
SM-8558: Updated
jsonwebtoken
version
Version 4.15.1 (19/01/2023)
Updated GeoJSON API with the following changes:
-
SM-8269: Updated
GET /ancillary-informations
endpoint to return optional fieldswork_reference_number
andpermit_reference_number
.
Updated Reporting API with the following changes:
-
SM-8367: Added new
GET /pbi-sample-inspection-targets
endpoint to return a list of active sample inspection targets for the user's organisation. -
SM-8367: Added new
GET /pbi-sample-inspections
endpoint to return a list of sample inspections due.
Updated Data Export API with the following changes:
-
SM-8369: Added new
POST /pbi-sample-inspections-due/csv
endpoint to generate a CSV of sample inspections due. -
SM-7635: Updated endpoint
POST fees/csv
to includestandard_fee
,cost
andchallenge_reason
in CSV export and also reordered columns.
Updated Work API with the following changes:
-
SM-8391: Bug fix addressing issue where
GET/ forward-plans
requests were returningupcoming-enum
fornull
values oftraffic_management_type
. -
SM-7654: Updated endpoints
POST /works/{workReferenceNumber}/permits
,PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status
,PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
to calculate thestandard_fee
andtotal_cost
of the PAA, PA, and Change request. -
SM-8542: (BREAKING CHANGE):
POST works/{workReferenceNumber}
andPOST works/{workReferenceNumber}/permits
now supportsNCT03
as a permit condition. -
SM-7443: Updated
POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
to address a bug where a site can be changed from interim to permanent without creating a new phase.
Updated Sampling API with the following changes:
-
SM-8465: Added new
GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
endpoint to return aSampleInspectionTargetResponse
containing information about an individual target.
Version 4.15 (08/12/2022):
Updated GeoJSON API with the following changes:
-
SM-8269: Added new
GET /ancillary-informations
endpoint to retrieve ancillary informations within a given bounding box.
Updated Work API with the following changes:
-
SM-8442:
AncillaryInfoSummaryResponse
updated to makedate_removed
andancillary_info_removal_reason
optional. The limit for ancillary informations has also been updated to be a maximum of 20 per permit, rather than 20 per work. -
SM-8499: Updated endpoint
GET /works/{workReferenceNumber}
to return a new optionalpbi_sample_inspections
property when issued PBI sample inspections exist for the Work. -
SM-8413: Updated
POST /works/{workReferenceNumber}/inspections
to update PBI sample inspection target progress and sample inspection status when creating an inspection, also updated to prevent Cat B or C when scheduling another inspection as part of the create journey. UpdatedPOST /works/{workReferenceNumber}/scheduled-inspections
to prevent Cat B or C inspections as thescheduled_inspection_category
Updated Data Export API with the following changes:
-
SM-8411: Updated endpoint
POST /section-58s/csv
to make use ofswa_code
so that a contractor can export section 58s. -
SM-6390: Added additional optional filter param to the
InspectionCSVExportRequest
model used by thePOST /inspections/csv
endpoint. New filter param includes:inspection_category
Updated Reporting API with the following changes:
- SM-6390: Added additional optional filtering to the
GET /inspections
endpoint. New filter params includes:inspection_category
Updated Sampling API with the following changes:
-
SM-8365: Added new endpoint
POST /sample-inspections/end-quarter
to end a sample inspection quarter -
SM-8485: Updated validation on
POST /sample-inspection-targets
andPUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to allow targets of 0 when calculated quarterly quota is less than 20.
Version 4.14 (24/11/2022):
Updated Reporting API with the following changes:
-
SM-8308: Updated endpoint
GET /section-81s
to ensuresection_81_severity
andsection_81_severity_string
are now optional and will be returned asnull
ifsection_81_type
isunattributed_works_live_site
orunattributed_works_completed
. -
SM-8402: Updated
GET /inspections
to return new inspection outcome response fields:promoter_response_status_id
,promoter_response_status_string
,ha_response_status_id
andha_response_status_string
. Promoter fields are only returned ifpromoter_response_status_id
is populated and Highway authority fields are only returned ifha_response_status_id
is populated. -
SM-8378: Updated
POST /works
,POST /works/{workReferenceNumber}/permits
andPOST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
to makeclose_footpath
mandatory
Updated Work API with the following changes:
-
SM-8435: Added new endpoint
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations/{ancillaryInformationReferenceNumber}
which will allow a Planner, Contractor OR Highway Authority to get an Ancillary Information and all associated data. -
SM-8402: Updated
GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
to return new inspection outcome response fields:promoter_response_status_id
,promoter_response_status_string
,promoter_response_status_change_date
,promoter_reason_for_dispute
,ha_response_status_id
,ha_response_status_string
,ha_response_status_change_date
andha_reason_for_accepting
. Promoter fields are only returned ifpromoter_response_status_id
is populated, additionallypromoter_reason_for_dispute
is only returned ifpromoter_response_status_id
is a value ofinspection_outcome_disputed
. Highway authority fields are only returned ifha_response_status_id
is populated.
Updated Sampling API with the following changes:
-
SM-8358: Added new endpoint
DELETE /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to delete sample inspection targets -
SM-8384: Added new endpoint
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
to update sample inspection targets -
SM-8356: Added new endpoint
POST /sample-inspections/start-quarter
to start a sample inspection quarter
Version 4.13 (10/11/2022):
Updated Sampling API with the following changes:
-
SM-8362: Added new endpoint
POST /sample-inspections
to start the sample inspection generation process. - SM-8398: Add a 30s timeout to sampling api endpoints
Updated Street Lookup API with the following changes:
- SM-8164: Add a 30s timeout to street lookup api endpoints
Updated Work API with the following changes:
-
SM-8375: Added new endpoint
PUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/status
which will allow a Planner, Contractor or Highway Authority to update a failed inspection's outcome response. -
SM-8267: Added new endpoint
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations/{ancillaryInformationReferenceNumber}/remove
which will allow a Planner or Contractor to mark Ancillary Information as removed. -
SM-8300:
PUT works/{workReferenceNumber}/inspection-units
is now hidden. Inspection units are now automatically updated by the system. This endpoint will be removed in future. -
SM-8265: Added
current_traffic_management_type
,current_traffic_management_type_ref
andcurrent_traffic_management_update_date
to open data notifications.
Updated Data Export API with the following changes:
-
SM-7860: Added new endpoint
POST /reinstatements/expiring-interims/csv
. This endpoint will generate a csv of expiring interim reinstatements
Updated Reporting API with the following changes:
-
SM-7860: Added new endpoint
GET /reinstatements/expiring-interims
. This endpoint will return expiring interim reinstatements only.
Version 4.12 (27/10/2022):
Updated Work API with the following changes:
-
SM-6893: Updated Work API for the
POST /works/{workReferenceNumber}/permits
endpoint so that when works_coordinates and permit_coordinates are missing from request and active permit respectively, an error 400 (Bad Request) is thrown rather than an error 500 (Internal Server Error). -
SM-8237: Added new a new
traffic_management_type
,temporary_obstruction_15_minute_delay
. Added new optional propertyclose_footpath
toWorkCreateRequest
andPermitRequest
.close_footpath
can be one of two enum values,yes_discussed_with_ha
orno
. -
SM-8341: Added new endpoint
GET /fee-matrix/{organisationReference}
to the Work API. This takes a Highway Authority SWA code and will return a Fee Matrix if one exists for the given organisation. -
SM-8266: Added new endpoint
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations
to create an ancillary information for a permit. -
SM-8268: Updated endpoint
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
to retrieve all ancillary information for a permit.
Updated Sampling API with the following changes:
-
SM-8281: New Endpoint added to Sampling API that calculates the quarterly sample quota -
GET /sample-inspection-quota
-
SM-8355: New Endpoint added to Sampling API that creates sample inspection targets -
POST /sample-inspection-targets
Updated Data Export API with the following changes:
- SM-8161: Add a 30s timeout to all data export api endpoints
Version 4.11 (13/10/2022):
New Sampling API created:
- SM-6924: Created a new Sampling API. No usable endpoints have been created so far but will be added in future releases.
Updated Street Reporting API with the following changes:
-
SM-8313: Changed the validation of the
permit_alteration_reference_number
parameter for theGET /alterations
endpoint from a max length of 105 characters to 100 characters. - SM-8160: Add a 30s timeout to all reporting api endpoints
Updated Street Lookup API with the following changes:
-
SM-8193: Updated the
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/status
endpoint to only allowwork_type = permit_works
when accepting unattributed works.
Updated Work API with the following changes:
-
SM-7800:
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}
replaced withPOST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/impose
for changes imposed by HA officers. -
SM-8371: Deprecated the following endpoints:
POST /works/sample-inspection-targets
GET /works/sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
PUT /works/sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
PUT /works/sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
POST /works/sample-inspection
-
SM-8278: Updated
PUT /works/{workReferenceNumber}/stop
andPUT /works/{workReferenceNumber}/revert-stop
to calculate inspection units for a work upon the works stop/revert stop being submitted. This will also update the inspection units on the work to reflect the calculated total, and update the annual inspection unit count for the promoter/HA organisation pairing for the financial year in which the works stop was registered.
Updated Data Export API with the following changes:
-
SM-8261: Includes the following changes:
- Updated exported Permit CSVs to include the additional columns 'Current traffic management type', 'current traffic management update date' 'Current traffic management emergency contact name' and 'Current traffic management emergency contact number'
- Updated the 'Download all my data' export to include the additional columns
current_traffic_management_type_id
,current_traffic_management_update_date
,current_traffic_management_emergency_contact_name
andcurrent_traffic_management_emergency_contact_number
inpermit.csv
Updated Event API with the following changes:
-
SM-8159: Updated
GET /works/updates
andGET /healthcheck
to timeout after 30 seconds.
Updated GeoJSON API with the following changes:
- SM-8162: Add a 30s timeout to all geojson api endpoints
Version 4.10 (29/09/2022):
Updated Street Lookup API with the following changes:
-
SM-8229: Replaced
GET /nsg/streets
endpoint with newPOST /nsg/streets/search
endpoint. This endpoint accepts aStreetsRequest
as its request body, containing an array of coordinates to search for. See 'Get streets endpoint (coordinates)' section in the Resource Guide for more information.
Updated Work API with the following changes:
-
SM-8135:
POST works/{workReferenceNumber}
andPOST works/{workReferenceNumber}/permits
now supportsNCT09d
as a permit condition.
Updated Reporting API with the following changes:
-
SM-8187: Removed
query
query parameter from all endpoints exceptGET /activities
.
Updated Data Export API with the following changes:
-
SM-8187: Removed
query
fromBaseCSVExportRequest
on all endpoints.
Version 4.9 (15/09/2022):
Updated Event API with the following changes:
-
SM-7864: Added
site_subsumed
andinspection_deleted
toAuditEvent
enum. Correctedpermit_duration_non_acceptance_response
to bepermit_duration_challenge_non_acceptance_response
Updated Work API with the following changes:
-
SM-7864: Added
site_subsumed
andinspection_deleted
toAuditEvent
enum. Correctedpermit_duration_non_acceptance_response
to bepermit_duration_challenge_non_acceptance_response
-
SM-8232: Includes the following changes:
- Added a new endpoint
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/current-traffic-management-type
to allow for the update of a permit's current traffic management details. - Updated
PermitResponse
to returncurrent_traffic_management_type
,current_traffic_management_type_string
,current_traffic_management_emergency_update_date
,current_traffic_management_emergency_contact_name
andcurrent_traffic_management_emergency_contact_number
- Added a new endpoint
Updated Reporting API with the following changes:
-
SM-7932: Updated
GET /section-58s/list
to add additionalsection_58_reference_number
,USRN
andstreet_descriptor
filters. -
SM-7864: Added
site_subsumed
andinspection_deleted
toAuditEvent
enum. Correctedpermit_duration_non_acceptance_response
to bepermit_duration_challenge_non_acceptance_response
Updated Data Export API with the following changes:
-
SM-7932: Updated
POST /section-58s/csv
to add additionalsection_58_reference_number
,USRN
andstreet_descriptor
filters.
Version 4.8 (01/09/2022):
Updated all APIs with the following changes:
- SM-7351: Replaced component that handles HTTP header caching
Updated Reporting API with the following changes:
-
SM-7971:
is_active_reinstatement
andis_subsumed
are now required properties inReinstatementReportingResponse
-
SM-7903: Includes the following changes:
- Updated
GET /fixed-penalty-notices
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters. - Updated
GET /inspections
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters. - Updated
GET /sample-inspections
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters.
- Updated
Updated Work API with the following changes:
-
SM-7971:
is_active_reinstatement
is now a required property inReinstatementResponse
-
SM-6535: Added
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/impose
endpoint to allow HA users to impose a change on a permit
Updated Data Export API with the following changes:
-
SM-7903: Includes the following changes:
- Updated
GET /fixed-penalty-notices
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters. - Updated
GET /inspections
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters. - Updated
GET /sample-inspections
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters.
- Updated
Version 4.7 (18/08/2022):
Updated Reporting API with the following changes:
-
SM-5195: Updated
GET /section-81s
to add additionalsection_81_type
filter and addedsection_81_type
andsection_81_type_string
to the response. -
SM-7623:
site_number
is no longer returned inReinstatementReportingResponse
. -
SM-7904: Includes the following changes:
- Updated
GET /reinstatements
to add additionalstreet_descriptor
,usrn
,work_reference_number
andwork_reference_number_exact
filters. - Updated
GET /section-81s
to add additionalstreet_descriptor
,usrn
andsection_81_reference_number
filters.
- Updated
Updated Work API with the following changes:
-
SM-7623:
site_number
is no longer returned as part offailure_reason_details
inInspectionResponse
. - SM-7779: Added rate limits to non-authenticated endpoints including authentication and file upload
Updated Party API with the following changes:
- SM-7779: Added rate limits to non-authenticated endpoints including password reset
Updated Data Export API with the following changes:
-
SM-5195: Updated
POST /section-81s/csv
to add additionalsection_81_type
filter. -
SM-7904: Includes the following changes:
- Updated
POST /reinstatements/csv
to add additionalstreet_descriptor
,usrn
andwork_reference_number
filters. - Updated
POST /section-81s/csv
to add additionalstreet_descriptor
,usrn
andsection_81_reference_number
filters.
- Updated
Version 4.6 (04/08/2022):
Updated Event API with the following changes:
-
SM-6792: Added
GET /works/updates
endpoint. This endpoint functions in the same way as theGET /works/updates
endpoint on the Reporting API, except for the following:previous_minutes
param has been removed- Maximum allowed range between
start_date
andend_date
has been reduced from 24 hours to 12 hours
Updated Reporting API with the following changes:
-
SM-6792: Removed
GET /works/updates
andPOST /permits/search
endpoints. -
SM-7902: Includes the following changes:
- Updated
GET /forward-plans
to add additionalstreet_descriptor
,usrn
andforward_plan_reference_number
filters. - Updated
GET /alterations
to add additionalstreet_descriptor
,usrn
andpermit_alteration_reference_number
filters.
- Updated
Updated Data Export API with the following changes:
-
SM-7902: Includes the following changes:
- Updated
POST /forward-plans/csv
to add additionalstreet_descriptor
,usrn
andforward_plan_reference_number
filters. - Updated
POST /alterations/csv
to add additionalstreet_descriptor
,usrn
andpermit_alteration_reference_number
filters.
- Updated
-
SM-7622: Removed column 'Is environmental health notifiable?' from exported permit CSVs. This has also been removed from 'Download all my Data'
permit_version.csv
Updated Work API with the following changes:
-
SM-7238: Modified
GET /works/{workReferenceNumber}
to make use ofsection_81_type
andsection_81_type_string
. -
SM-7974: Updated
GET works/{workReferenceNumber}/permits/{permitReferenceNumber}
,GET works/{workReferenceNumber}/sites/{siteReferenceNumber}
andGET works/{workReferenceNumber}
to timeout after 30 seconds. -
SM-8012: Update POST
/works/{workReferenceNumber}/permits
to allow for an incoming permit to be accepted by the system if it has the sameworkstream_prefix
as a permit currently on the works record. The permit can also be rejected if it has a differentworkstream_prefix
than the one currently on the works record.
Version 4.5 (21/07/2022):
New Event API created:
- SM-6924: Created a new Event API. No usable endpoints have been created so far but will be added in future releases.
Updated Reporting API with the following changes:
-
SM-7953: Updated
GET /reinstatements
to excludereinstatement_date
andend_date
when a site is subsumed and the reinstatement is active. -
SM-7901: Updated
GET /permits
to add awork_reference_number
filter.
Updated Work API with the following changes:
-
SM-7953: Updated
GET /works/{workReferenceNumber}/sites/{siteReferenceNumber}
to excludecompleted_date
,reinstatement_date
andend_date
when a site is subsumed. -
SM-8121: Fixed a bug that was stopping Highway Authority users imposing changes via
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alteration
on works that did not haveemergency contacts
because they were created on v3. Included in this was a small fix that stops Highway Authority users editing more than thepermit_conditions
in a HA imposed change.
Updated Data Export API with the following changes:
-
SM-7901: Updated
POST /permits/csv
to add awork_reference_number
filter.
Version 4.4 (07/07/2022):
Updated Reporting API with the following changes:
-
SM-6243: Update
GET /works/updates
to correctly populateevent_type
when value isinspection_agreed_site_compliance
. -
SM-7900: Updated
GET /permits
to add separatestreet_descriptor
,usrn
andpermit_reference_number
filters.
Updated Work API with the following changes:
-
SM-8034: Updated
emergency_contact_name
andemergency_contact_number
to be required when traffic management type is multi-way signals or two-way signals. -
SM-7926: Updated
activity_type
to be mandatory inGetWorkCategoryRequest
.
Updated Data Export API with the following changes:
-
SM-6290: Corrected column headers in the Download all my data forward_plan.csv to match data from
hs2_in_act_limits
,hs2_highway_exemption_id
,hs2_consultation_requested_response_date
,hs2_forward_plan_work_type_id
tohs2_forward_plan_work_type_id
,hs2_in_act_limits
,hs2_highway_exemption_id
,hs2_consultation_requested_response_date
. -
SM-7900: Updated
POST /permits/csv
to add additionalstreet_descriptor
,usrn
andpermit_reference_number
filters.
Version 4.3 (23/06/2022):
Updated Data Export API with the following changes:
-
SM-7905: Updated
POST /section-74s/csv
to add additionalstreet_descriptor
,usrn
andsection_74_reference_number
filters.query
will no longer filter on this endpoint.
Updated Reporting API with the following changes:
-
SM-7905: Updated
GET /section-74s
to remove thequery
filter and add separatestreet_descriptor
,usrn
andsection_74_reference_number
filters.
Updated Work API with the following changes:
-
SM-7987: Increased character limit on
emergency_contact_number
, inWorkCreateRequest
andPermitRequest
, from 20 to 100 characters.
Updated Party API with the following changes:
-
SM-7987: Increased character limits on
emergency_contact_name
andemergency_contact_number
, inWorkstreamCreateRequest
andWorkstreamUpdateRequest
, to 100 characters.
Version 4.2 (09/06/2022):
Updated Work API with the following changes:
-
SM-7937: Changes to
POST /section-81-works/section-81s
to allow adding of unattributed works via the API.section_81_severity
andmade_safe_by_ha
will be optional in the create request ifsection_81_type
isunattributed_works_live_site
orunattributed_works_completed
.
Version 4.1 (26/05/2022):
Updated Work API with the following changes:
-
SM-7883: Updated
WorkCreateRequest
,PermitRequest
andPermitResponse
to include the following optional properties:emergency_contact_name
emergency_contact_number
-
SM-7610: Added
DELETE /works/{workReferenceNumber}/fixed-penalty-notices/{fpnReferenceNumber}
endpoint to allow HAs to delete an FPN.
Version 4.0 (12/05/2022):
Released V4 of all APIs. Decommissioned V2 of all APIs.
Version 3.15.11 (28/04/2022):
Updated Work API with the following changes:
-
SM-7826: Updated
PUT /section-58s/{section58ReferenceNumber}/status
so only fields relevant to the updated status will be mapped. E.g.cancellation_reason
will only be updated when the Section 58 update status iscancelled
. -
SM-6802: Update
ReinstatementResponse
to return a new optionalis_active_reinstatement
property.
Updated Reporting API with the following changes:
-
SM-6802: Update
ReinstatementReportingResponse
to return new optionalis_active_reinstatement
andis_subsumed
properties.
Updated Data Export API with the following changes:
-
SM-7935: Update the following endpoints to include optional
organisation
property to enable filtering CSV exports by organisation name in line with the recent changes to Reporting API endpoints./section-81s/csv
/reinstatements/csv
/fixed-penalty-notices/csv
/permits/csv
/inspections/csv
/forward-plans/csv
/alterations/csv
/comments/csv
/section-74s/csv
/sample-inspections-due/csv
query
filter on the/comments/csv
is no longer ignored. This will now filter by the street, town, area and USRN associated with the works.
Version 3.15.10 (14/04/2022):
Updated Party API with the following changes:
-
SM-7882: Added
emergency_contact_name
&emergency_contact_number
properties toworkstreamCreateRequest
,workstreamUpdateRequest
andworkstreamResponse
to allow admin and planner users to add emergency contact name and number for specific workstreams.
Updated Work API with the following changes:
-
SM-6801: Added new
PUT /works/{workReferenceNumber}/sites/{siteReferenceNumber}/subsume
endpoint to subsume a site. Changes made toSiteSummaryResponse
andReinstatementResponse
to indicate if a site has been subsumed. If a site is subsumedreinstatement_date
andend_date
will be null. Business rules changed to prevent adding a reinstatement to a subsumed site. -
SM-7944: SM-6801 introduced a possible breaking change where
reinstatement_date
andend_date
will be null if a site is subsumed. This has now been resolved and thereinstatement_date
andend_date
will retain their previous value when a site is subsumed. -
SM-7863: Changes made to
GetWorkCategoryRequest
to include an optionalactivity_type
. This will be used to progress a forward plan as a major if the duration is a major category and the activity type isoptional_permit_no_fee
. The business rules have been updated to align with this change.
Updated Reporting API with the following changes:
-
SM-7844: Updated
GET /workstreams
endpoint to returnorganisation_reference
padded to four characters.
Version 3.15.9 (31/03/2022):
Updated Reporting API with the following changes:
-
SM-7907: Change made to
POST /permits/search
to increase the maximumpage_size
value from 250 to 500.
Version 3.15.8 (17/03/2022):
Updated Reporting API with the following changes:
-
SM-7724: Change made to
GET /sample-inspection-targets
to remove inspections with an outcome status ofunable_to_complete
from sample inspection completed count. -
SM-7804: Added
GET /permits/duration-challenges
endpoint which returns permits that have been duration challenged. -
SM-7843: Added
GET /alterations/duration-challenges
endpoint which returns permit alterations that have been duration challenged.
Updated Work API with the following changes:
-
SM-7823: Change made to
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-review
andPUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-non-acceptance-response
to prevent the duration challenge non acceptance process from being started or continued if the related permit is closed. -
SM-7612: Added new
DELETE /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
endpoint to allow HAs to delete an inspection.
Updated Reporting API with the following changes:
-
SM-7760: Added
organisation
query parameter to theGET /section-74s
,GET /section-81s
andGET /reinstatements
endpoints to allow section 74s, section 81s and reinstatements to be filtered by organisation name. The parameter will filter section 74s, section 81s and reinstatements by Local Authority name for promoter / contractor users, and by Promoter name for HA users.
Version 3.15.7 (03/03/2022):
Updated Work API with the following changes:
-
SM-7735: Change made to
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status
to allow alterations to be duration challenged when the reasonable period end date has changed.
Updated Reporting API with the following changes:
-
SM-7758: Added
organisation
query parameter to theGET /fixed-penalty-notices
,GET /inspections
andGET /sample-inspections
endpoints to allow FPNs, Inspections and Sample Inspections to be filtered by organisation name. The parameter will filter by Local Authority name for promoter / contractor users, and by Promoter name for HA users. -
SM-7781: Added
page_size
query parameter to theGET /works/updates
andPOST /permits/search
endpoints to allow a page size between 100 and 250 to be requested, it will default to 100 if not specified.
Version 3.15.6 (17/02/2022):
Updated Reporting API with the following changes:
-
SM-7770: Added
organisation
query parameter to theGET /alterations
andGET /forward-plans
endpoints to allow forward plans and permit alterations to be filtered by organisation name. The parameter will filter forward plans and permit alterations by Local Authority name for promoter / contractor users, and by Promoter name for HA users.
Version 3.15.5 (03/02/2022):
Updated Work API with the following changes:
- SM-7759: Fixed a bug where previously inactive, disabled accounts are disabled again each evening after being re-invited and logging in.
Version 3.15.4 (20/01/2022):
Updated Work API with the following changes:
-
SM-7716 (BREAKING CHANGE): Updated the maximum duration validation to prevent a works actual end date being more than 5 years after the actual start date as well as actual start date being more than 5 years after proposed start date. This affects
PUT /works/{workReferenceNumber}/stop
andPUT /works/{workReferenceNumber}/start
endpoints.
Updated Data Export API with the following changes:
-
SM-6970: Added a new
POST /sample-inspections-due/csv
endpoint to trigger the generation of a CSV of sample inspections.
Version 3.15.3 (06/01/2022):
Updated Reporting API with the following changes:
-
SM-6834: Added
organisation
query parameter to theGET /permits
endpoint to allow permits to be filtered by organisation name. The parameter will filter permits by Local Authority name for promoter / contractor users, and by Promoter name for HA users.
Updated Data Export API with the following changes:
-
SM-6788: Added a new
POST /section-74s/csv
endpoint to trigger the generation of a CSV of Section 74s.
Version 3.15.2 (09/12/2021):
Updated Reporting API with the following changes:
-
SM-7643: Added
GET /activities
endpoint to allow a list of Activities to be retrieved
Version 3.15.1 (25/11/2021):
Updated Work API with the following changes:
-
SM-7670: Moved
permit_reference_number
property toSection74SummaryResponse
which forms part of theWorkResponse
. This means that the endpointGET /works/{workReferenceNumber}
will now return the permit reference number associated with the Section 74. -
SM-6511: Added
DELETE /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements/{reinstatementReferenceNumber}
to allow the deletion of reinstatements created in error. Two new audit events will be returned in the work historyreinstatement_deleted
andsite_deleted
to record the deletions. Reference numbers of deleted sites/reinstatements will never be re-used, any subsequently created site/reinstatement will not take the reference number of the previously deleted site/reinstatement. Any inspections with non compliant sites will still show that the deleted site was non-compliant. -
SM-7596: Updated the
GET /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}
endpoint to only return fields relevant to the current HA and Promoter statuses.
Updated Reporting API with the following changes:
-
SM-7651: Added
activity_type
andactivity_type_string
properties toPermitSummaryResponse
which forms part of the response from theGET /permits
endpoint. -
SM-6629: Added
work_reference_number
andpermit_reference_number
properties toSection74SummaryResponse
which forms part of the response from theGET /section-74s
endpoint. -
SM-6511: The
GET /works/updates
endpoint will returnreinstatement_deleted
andsite_deleted
to relating to reinstatement/site deletions.
Updated GeoJSON API with the following changes:
-
SM-6785: Added a new
GET /section-58s
endpoint to allow Section 58s within a given bounding box to be retrieved.
Updated Data Export API with the following changes:
-
SM-6788: Added a new
POST /section-58s/csv
endpoint to trigger the generation of a CSV of Section 58s.
Version 3.14 (11/11/2021):
Updated Work API with the following changes:
-
SM-7626: Updated the
POST /section-58
andGET /section-58/{section58ReferenceNumber}
endpoints to be pluralised in line with other endpoints. They are nowPOST /section-58s
andGET /section-58s/{section58ReferenceNumber}
. No behavioural changes. -
SM-6884: Removed the
environmental_health_notifiable
property from all requests and responses in the V3 API. V3 (and UI) will now default this to false. -
SM-7604: Updated the following endpoint URLs to include site reference number rather than site number:
GET /works/{workReferenceNumber}/sites/{siteNumber}
is nowGET /works/{workReferenceNumber}/sites/{siteReferenceNumber}
POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
is nowPOST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
404 NOT FOUND
error. -
SM-7604: Replaced the
site_numbers
property withsite_reference_numbers
in theFailureReasonDetails
model.failure_reason_details
provided as part of the request to thePOST /works/${workReferenceNumber}/inspections
endpoint should now includesite_reference_numbers
rather thansite_numbers
. -
SM-7604: Added
site_reference_number
to theSiteDetails
model. For all inspections created from this version onwards,site_reference_number
will be returned as part of thefailure_reason_details
property from theGET /works/${workReferenceNumber}/inspections/${inspectionReferenceNumber}
endpoint. For inspections created before the release of this version,site_number
will be returned instead. - SM-7604: Updated
WorkHistorySummaryResponse
object_reference
property to returnsite_reference_number
when a new site/reinstatement has been created.
Updated Reporting API with the following changes:
-
SM-6682: Added
GET /section-58s
endpoint to allow a list of Section 58s to be retrieved
Version 3.13 (28/10/2021):
Updated Work API with the following changes:
-
SM-7552: A reference number will be generated when creating a site or adding a reinstatement to an existing site. The affected endpoints are as follows:
-
site_reference_number
andreinstatement_reference_number
will now be returned byPOST /works/{workReferenceNumber}/sites
as part of theSiteCreateResponse
-
site_reference_number
andreinstatement_reference_number
will now be returned byPOST /non-notifiable-works/sites
as part of theNonNotifiableSiteCreateResponse
-
reinstatement_reference_number
will be returned byPOST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
as part of the newReinstatementCreateResponse
-
site_reference_number
andreinstatement_reference_number
have been added to theSiteSummaryResponse
and will contain the values for the most recently created reinstatement.reinstatement_reference_number
has also been added to theReinstatementResponse
. These will now be returned byGET /works/{workReferenceNumber}/sites/{siteNumber}
-
- SM-6787: Added a new endpoint to enable HA users to change the status of a Section 58 -
PUT /section-58s/{section58ReferenceNumber}/status
.
Updated Reporting API with the following changes:
-
SM-7552: Added
site_reference_number
andreinstatement_reference_number
properties toReinstatementSummaryResponse
models. This change affects theGET /reinstatements
endpoint
Version 3.12 (14/10/2021):
Updated Work API with the following changes:
- SM-6434: Added a new endpoint to the V3 Works API to enable HA Officer users to issue Section 58 warnings -
POST /section-58
. - SM-6786: Added a new endpoint to the V3 Works API to enable users to get details of Section 58 warnings -
GET /section-58/{section58ReferenceNumber}
.
Version 3.11 (30/09/2021):
Updated Reporting API with the following changes:
- SM-7509: The
WorkUpdateReportingResponse
next_update
property is now correctly marked as optional, but there are no behavioural changes. This is on theGET /works/updates
endpoint. - SM-3363:
PermitSummaryResponse
has been updated to returnpaa_to_pa_deadline_date
on thePOST /permits/search
andGET /permits
endpoints.
Updated Work API with the following changes:
- SM-3363: PAA to PA submission deadline date is now calculated as the proposed start date of the work minus 11 working days.
-
SM-7437:
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
has been updated so that changes toreasonable_period_end_date
are flagged as a difference. This fixes an issue where an error was returned ifreasonable_period_end_date
was the only change. This is a behavioural change only.
Version 3.10 (16/09/2021):
Updated Work API with the following changes:
- SM-7010: Updated the
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
endpoint to limit the number of permit alterations returned from a permit response to the latest 50. Permit alterations are also limited to the latest 50 for theoriginal
andproposed
PermitResponse
properties in the permit alteration response returned fromGET /works/${workReferenceNumber}/permits/${permitReferenceNumber}/alterations/${permitAlterationReferenceNumber}
. -
SM-7060: Added
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-non-acceptance-response
endpoint to allow a Highway Authority user to respond to a duration challenge non-acceptance review on an immediate permit. AdditionallyPermitResponse
andPermitAlterationResponse
have been updated to returnduration_challenge_non_acceptance_response_old_reasonable_period_end_date
. -
SM-6004: Fixed a bug with work extensions on works in progress to not require early start information if the permit did not originally have an early start. The flag
is_early_start
is set to false if the work is in progress. This affects the following endpoints:GET /permits/category
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
Version 3.9 (03/09/2021):
Updated Work API with the following changes:
- SM-6738: Updated the
GET /works/{workReferenceNumber}/sites/{siteNumber}
endpoint to limit the number of reinstatements returned from a site response to the latest 50. -
SM-7061: Added
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/duration-challenge-review
endpoint to allow promoters to submit duration challenge reviews on immediate permits. The following fields are also now returned in thePermitResponse
:duration_challenge_review_status
duration_challenge_review_status_string
duration_challenge_reason_for_non_acceptance
duration_challenge_review_update_date
duration_challenge_non_acceptance_response_status
duration_challenge_non_acceptance_response_status_string
duration_challenge_non_acceptance_response_details
duration_challenge_non_acceptance_response_update_date
duration_challenge_non_acceptance_response_new_reasonable_period_end_date
duration_challenge_follow_up_review_complete
- SM-6766: Logic added to prevent users belonging to disabled organisations from performing any read/write actions. Also to prevent contractor orgs from performing any read/write actions on disabled organisations records.
Updated Reporting API with the following changes:
- SM-6766: Logic added to prevent users belonging to disabled organisations from performing any read/write actions. Also to prevent contractor orgs from performing any read/write actions on disabled organisations records.
- SM-6708: A new
GET /section-74s
endpoint has been added to allow a list of Section 74s to be retrieved.
Updated Party API with the following changes:
- SM-6766: Logic added to prevent users belonging to disabled organisations from performing any read/write actions. Also to prevent contractor orgs from performing any read/write actions on disabled organisations records. The
GET /organisations
endpoint will not return disabled organisations.
Updated Data Export API with the following changes:
- SM-6766: Logic added to prevent users belonging to disabled organisations from performing any read/write actions. Also to prevent contractor orgs from performing any read/write actions on disabled organisations records.
- SM-7370: CSVs generated via the
POST /*/csv
endpoints, and retrieved via thePOST /csv/{csvId}
endpoint now have any values within the CSV which could potentially contain formulas 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
.
Updated Street lookup API with the following changes:
- SM-6766: Logic added to prevent users belonging to disabled organisations from performing any read/write actions. Also to prevent contractor orgs from performing any read/write actions on disabled organisations records.
Updated Geojson API with the following changes:
- SM-6766: Logic added to prevent users belonging to disabled organisations from performing any read/write actions. Also to prevent contractor orgs from performing any read/write actions on disabled organisations records.
Version 3.8 (19/08/2021):
Updated Work API with the following changes:
-
SM-7401: Updated
POST /works/{workReferenceNumber}/section-74s
endpoint to allow an additional Section 74 to be added to a permit if all others are withdrawn i.e.ha_status=withdrawn
. - SM-6706:
WorkResponse
has been updated to returnsection74s
property which is an array ofSection74SummaryResponse
responses. These have been limited to 50 and ordered by date created. -
SM-7023: Added
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-non-acceptance-response
endpoint to enable a Highway Authority user to respond to a duration challenge review request. - SM-6736: A limit restricting the number of files which can be associated with an entity has been introduced. This will mean the
file_ids
array will need to be less than 50. This affects the following endpoints:POST /works/{workReferenceNumber}/files
POST /works
POST /works/{workReferenceNumber}/permits
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
POST /works/{workReferenceNumber}/fixed-penalty-notices
POST /historic-works/fixed-penalty-notices
POST /historic-works/inspections
POST /works/{workReferenceNumber}/inspections
POST /non-notifiable-works/sites
POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
POST /works/{workReferenceNumber}/sites
POST /works/{workReferenceNumber}/section-74s
POST /section-81-works/section-81
- SM-6521: The logic to extend the end date when a permit is started within the validity period has been updated to include all road types.
The following rules now apply:
- The end date cannot extend for road categories 1, 2, 5 and 10
- The end date cannot extend for road categories 3 and 4 that are also traffic sensitive
- The end date can extend for road categories 3 and 4 that are not traffic sensitive
- The end date can extend for road categories 6, 7, 8 and 9 regardless of traffic sensitivity
Updated GeoJson API with the following changes:
- SM-7388: New required parameter
phase
added toGET /hs2-act-limits
endpoint to allow selection of HS2 Phase 1 or HS2 Phase 2a act limits.
Version 3.7 (05/08/2021):
Updated Reporting API with the following changes:
- SM-6890: Updated
GET /works/updates
endpoint andPOST /permits/search
endpoint to use cursor-based pagination. More information on this can be found in the Resource Guide.
Updated Work API with the following changes:
- SM-6724: Added
PUT /works/${workReferenceNumber}/section-74s/${section74ReferenceNumber}/promoter-status
endpoint to enable a Planner user to update the status of a Section 74. - SM-7022: Added
PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/duration-challenge-review
endpoint to enable a Planner user to accept or not accept a duration challenge. The following fields are returned in the PermitAlterationResponse:duration_challenge_review_status
duration_challenge_review_status_string
duration_challenge_reason_for_non_acceptance
duration_challenge_review_update_date
duration_challenge_non_acceptance_response_status
duration_challenge_non_acceptance_response_status_string
duration_challenge_non_acceptance_response_details
duration_challenge_non_acceptance_response_update_date
duration_challenge_non_acceptance_response_new_reasonable_period_end_date
duration_challenge_follow_up_review_complete
- SM-6733: Updated the
GET /works/{workReferenceNumber}
to limit the number of permits returned from a work response to the latest 50. The full list can be retrieved using theGET /permits
endpoint on Reporting API. - SM-6733: Added
GET /works/${workReferenceNumber}/earliest-permit
endpoint which returns the summary details of the permit with the earliest actual start date for a given work.
Version 3.6 (22/07/2021):
Updated Work API with the following changes:
- SM-6723: Added
PUT /works/${workReferenceNumber}/section-74s/${section74ReferenceNumber}/highway-authority-status
endpoint to enable a HA user to update the status of Section 74 warnings.
Version 3.5 (08/07/2021):
Updated Work API with the following changes:
- SM-6705: Added
POST /works/${workReferenceNumber}/section-74s
endpoint to enable a HA user to issue Section 74 warnings. - SM-6705: The following audit event types have been added, to be used for Section 74 functionality:
section_74_warning_issued
section_74_warning_acknowledged
section_74_site_visited_and_rectified
section_74_charges_ended
section_74_warning_disputed
section_74_withdrawn
section_74_draft_invoice_issued
section_74_resolved
section_74_draft_invoice_acknowledged
section_74_charge_under_review
section_74_charge_agreed
- SM-6707: Added
GET /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}
endpoint to return a Section 74 warning relating to a work.
Updated Reporting API with the following changes:
- SM-6705: The following audit event types have been added, to be used for Section 74 functionality:
section_74_warning_issued
section_74_warning_acknowledged
section_74_site_visited_and_rectified
section_74_charges_ended
section_74_warning_disputed
section_74_withdrawn
section_74_draft_invoice_issued
section_74_resolved
section_74_draft_invoice_acknowledged
section_74_charge_under_review
section_74_charge_agreed
-
SM-6737: Updated the
GET /works/{workReferenceNumber}
to limit the number of sites returned from a work response to the latest 50. The full list can be retrieved using theGET /reinstatements
endpoint on Reporting API. Also site creation is limited to 999 sites on a work. There is also a new field `number_of_sites` which includes the total of sites on a work.
Version 3.4 (24/06/2021):
Updated Work API with the following changes:
-
SM-7164: Updated
POST /historic-works/inspections
to increment the actual count of a sample inspection target where there is an active target between the Highway Authority and the Promoter.
Version 3.3 (10/06/2021):
Updated Work API with the following changes:
-
SM-6735: Updated the
GET /works/{workReferenceNumber}
to limit the number of inspections returned from a work response to the latest 50. The full list can be retrieved using theGET /inspections
endpoint on Reporting API.
Updated Reporting API with the following changes:
-
SM-6885: Added the following parameters to the
GET /alterations/csv
endpoint to enable the filtering on the alterationstatus_changed_date
:- status_update_date_from
- status_update_date_to
Updated Data Export API with the following changes:
-
SM-6885: Added the following parameters to the
GET /alterations/csv
endpoint to enable the filtering on the alterationstatus_changed_date
:- status_update_date_from
- status_update_date_to
Version 3.2 (27/05/2021):
SM-7109: Updated all APIs to be generated using OpenAPI Specification 3 in order to patch a third party dependency vulnerability. Here is an example of an updated V2 Work API. This swagger.json should be used as an example and will not be the released swagger.json.
Updated Work API with the following changes:
-
SM-6734: Updated the
GET /works/{work reference number}
to limit the number of FPNs returned from a work response to the latest 50. The full list can be retrieved using theGET /fixed-penalty-notices
endpoint.
Updated the Party API with the following changes:
-
SM-7071: New
StreetWorksAdmin
role added toRoleResponse
enum, which is returned in theUserResponse
from theGET /users/{email}
endpoint.
Updated Reporting API with the following changes:
-
SM-6835: Updated the query property filtering to enable searching across
street_name
,town
andarea_name
as a single column meaning search terms likeGREEN OAK AVENUE, SHEFFIELD
are valid. This change has been applied to:GET /forward-plans
GET /fixed-penalty-notices
GET /inspections
GET /alterations
GET /permits
GET /reinstatements
GET /section-81s
GET /sample-inspections
Updated Data Export API with the following changes:
-
SM-6835: Updated the query property filtering to enable searching across
street_name
,town
andarea_name
as a single column meaning search terms likeGREEN OAK AVENUE, SHEFFIELD
are valid. This change has been applied to exports generated by:POST /forward-plans/csv
POST /fixed-penalty-notices/csv
POST /inspections/csv
POST /alterations/csv
POST /permits/csv
POST /reinstatements/csv
POST /section-81s/csv
POST /sample-inspections/csv
Updated Lookup API with the following changes:
-
SM-4954: Fixed an issue with
GET /nsg/search
where streets containing apostrophe'
and hyphen-
characters were failing to return results
Version 3.1 (13/05/2021):
Updated Reporting API with the following changes:
- SM-6081: Added additional optional
query
param to theGET /fixed-penalty-notices
endpoint. This provided query will search against the following properties:work_reference_number
fpn_reference_number
street_name
USRN
promoter_organisation_name
- for HA usersha_organisation_name
- for Planner and Contractor users
Updated Data Export API with the following changes:
- SM-6081: Updated the
POST /fixed-penalty-notices/csv
to use the optionalquery
property. The provided query will search against the following properties:work_reference_number
fpn_reference_number
street_name
USRN
promoter_organisation_name
- for HA usersha_organisation_name
- for Planner and Contractor users
-
SM-6097: The
GET /work-data
endpoint which was used to retrieve permits that had been added, changed or deleted in the previous hour has now been removed.
Version 3.0 (29/04/2021):
Released v3 of all APIs. Decommissioned v1 of all APIs
Version 2.10.10 (15/04/2021):
Updated Work API with the following changes:
- SM-6393: On creation of a permit following a PAA, the deadline date will be set to whichever date is further away between the permits calculated response date and what's remaining of the PAA response date.
Version 2.10.9 (01/04/2021):
Updated Work API with the following changes:
-
SM-6950: Updated the
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
endpoint to return a precondition failed error when submitting a permit alteration on a planned work which would change the permit from minor/standard to major/PAA -
SM-6842: Updated the
POST /works/{workReferenceNumber}/inspections
endpoint so that any eligible inspection raised will contribute to progress against a sample inspection target, if an active target exists for the HA and promoter. -
SM-6842: Updated the
POST /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw
endpoint so that progress against sample inspection targets will be decreased when any eligible inspection is withdrawn, if an active target exists.
Version 2.10.7 (04/03/2021):
SM-6776: Added new authorisation checks that prevent users belonging to suspended organisations from performing any read/write actions, and to prevent contractor orgs from performing any read/write actions on suspended organisations records. These checks have been added to the following APIs:
- Reporting API
- Party API
- Data Export API
- Street Lookup API
- GeoJSON API
Updated Work API with the following changes:
-
SM-5939: Added additional validation to the
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/link-section-81
endpoint to prevent linking a permit and section 81 that are assigned to different promoter organisations. -
SM-5846: Added
PUT sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
endpoint to Work API to allow sample inspection Targets to be closed. Any sample inspections linked to the target that have not been completed will be set to `expired`. Reporting APIGET /sample-inspection-targets
will only return active targets (is_active_target = true
)
Updated the Party API with the following changes:
-
SM-6813:
organisation_status
andorganisation_status_string
have been added as optional properties toUserResponse
,OrganisationResponse
andOrganisationSummaryResponse
. These properties will now be returned by the following endpoints:GET /organisations
GET /organisations/{organisationReference}
GET /users/{email}
Version 2.10.6 (18/02/2021):
Updated Work API with the following changes:
-
SM-6659: Updated the validation on the
PUT /works/{workReferenceNumber}/start
endpoint to prevent a works start being more than 5 years in the past from the proposed start date. - SM-6795: Added new validation rules to Work API that prevent users belonging to suspended organisations from logging in and to prevent contractor orgs from performing any read/write actions on suspended organisations records
-
SM-6107: Updated the validation on
POST /works/{workReferenceNumber}/sites
andPOST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
to use the earliestactual_start_date
across all permits associated with a work when validatingreinstatement_date
. The reinstatement date cannot be before the earliestactual_start_date
. -
SM-6874: Updated the validation logic on the
GET /files/{fileId}
endpoint to allow users to download files attached to a work that they have read access to.
Updated Reporting API with the following changes:
-
SM-6791: Updated the
GET /works/updates
endpoint to allow theupdate_id
parameter to be used without needing to provide either thestart_date
andend_date
, orprevious_minutes
. When theupdate_id
parameter is provided without time range filtering, a maximum of 500 results will be returned.
Updated GeoJSON API with the following changes:
-
SM-6679 (BREAKING CHANGE): A limit of 100 results has been added to the endpoints listed below. If this limit is exceeded, an error will be returned with status code
403
, indicating that the search area and/or date range should be refined.GET /works
GET /activities
GET /forward-plans
GET /hs2-act-limits
Version 2.10.5 (04/02/2021):
Updated Work API with the following changes:
-
SM-3950: Updated the
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/reassign-section-81
endpoint to record the organisation names rather than organisation references in the works history entries when Section 81s are reassigned. - SM-5176: New
GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
endpoint added to retrieve sample inspection target details.
Updated Reporting API with the following changes:
-
SM-4032: Added additional filter and sorting params to the
GET /reinstatements
endpointregistration_date_from
: filter reinstatements to those created on or after this dateregistration_date_to
: filter reinstatements to those created on or before this dateend_date_from
: filter reinstatements to those with an expiry date on or after this dateend_date_to
: filter reinstatements to those with an expiry date on or before this datesort_direction
: change the sort order. This can be eitherasc
ordesc
sort_column
: change the column results are sorted on. Currently limited toend_date
Updated Data Export API with the following changes:
-
SM-4032: Added additional filter params to the
GET /reinstatements/csv
endpointregistration_date_from
: filter reinstatements to those created on or after this dateregistration_date_to
: filter reinstatements to those created on or before this dateend_date_from
: filter reinstatements to those with an expiry date on or after this dateend_date_to
: filter reinstatements to those with an expiry date on or before this date
Version 2.10.4 (21/01/2021):
Updated Work API with the following changes:
-
SM-3570: Fixed a bug with
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
endpoint,revoke_reason
now included in work history entry when a permit is revoked. - The following business rule change introduced on 25/01/2021 is included:
- SM-6114: Updated permit cancel logic to only allow active permits to be cancelled, making it consistent with the options available on the UI.
-
SM-6605 (BREAKING CHANGE): Updated the format of
GET /files/{fileId}
error response body to be in line with error responses throughout Street Manager. An error response body will now contain an object, where previously it contained only the string title of the error code. No further error scenarios have been introduced as part of this change.
Updated Reporting API with the following changes:
- SM-5178: Extended the search functionality available through the optional
query
param on theGET /sample-inspections
endpoint to support searching by street name and promoter organisation name, in addition to searching by the work reference number and USRN which were already supported.
Version 2.10.3 (07/01/2021):
Updated Reporting API with the following changes:
-
SM-4820: The fields which can be searched with using the
query
query parameter has been extended to include:usrn
street_name
town
promoter_organisation_name
where the authenticated user is a HAha_organisation_name
where the authenticated user is a promoter
GET /permits
GET /alterations
GET /forward-plans
-
SM-6640: Fixed a bug with
GET /inspections
endpoint where including leading 0s inquery
excluded valid search results when usingquery
param to filter by USRN.
Updated Data Export API with the following changes:
-
SM-4820: The fields which can be searched with using the
query
query parameter has been extended to include:usrn
street_name
town
promoter_organisation_name
where the authenticated user is a HAha_organisation_name
where the authenticated user is a promoter
POST /permits/csv
POST /alterations/csv
POST /forward-plans/csv
-
SM-6640: Fixed a bug with
POST /inspections/csv
endpoint where including leading 0s inquery
excluded valid search results when usingquery
param to filter by USRN.
Version 2.10.2 (10/12/2020):
Updated Data Export API with the following changes:
-
SM-6508:
GET /csv/{csvId}
has been updated to add validation tocsvId
. This means that a bad request error will be returned a where an invalid value has been provided ascsvId
. Prior to this change an internal server error would be returned.csvId
must be a positive integer.
Updated Reporting API with the following changes:
-
SM-5733:
GET /works/updates
has been updated with two optional query parameters:-
workstream_prefix
: Updates will be restricted to works with one of the given prefixes, if provided. It is not required to have permissions for the provided workstreams. -
update_id
: Only results with update ids above the given id will be returned, if provided.
-
- SM-5420: A new job was created to expire sample inspections. This job will run at 17:00 during GMT and 18:00 during BST. The expiry dates are calculated when the sample inspection is issued. The calculation is as follows:
Category A
: expires from eligibility on the proposed end date of the work recordCategory B
: expires from eligibility when the latest reinstatement at the time of creation is 6 months oldCategory C
: the work contains a reinstatement with anend_date
coming up within the next 3 months. Expires from eligibility when the reinstatement end date is reached
Version 2.10.1 (26/11/2020):
Updated Work API with the following changes:
-
SM-6368:
GET /works/{workReferenceNumber}/history
endpoint updated to enable pagination. This works similarly to the paginated endpoints found in the Reporting API:- Optional query param
offset
added to enable moving through the pages. -
Response model updated with new properties:
pagination
: This object contains pagination information;has_next_page
andtotal_rows
rows
: This is an array of work history items. The detail returned here remains unchanged. There is a limit of 25 history items per page.
- Optional query param
-
SM-6213: New endpoint
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/reassign-section-81
added to enable a HA to change the promoter organisation that a Section 81 is associated with. -
SM-6568: Updated logic used by the
POST /works/{workReferenceNumber}/permit/{permitReferenceNumber}/alterations
endpoint to ensure a permit will not be update to a PAA if the work has started.
Version 2.9 (12/11/2020):
Updated Work API with the following changes:
- SM-6314: New
PUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw
endpoint added to enable the withdrawing of an inspection. - SM-4273:
- Added the following properties to
Section81CreateRequest
:section_81_evidence
(required)file_ids
(optional)
- Added the following properties to
Section81Response
:files
(required)
- Added the following properties to
- SM-6263: The
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
endpoint has been updated to prevent alterations being raised on Immediate permits that have been refused.
Added upcoming enum value:
- SM-6282: Work API response enums have been updated to include a new
upcoming_enum
value. This value is currently a placeholder. Once V2 of the API is stabilised,upcoming_enum
will be returned in responses where the latest version of the API will return a new enum value. This prevents the need for breaking changes on the stabilised API to add new enum values.
Version 2.8 (29/10/2020):
Updated Work API with the following changes:
- SM-5455: New
permit_granted_with_duration_challenge
audit event type has been added, used when an immediate permit is granted with a duration challenge. - SM-6198: New
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/unlink-section-81
endpoint added to enable unlinking a Section 81 from a permit. - SM-6315:
- Added the following additional properties to
InspectionResponse
:inspection_status
(required)inspection_reason_for_withdrawal
(optional)withdrawal_details
(optional)
- Added the following additional required properties to
InspectionSummaryResponse
:inspection_status
- Updated the
POST /works/{workReferenceNumber}/inspections
endpoint to setinspection_status = recorded
. - New
inspection_withdrawn
audit event type has been added, to be used in upcoming functionality for withdrawing inspections.
- Added the following additional properties to
- SM-6284: Responses in the Work API have been updated to return a string version of each enum property previously returned. For example,
PermitResponse
now contains thepermit_status
property which remains as type PermitStatus and a newpermit_status_string
property which will be populated with the string equivalent of the enum value. These will contain the same text in most circumstances but in the future when we stabilise the API and no longer add new enum values we will use the string property to provide more information.
Updated Reporting API with the following changes:
- SM-5925: Added additional optional params to the
GET /fixed-penalty-notices
endpoint.- New filter params include:
status_changed_date_from
status_changed_date_to
- New sorting params include:
sort_column
values:issue_date_time
(default),status_changed_date
sort_direction
values:asc
,desc
(default)
- New filter params include:
- SM-6315:
- Added the following additional required properties to
InspectionSummaryResponse
:inspection_status
date_modified
- New
inspection_withdrawn
audit event type has been added, to be used in upcoming functionality for withdrawing inspections.
- Added the following additional required properties to
Updated Data Export API with the following changes:
- SM-5925: Added additional optional filter params to the
GET /fixed-penalty-notices/csv
endpoint. New filter params include:status_changed_date_from
status_changed_date_to
Updated Party API with the following changes:
- SM-6214: Updated the
type
query param for theGET /organisations
endpoint to allow a list, instead of a single organisation type.
Version 2.7 (15/10/2020):
Added upcoming enum value:
- GeoJSON API, Street Lookup API and Party API response enums have been updated to include a new
upcoming_enum
value. This value is currently a placeholder. Once V2 of the API is stabilised,upcoming_enum
will be returned in responses where the latest version of the API will return a new enum value. This prevents the need for breaking changes on the stabilised API to add new enum values. Thisupcoming_enum
value will be added to Works API and Reporting API response enums in a future release.
Added enum string properties:
- Reporting API, GeoJSON API, Street Lookup API and Party API service responses have been updated to return a string version of each enum property previously returned. For example,
PermitResponse
now containspermit_status
property which remains as type PermitStatus and a newpermit_status_string
property which will be populated with the string equivalent of the enum value. These will contain the same text in most circumstances but in the future when we stabilise the API and no longer add new enum values we will use the string property to provide more information.
Updated GeoJSON API with the following changes:
- Added
hs2_highway
to theWorkCategory
enum. This can be returned by theWorkResponse
Updated Party API with the following changes:
- Updated the
POST /organisations/{organisationReference}/workstreams
andPUT /organisations/{organisationReference}/workstreams/{workstreamPrefix}
endpoints to accept optionalinternal_user_identifier
andinternal_user_name
properties.
Updated Work API with the following changes:
- Updated the
POST /geographical-areas
andPUT /geographical-areas/{geographicalAreaReferenceNumber}
endpoints to accept optionalinternalUserIdentifier
andinternalUserName
query params. - Removed the
is_progressable_paa
field from thePermitResponse
object. This field was never intended to be returned and was never populated in the response object. - Updated the
POST /activity
andPUT /activity/{activityReferenceNumber}
endpoints to acceptstart_date
andstart_time
values in the past. - Updated the
POST /works/${workReferenceNumber}/comments
endpoint to return aCommentCreateResponse
containing thecomment_reference_number
. - New
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/link-section-81
endpoint added to enable linking a Section 81 with a permit. - Updated the
PermitResponse
interface to include an optionallinked_section_81
property, which contains thework_reference_number
andsection_81_reference_number
properties of a linked Section 81. - Updated the
Section81Response
interface to include an optionallinked_permit
property, which contains thework_reference_number
andpermit_reference_number
properties of a linked permit. - The following audit event types have been added, to be used when linking, unlinking and re-assigning Section 81s:
section_81_linked_to_permit
section_81_unlinked_from_permit
section_81_reassigned
Updated Reporting API with the following changes:
- New
GET /sample-inspections
endpoint added to fetch issued Sample Inspections for a Highway Authority organisation.
Version 2.6 (01/10/2020):
Released V2 API Routes:
- All API services now have a
v2
route available in addition tov1
andlatest
.latest
routes point to the latest version of the code which is currentlyv2
. - https://api.sandbox.manage-roadworks.service.gov.uk/v2/work/docs/ (Work API)
- https://api.sandbox.manage-roadworks.service.gov.uk/v2/reporting/docs/ (Reporting API)
- https://api.sandbox.manage-roadworks.service.gov.uk/v2/lookup/docs/ (Street Lookup API)
- https://api.sandbox.manage-roadworks.service.gov.uk/v2/geojson/docs/ (GeoJSON API)
- https://api.sandbox.manage-roadworks.service.gov.uk/v2/party/docs/ (Party API)
- https://api.sandbox.manage-roadworks.service.gov.uk/v2/export/docs/ (Data Export API)
Updated Reporting API with the following changes:
- Added additional optional
query
param to theGET /inspections
endpoint. This provided query will search against the following properties:work_reference_number
street_name
USRN
promoter_organisation_name
ha_organisation_name
- Added additional optional filtering to the
GET /fixed-penalty-notices
endpoint. New filter params include:offence_code
Updated Data Export API with the following changes:
- Updated the
POST /inspections/csv
to use the optionalquery
property. The provided query will search against the following properties:work_reference_number
street_name
USRN
promoter_organisation_name
ha_organisation_name
- Added additional optional filter properties to the
FPNCSVExportRequest
model used by thePOST /fixed-penalty-notices/csv
endpoint. New filter properties include:offence_code
Version 2.5 (17/09/2020):
Updated Works API with the following changes:
- New optional
hs2_additional_usrns
property added toWorkCreateRequest
,PermitCreateRequest
andPermitResponse
objects. This allows HS2 users to provide additional USRNs for permits. The property will be ignored for non-HS2 users. - Updated the login endpoint,
POST /authenticate
, to lock out user accounts that have 5 failed login attempts within a 5 minute period. A423
status code will be returned when locked accounts attempt to authenticate. Accounts are automatically unlocked after 5 minutes. - New
PUT /works/${workReferenceNumber}/excavation-carried-out
endpoint added. If excavation has been requested in the permit application, this endpoint can be used to update the works record to reflect if an excavation took place. The works must be started before this endpoint can be used.
Updated Reporting API with the following changes:
- Added additional optional filtering to the
GET /inspections
endpoint. New filter params include:inspection_type
inspection_outcome
start_date_created
end_date_created
Updated Data Export API with the following changes:
- Added additional optional filter properties to the
InspectionCSVExportRequest
model used by thePOST /inspections/csv
endpoint. New filter properties include:inspection_type
inspection_outcome
start_date_created
end_date_created
Version 2.4 (03/09/2020):
Updated Works API with the following changes:
- Updated
GET permits/category
endpoint to return minor/standardwork_type
if the work only contains a forward-plan and the work does not have major works duration. Works with only a forward-plan and major timings will continue to return awork_type
ofPAA
- Updated
POST /works/{workReferenceNumber}/permits
to use the updated category result described above. Forward plans will now progress directly to Permits when they do not have major timing duration. - Query optimisations
Version 2.3 (20/08/2020):
Updated Works API with the following changes:
- Updated the following endpoint to allow for submission of HS2 Forward plans:
POST /forward-plans/
- BREAKING CHANGE: Added the following mandatory (only for HS2 Promoters) properties to the
ForwardPlanCreateRequest
interface for thePOST /forward-plans/
endpoint. These were also added as optional properties to theForwardPlanResponse
interface.hs2_in_act_limits
hs2_consultation_requested_response_date
hs2_highway_exemption
hs2_works_type
- Updated
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
endpoint to allow HS2 fields to be altered when creating an alteration. - Added the following optional properties (only for HS2 Promoters) to the
PermitAlterationCreateRequest
interface for thePOST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
endpoint.hs2_consultation_requested_response_date
hs2_highway_emails
Version 2.2 (06/08/2020):
Version 2.1 (23/07/2020):
Updated Works API with the following changes:
- Updated the following endpoints to save optional comments for PermitConditionTypes NCT01a, NCT01b and NCT11a:
POST /works/{workReferenceNumber}/permits
POST /works
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
- Reasonable period end date can now be set as a date in the past when granting an immediate permit with a duration challenge.
- BREAKING CHANGE: Added the following mandatory properties to the
FPNCreateRequest
and theHistoricFPNCreateRequest
interfaces for thePOST /works/{workReferenceNumber}/fixed-penalty-notices
andPOST /historic-works/fixed-penalty-notices
endpoints. These were also added as optional properties to theFPNResponse
interface.officer_address
representations_contact
representations_contact_address
payment_methods
Version 2.0 (09/07/2020):
Updated Works API with the following changes:
- PermitASD model has been updated to make
special_desig_description
optional. - New
POST /sample-inspection-targets
endpoint added to allow Sample Inspection Targets to be created. - New
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
endpoint added allowing the agreed targets and max number of works to sample to be updated. - New
POST /sample-inspection
endpoint added which will start the process of selecting work records that will contribute to inspection targets as defined byPOST /sample-inspection-targets
. The selection of work records will be implemented in a future release.
Updated Street Lookup API with the following changes:
- AdditionalSpecialDesignationsResponse model has been updated to make
special_desig_description
optional.
Updated Reporting API with the following changes:
- New
GET /sample-inspection-targets
endpoint added to return Sample Inspection Targets for a Highway Authority organisation.
Version 1.25 - Stable (18/06/2020):
Updated Works API with the following changes:
- New optional
is_covid_19_response
property added toWorkCreateRequest
,PermitCreateRequest
andPermitResponse
objects. Allows a permit to be marked as a response to Covid-19. If this property is not provided in the request it will default to false. -
Added the following comment topics to the
CommentTopicEnum
used in thePOST /works/{workReferenceNumber}/comments
endpoint:FORWARD_PLAN
CHANGE_REQUEST
IMPOSED_VARIATION
DURATION_CHALLENGE
SECTION_81
topic
field of theWorkHistoryResponse
. - Implemented new optional
is_internal
property added toPOST /works/{workReferenceNumber}/comments
endpoint allowing a comment to be marked as internal. - Implemented new endpoint
PUT /works/{workReferenceNumber}/comments/{commentReferenceNumber}/read
available to mark comments as read
Updated Reporting API with the following changes:
-
Added the following comment topics to the
CommentTopicEnum
used in theGET /comments
endpoint:FORWARD_PLAN
CHANGE_REQUEST
IMPOSED_VARIATION
DURATION_CHALLENGE
SECTION_81
- Response from
GET /comments
endpoint updated to include the following properties:comment_reference_number
is_internal
(boolean)is_read
(boolean)read_by
(optional string - should be the user's email address)read_on_date
(optional date)
Updated Data Export API with the following changes:
-
Added the following comment topics to the
CommentTopicEnum
used in thePOST /comments/csv
endpoint:FORWARD_PLAN
CHANGE_REQUEST
IMPOSED_VARIATION
DURATION_CHALLENGE
SECTION_81
-
The hourly generated CSV files exposed through the
GET /work-data
andGET /activity-data
endpoints now use the ISO 8601 format (rather than localised date and time strings) for any datetime values. This is consistent with the datetimes returned in the Works API responses, and removes ambiguity regarding timezones.
Version 1.24 (28/05/2020):
Updated Works API with the following changes:
- PermitASD model has been updated to make
special_desig_description
optional. This is currently a documentation change only. This functionality will be implemented in a future release.
Updated Street Lookup API with the following changes:
- AdditionalSpecialDesignationsResponse model has been updated to make
special_desig_description
optional. This is currently a documentation change only. This functionality will be implemented in a future release.
The following changes will be made to the Works API in a future release:
- New optional
is_covid_19_response
property will be added toWorkCreateRequest
,PermitCreateRequest
andPermitResponse
objects. This will allow a permit to be marked as a response to Covid-19. If this property is not provided in the request it will default to false.
Version 1.23 (14/05/2020):
Updated Works API with the following changes:
- ActivityType request model has been updated to include the following additional values:
new_service_connection
works_for_road_purposes
optional_permit_no_fee
- CommentTopic model has been updated to include the following additional values (please note these will not be useable until a future release):
FORWARD_PLAN
CHANGE_REQUEST
IMPOSED_VARIATION
DURATION_CHALLENGE
SECTION_81
-
The
InspectionResponse
andInspectionSummaryResponse
response models have been updated to make theinspection_category
property optional. -
The definitions for
ASDCode
andASDPeriodicityCode
models have been updated to clarify that the enum values should be submitted as numbers instead of strings. Note that, in a future release, we will be adding validation against providing strings. The API will continue to accept both for the time being, but we strongly encourage submitting these values as numbers instead of strings if you aren't already doing so. -
PermitASD
interface, which is used in a number of work and permit request and response models, will be updated to include new optional date propertiesspecial_desig_start_date
andspecial_desig_end_date
. These fields will be stored against the work and returned on the appropriate responses where available. Affected models include:ForwardPlanCreateRequest
ForwardPlanResponse
ForwardPlanUpdateRequest
PermitRequest
PermitResponse
WorkCreateRequest
Updated Reporting API with the following changes:
CommentReportingResponse
updated to include the string propertycomment_reference_number
.- CommentTopic model has been updated to include the following additional values (please note these will not be useable until a future release):
FORWARD_PLAN
CHANGE_REQUEST
IMPOSED_VARIATION
DURATION_CHALLENGE
SECTION_81
-
The
InspectionSummaryResponse
response model has been updated to make theinspection_category
property optional.
Updated Street Lookup API with the following changes:
AdditionalSpecialDesignationsResponse
updated to include new optional date propertiesspecial_desig_start_date
andspecial_desig_end_date
. This is a documentation change only, the api will be updated to return these values in a future release.
Version 1.22 (30/04/2020):
Updated Works API with the following changes:
- ActivityType request model has been updated to include additional values.
new_service_connection, works_for_road_purposes, optional_permit_no_fee
This is a documentation update only. The application will begin to accept these values in an upcoming release. - AuditEvent response model has been updated to include additional values.
sample_inspection_target_created, sample_inspection_target_updated, sample_inspection_created, sample_inspection_completed, sample_inspection_removed, sample_inspection_expired, internal_comment_submitted, comment_read
This is a documentation update only. The application will begin to return these values in an upcoming release. road_category: number
documentation on create request models has been updated from 0-4 to 0-10 in line with the values accepted by the application.- Specific authentication error message when attempting to authenticate with a user who has had their account disabled using
POST /authenticate
endpoint, which was added in V1.19, has been removed. Users will see a generic error message. - Fixed an issue where calendar day and working day durations would incorrectly be adding an additional day when proposed_end_time was not provided on create work requests
Updated Reporting API with the following changes:
- AuditEvent response model has been updated to include additional values.
sample_inspection_target_created, sample_inspection_target_updated, sample_inspection_created, sample_inspection_completed, sample_inspection_removed, sample_inspection_expired, internal_comment_submitted, comment_read
This is a documentation update only. The application will begin to return these values in an upcoming release. - The
GET /comments
endpoint has been updated with the following optional properties for filtering:date_created_from
date_created_to
topic
Updated Street Lookup API with the following changes:
- AdditionalSpecialDesignationsResponse updated to include the optional
whole_road: boolean
andasd_coordinate_geometry: GeoJSONGeometry
properties.
Updated Party API with the following changes:
- Specific authentication error message when attempting to reset password with a user who has not successfully set password after account creation will now return 401 using
POST /forgot-password
endpoint, which was added in V1.19, has been removed.
Updated Data Export API with the following changes:
- The
POST /comments/csv
endpoint has been updated with the following optional properties for filtering:date_created_from
date_created_to
topic
The following changes will be made to the Works API in a future release:
- New optional
is_internal
property will be added toPOST /works/{workReferenceNumber}/comments
endpoint allowing a comment to be marked as internal. - New endpoint
PUT /works/{workReferenceNumber}/comments/{commentReferenceNumber}/read
will be available to mark comments as read
The following changes will be made to the Reporting API in a future release:
- Response from
GET /comments
endpoint updated to include the following properties: comment_reference_number
is_internal
(boolean)is_read
(boolean)read_by
(optional string - should be the user's email address)read_on_date
(optional date)
Version 1.21 (16/04/2020):
Updated Works API with the following changes:
- Implemented the new
PUT /geographical-areas/{geographicalAreaReferenceNumber}
endpoint allowing a geographical area to be updated. - New optional
permit_reference_number
property added toPOST /works/{workReferenceNumber}/fixed-penalty-notices
endpoint allowing a fixed penalty notice to be associated with a permit. - Delegated user properties
internal_user_identifier
andinternal_user_name
are being stored against audit events generated byPOST
andPUT
endpoints. These are being returned as part ofGET /works/{workReferenceNumber}/history
response.
Updated Data Export API with the following changes:
- New fields added to the Fees Report export: Is TTRO required?, Traffic management type, Proposed start date, Proposed end date, Actual start date, Actual end date, Change request reference
Version 1.20 (02/04/2020):
Updated Works API with the following changes:
- The following endpoint will be available on the Works API in a future release:
- Update a geographical area
PUT /geographical-areas/{geographicalAreaReferenceNumber}
endpoint
- Update a geographical area
- The following audit event types have been added:
update_geographical_area
upcoming_event
(placeholder for a future audit event)
Version 1.19 (26/03/2020):
Updated Party API with the following changes:
- Updated authentication error message when attempting to reset password with a user who has not successfully set password after account creation will now return 401 using
POST /forgot-password
endpoint
Updated Street Lookup API with the following changes:
- Fixed defect on the
GET /nsg/search
endpoint to allow users to input multiple spaces and special characters in thequery
param
Updated Works API with the following changes:
- Fixed defect on the
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
endpoint to allow Highway Authorities to impose changes on a permit that contains files and/or ASDs - Updated authentication error message when attempting to authenticate with a user who has had their account disabled using
POST /authenticate
endpoint - Updated validation on
POST /works/{workReferenceNumber}/inspections
andPOST /historic-works/inspections
endpoints. An empty array value ([]
) for thefailure_reason_details
property for failed inspections will result in a bad request error. - Validation has been added to the proposed_start_time field in the
POST /work
request to prevent immediate works being created without a time being specified. - The work_end_date and work_end_time are now being correctly updated where the proposed_end_date/time slide as a result of validity period.
- Validity period end date calculation now starting from the next working day if the proposed start date is on a weekend or bank holiday.
Updated Reporting API with the following changes:
- The
GET /inspections
endpoint now returns a maximumtotal_rows
value of 501, similar to other Reporting API endpoints - The
GET /*/csv
endpoints which were deprecated in V1.12 have been completely removed. All CSV exporting is available via the Data Export API. This applies to CSV exports for Permits, Fees, FPNs, Inspections and Forward plans.
Updated Data Export API with the following changes:
- The
POST /*/csv
endpoints will now generate CSVs that will include a newtown
column - The
POST /permits/csv
endpoint will now generate a CSV that will include the following new columns:actual_start_date
,actual_end_date
,revoke_reason
andreasonable_period_end_date
- The
POST /fees/csv
endpoint will now generate a CSV that will include a newArea
column - Updated the hourly scheduled job which returns data as part of the
GET /work-data
endpoint to include the following event types when checking for changes:alteration_deemed
permit_hs2_acknowledged
Version 1.18 (19/03/2020):
Town will now be stored in Street Manager:
In the Works API, the following endpoints have been updated to include the optional property town
in its request body (if not provided, it will be inferred from NSG data):
POST /activity
POST /forward-plans
POST /historic-works/fixed-penalty-notices
POST /historic-works/inspections
POST /non-notifiable-works/sites
POST /section-81-works/section-81s
POST /works
In the Works API, the following endpoints now include town
in their respective responses:
GET /works/{workReferenceNumber}
GET /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber}
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}
GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
In the Reporting API, the following endpoints now include town
in their respective responses:
GET /alterations
GET /forward-plans
GET /inspections
GET /permits
GET /reinstatements
GET /section-81s
Updated Work API with the following changes:
- Fixed a defect with the
DELETE /files/{fileId}
endpoint so it now correctly returns a precondition failed error if the file has already been associated with a work - Fixed a defect with the
GET /works/{workReferenceNumber}/history
endpoint so it now correctly returnsinspection_agreed_site_compliance
AuditEvent enum where applicable instead of the event not being returned - Users can now update the
works_coordinates
property when submitting a Permit Alteration to the/works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
endpoint. - Updated
width
,depth
,length
,inspection_units
andnumber_of_holes
request properties to now allow a value of 0. This will impact the following endpoints:POST /non-notifiable-works/sites
POST /works/{workReferenceNumber}/sites
POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
PUT /works/{workReferenceNumber}/inspection-units
- The following audit event types have been added, these are used when creating a work:
planned_works_record_created
in_progress_works_record_created
historic_works_record_created
non_notifiable_works_record_created
section_81_works_record_created
unattributable_works_record_created
- Updated the
GET /work-data
endpoint so that it is now accessible to users with the following roles:Planner
Contractor
HighwayAuthority
Admin
DataExport
Updated Street Lookup API with the following changes:
- Property
road_category
marked as deprecated and will be removed from the response of the following endpoints in a future release:GET /nsg/streets
andGET /nsg/streets/{usrn}
. - Property
reinstatement_types
added to the response of the following endpoints:GET /nsg/streets
andGET /nsg/streets/{usrn}
. This property contains a collection of reinstatement type codes and corresponding location text. For more information on thereinstatement_type_code
property see the `Reinstatement type codes` section above. - The streets returned in the response of the following endpoints now include streets with reinstatement type code value of up to 10 and where the street state does not equal 4:
GET /nsg/streets
andGET /nsg/streets/{usrn}
.
Updated Work API with the following changes:
- All existing create endpoints which currently accept the property
road_category
have been updated to now accept a value of up to 10.
Version 1.17 (05/03/2020):
Workstream restrictions will be taking effect on the Work API. See the access and permissions section for further details.
Updated Work API with the following changes:
- Updated the `object_reference` of audits relating to the
event_type
of reinstatement_submitted. This will now return the site number that can be used as the resource identifier inGET /works/{workReferenceNumber}/sites/{siteNumber}
. This change was applied to theGET /works/{workReferenceNumber}
andGET /works/{workReferenceNumber}/history
endpoints. - Planned permits no longer need to be granted by HA before works can be started
- Planned permits can be assessed at any stage, provided they haven't been assessed or cancelled
- Updated the
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
endpoint to now accept the additional valuesreasonable_period_end_date
andis_duration_challenged
- The
PermitResponse
has been updated to returnis_duration_challenged
Updated Party API with the following changes:
- Updated the
GET /users/{email}
endpoint to acceptswaCode
query parameter. This can be used by contractors to see the workstreams they have available for a particular contract
The Data Export API has been updated with the following changes:
POST /permits/csv
has been updated with the following new properties:geographical_area_reference_number
is_duration_challenged
POST /permits/csv
has been updated with the newgeographical_area_reference_number
propertyPOST /alterations/csv
has been updated with the newgeographical_area_reference_number
propertyPOST /forward-plans/csv
has been updated with the newgeographical_area_reference_number
propertyPOST /reinstatements/csv
has been updated with the newgeographical_area_reference_number
propertyPOST /section-81s/csv
has been updated with the newgeographical_area_reference_number
propertyPOST /inspections/csv
has been updated with the newgeographical_area_reference_number
propertyPOST /fixed-penalty-notices/csv
has been updated with the newgeographical_area_reference_number
property- Updated the
GET /work-data
endpoint to allow previously generated CSVs to be retrieved. - Updated the
GET /work-data
endpoint to include the following additional fields in generated CSVs:Highway authority swa code
Works category reference
Traffic management type reference
Assessment status reference
Permit status reference
Work status reference
- New
GET /activity-data
endpoint added to retrieve data of activities across all organisations which have been added, changed, or deleted within the last hour in CSV format. - New
POST /comments/csv
endpoint added to trigger generation of Comment CSV file
Reporting API has been updated with the following changes:
GET works/updates
endpoint has been updated to return theevent_type
andobject_type
properties. Returns updates for new events, for more information, see audit events in the documentation 'History' section.GET /alterations
endpoint now accepts the followingsort_column
values:date_created
,proposed_start_date
,proposed_end_date
andstatus_changed_date
GET permits/csv
endpoint now accepts the additional valueis_duration_challenged
- The following Reporting API endpoints have been updated with a new
geographical_area_reference_number
property that enables HA users to filter their lists based on one or more Geographical Areas within their organisation:GET /permits
GET /alterations
GET /forward-plans
GET /reinstatements
GET /section-81s
GET /inspections
GET /comments
GET /fixed-penalty-notices
Version 1.16 (20/02/2020):
Work API has been updated with the following changes:
- The
topic
property onWorkHistoryResponse
has been updated with new values specific to permit alterations and permit applications. The content of thedetails
property has also been updated for multiple audit events. This will affect theGET /works/{workReferenceNumber}
andGET /works/{workReferenceNumber}/history
endpoints. - The
AlterationType
enum has been updated to includemodified_permit
as a valid type
Reporting API has been updated with the following changes:
GET /permits
andGET /forward-plans
endpoints have been updated to include explicit date range filtering for start and end datesGET /permits
endpoint has been updated to accept the following optional boolean parameters:hs2_works_only
,consultation_works_only
,consent_works_only
,unacknowledged_by_ha_only
GET /csv-exports
has been updated to only return the CSV Exports that were generated by the requester- The
AlterationType
enum has been updated to includemodified_permit
as a valid type
Data Export API has been updated with the following changes:
POST /permits/csv
andPOST /forward-plans/csv
endpoints have been updated to include explicit date range filtering for start and end datesPOST /permits/csv
endpoint has been updated to accept the following optional boolean parameters:hs2_works_only
,consultation_works_only
,consent_works_only
,unacknowledged_by_ha_only
- The
AlterationType
enum has been updated to includemodified_permit
as a valid type
Version 1.15 (06/02/2020):
Work API has been updated with the following changes:
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/hs2_acknowledgement
endpoint has been added to acknowledge HS2 applications- The
PermitResponse
has been updated to return thehs2_acknowledged
property - The
PermitResponse
has been updated to return thehs2_acknowledged_date_time
property POST /geographical-areas
endpoint has been added to upload Geographical Areas
Party API has been updated with the following changes:
GET /users/{username}
endpoint has been added to return user details
Reporting API has been updated with the following changes:
GET /csv-exports
endpoint has been added return a list of CSV exports which are associated with the authenticated user's organisation
Version 1.14 (23/01/2020):
Work API has been updated with the following changes:
- The
PermitRequest
has been updated to include theadditional_contact
,additional_contact_number
, andadditional_contact_email
properties - The
PermitResponse
has been updated to return theadditional_contact
,additional_contact_number
, andadditional_contact_email
properties - The
WorkCreateRequest
has been updated to include theadditional_contact
,additional_contact_number
, andadditional_contact_email
properties
Party API has been updated with the following changes:
- Added
PUT /users/{email}
endpoint to allow updating of users names
Version 1.13 (08/01/2020):
Work API has been updated with the following changes:
POST /works/{workReferenceNumber}/comments
updated to remove comment_id- The
WorkType
enum has been updated to includehs2_highway_works
as a valid type - The
WorkCategory
enum has been updated to includehs2_highwaycode
as a valid category - The Permit and Work endpoints have been extended to include HS2 specific fields
- The
WorkResponse
has been updated to no longer return thehistorical_permit_reference
- The
WorkResponse
has been updated to return thedescription_of_work
property - The
WorkResponse
has been updated to return thedescription_of_work
property - The
POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
endpoint has been updated to remove the id of the created reinstatement - The
POST /works/{workReferenceNumber}/comments
endpoint has been updated to remove the id of the created comment - The
GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
endpoint has been updated to includestatus_changed_date
- The
GET /permits/category
endpoint has been extended to accept ahs2_highway_works
parameter
Reporting API has been updated with the following changes:
- Added
GET /section-81s
endpoint to allow a list of Section 81s to be retrieved
Party API has be updated with the following changes:
- New
GET /organisations
endpoint to allow retrieval of organisations
Data Export API has be updated with the following changes:
- New
POST fixed-penalty-notices/csv
endpoint to enable async CSV generation
Version 1.12 (19/12/2019):
This version of the specification is the V1 Baseline version that contains all legally required API functions.
The GET /CSV endpoints have been removed on the Reporting endpoint and will be available via the Data Export API in a future release. This applies to CSV exports for Permits, Fees, FPNs, Inspections and Forward plans.
Work API will be updated with the following changes:
- New
PUT /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}/status
endpoint to allow updates to the status of a section 81
Reporting API will be updated with the following changes:
- New
GET /section-81s
endpoint to retrieve all section 81s associated with the authenticated user's organisation
Party API will be updated with the following changes:
- New
GET /organisations
endpoint to allow retrieval of organisations
In previous versions of the documentation GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
was listed as being released on the Party API. This was incorrect. This endpoint is available on the Works API and the documentation has been corrected.
Version 1.11 (12/12/2019):
All APIs will be updated with the following changes:
- BREAKING CHANGE:
site_id
andpermit_id
response fields have removed. These have been replaced withsite_number
andpermit_reference_number
respectively.
The available values for the permit_status
field will be changing across the Works API, Reporting API and GeoJSON API. The new permit_status
values are:
submitted
granted
refused
permit_modification_request
revoked
closed
progressed
cancelled
The forward_plan_status
available values will also be updated to replace closed
with progressed
. The new list of forward_plan_status
values are:
raised
progressed
cancelled
Work API will be updated with the following changes:
- BREAKING CHANGE:
site_id
andpermit_id
response fields have removed. These have been replaced withsite_number
andpermit_reference_number
respectively. The biggest impact of this change to when fetching the details of a site, the existingGET /works/{workReferenceNumber}/sites/{siteId}
endpoint has been replaced withGET /works/{workReferenceNumber}/sites/{siteNumber}
- Existing
POST /works/{workReferenceNumber}/permits
endpoint updated to allow a permit to be created on a historical and non-notifiable work, optionalworkstream_prefix
field added to request to allow workstream to be set on submission of first permit on a historical and non-notifiable work - Optional failure_reason_details.site_name added to
GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber} response
- New
POST /historic-works/inspections
endpoint to create an inspection on a historic work - New
POST /non-notifiable-works/sites
endpoint to create a reinstatement on a non-notifiable work - Existing
POST /works
,POST /permits
andPOST /permit-alterations
requests updated to makespecial_desig_location_text
field optional - A new endpoint
GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
has been created to view a specific section 81s details.
Lookup API will be updated with the following changes:
- BREAKING CHANGE:
street_line
andstreet_centre_point
onGET /nsg/streets
response will be returned as GeoJSON object rather than string - BREAKING CHANGE:
street_line
andstreet_centre_point
onGET /nsg/streets/{usrn}
response will be returned as GeoJSON object rather than string - BREAKING CHANGE:
street_centre_point
onGET /nsg/search
response will be returned as GeoJSON object rather than string - BREAKING CHANGE:
GET /nsg/streets/{usrn}
response updated to makespecial_desig_location_text
field optional
Reporting API updated with the following changes:
- DEPRECATION: All CSV export endpoints i.e. endpoints ending in
/csv
are now deprecated and will be removed in an upcoming version
Data Export API updated with the following changes:
POST /fixed-penalty-notices/csv
endpoint added to trigger generation of FPN CSV file which will be exportable in a later version
Version 1.10 (28/11/2019):
- Add new Data Export API with endpoint
GET /work-data
. (See the resource guide for details)
Assessment status
The available values for a permit’s assessment_status
field will be updated and will no longer re-use the same values of the permit_status
field. The new assessment_status
values are:
granted
granted_auto
refused
refused_auto
permit_modification_request
revoked
Deeming will no longer exist as an assessment_status
, instead the response of GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
will now contain a boolean is_deemed
property to indicate whether or not a permit has deemed.
Now that assessment_status
and permit_status
will contain different values, permit assessment will now be carried out by a new endpoint PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
. Actions that will be carried out by this new endpoint include:
- Granting
- Refusing
- Modification requesting
- Revoking
Cancelling a permit will still continue to be carried out using the existing endpoint PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status
. The following properties will be removed from this endpoint and migrated to the PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
endpoint:
reasons_for_refusal
assessment_discount
revoke_reason
pending_change_details
Breaking changes summary:
-
Permit assessment and revoking will now be carried out using a new
PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment
endpoint, with only cancelling now being carried out using the existingPUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status
endpoint. The following fields will be removed from the latter:reasons_for_refusal
assessment_discount
revoke_reason
pending_change_details
- Deeming is no longer tracked as an
assessment_status
. It is now available via anis_deemed
boolean in the response ofGET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
Work API will be updated with the following changes:
- BREAKING CHANGE:
reinstatement_type
will be added as a new required field forPOST /works/${workReferenceNumber}/sites
. This is to prepare for the introduction of non-notifiable reinstatement work records. The value provided to this field should beexcavation
for current street manager reinstatements until the non-notifiable works feature is released. Reinstatement type is only provided when creating a site, any reinstatements added to an existing site will share the samereinstatement_type
- BREAKING CHANGE:
final_reinstatement
property has been removed fromPUT /works/{workReferenceNumber}/inspection-units
. This can now be updated using the newPUT /works/{workReferenceNumber}/final-reinstatement
endpoint. Inspection units can now be updated so long as there is an existing site/reinstatement for a work, and will be audited individually using the existing inspection_units_logged audit event - BREAKING CHANGE:
PUT /works/{workReferenceNumber}/excavation
removed. Promoters should now raise a permit alteration to update whether an excavation was carried out. - BREAKING CHANGE:
site_id
andpermit_id
response fields have removed. These have been replaced withsite_number
andpermit_reference_number
respectively. The biggest impact of this change to when fetching the details of a site, the existingGET /works/{workReferenceNumber}/sites/{siteId}
endpoint has been replaced withGET /works/{workReferenceNumber}/sites/{siteNumber}
inspection_units
added to response ofGET /works/${workReferenceNumber}
- A new endpoint
PUT /works/{workReferenceNumber}/final-reinstatement
has been created to update thefinal_reinstatement
property. This is only applicable for works with excavation reinstatements, and a new audit event has been added for this,final_site_registered
inspection_units
will be optional forPOST /works/${workReferenceNumber}/sites
andPOST /works/${workReferenceNumber}/sites/${siteId}/reinstatements
. Default to 1.length
,width
,depth
andfinal_reinstatement
fields will be optional forPOST /works/${workReferenceNumber}/sites
andPOST /works/${workReferenceNumber}/sites/${siteId}/reinstatements
. They will still be mandatory for reinstatements wherereinstatement_type
is set to excavation. This is in preparation for non-notifiable works.secondary_reinstatement_coordinates
optional field will be introduced toPOST /works/${workReferenceNumber}/sites
andPOST /works/${workReferenceNumber}/sites/${siteId}/reinstatements
, it must be a GeoJSON geometry (using British National Grid easting and northing coordinate pairs) and must be a point, line string or polygon.number_of_holes
optional field will be introduced toPOST /works/${workReferenceNumber}/sites
andPOST /works/${workReferenceNumber}/sites/${siteId}/reinstatements
this will be required if the reinstatement_type is one of bar holes, core holes or pole testing which will be supported when non-notifiable reinstatements are introduced to the system- Add
POST /section-81-works/section-81s
to create a new Section 81 work.
Version 1.9 (14/11/2019):
- Added the 'Connecting to the API services' section to the API documentation, to explicitly call out the need for clients to connect via DNS CNAMEs, rather than specific fixed IP addresses.
Updated Work API with the following changes:
- BREAKING CHANGE:
permit_id
has been removed from the response ofGET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
- BREAKING CHANGE:
permit_id
has been made optional from the response ofGET /works/{workReferenceNumber}
"sites" property - BREAKING CHANGE:
permit_id
has been made optional from the response ofGET /works/{workReferenceNumber}/sites/{siteId}
-
work_status
will be added to the responses of the following endpoints:GET /works/{workReferenceNumber}
GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}
Updated Reporting API with the following changes:
- BREAKING CHANGE:
swa_organisation_name
has been removed from the response ofGET /reinstatements
endpoint, replaced bypromoter_organisation
andhighway_authority
- BREAKING CHANGE:
permit_status
has been removed as a sorting filter from sort_column parameter onGET /permits
endpoint - BREAKING CHANGE:
forward_plan_status
has been removed as a sorting filter from from sort_column parameter onGET /forward-plans
endpoint - BREAKING CHANGE:
sort_column and sort_direction
have been removed as parameters onGET /forward-plans
endpoint
Version 1.8 (31/10/2019):
- Updated wording to reflect entering Public Beta; re-worked environments and release management sections.
Updated Work API with the following changes:
- Update the
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status
endpoint to allow HAs to submit apermit_modification_request
. See sequencing section for more details. - BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}
to makeclose_footway
mandatory - BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits
to makeclose_footway
mandatory - BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
to makeclose_footway
mandatory - BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}
to removehighway_authority
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}
to removepromoter_organisation
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}
to removepromoter_contact_details
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits
to removepromoter_contact_details
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
to removepromoter_contact_details
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}
to renameapproved_contractor
tosecondary_contact
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits
to renameapproved_contractor
tosecondary_contact
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
to renameapproved_contractor
tosecondary_contact
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}
to renamecontractor_contact_details
tosecondary_contact_number
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits
to renamecontractor_contact_details
tosecondary_contact_number
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
to renamecontractor_contact_details
tosecondary_contact_number
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status
to makereasons_for_refusal
mandatory when refusing permits - BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/inspections
to makeinspection_evidence
mandatory
Updated Reporting API with the following changes:
- BREAKING CHANGE:
GET /permits/counts
endpoint and associated response body removed - BREAKING CHANGE:
GET /sites
endpoint and associated response body removed - BREAKING CHANGE: Reporting API pagination updated across all reporting endpoints:
before
andafter
query params removedoffset
query param added instead (optional for the first page, must be a non-negative integer)total_count
response property will no longer return exact number of rows, instead, 501 will be the maximum number of rows returned by this countpage_start
property removed fromPaginationResponse
ReportingSummaryResponse
removed, meaning thecursor
property is also removed from each paginated endpoint response
Version 1.7 (17/10/2019):
- Added SANDBOX testing strategy details to Testing section
Updated Work API with the following changes:
- BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/inspections
renaming the fieldunable_to_complete_details
toinspection_outcome_details
, allowingnon_compliant
inspections andunable_to_complete
inspection outcomes to use the same field to record additional details. Note that there can only ever be one scheduled inspection per work record. - BREAKING CHANGE: Update the request body of
POST /works/{workReferenceNumber}/inspections
and response body ofGET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
renaming the fieldadditional_failure_comments
toadditional_comments
- Add
POST /works/{workReferenceNumber}/scheduled-inspections
to create a scheduled inspection from a work record. With a body with the following properties:inspection_date
, of type DateTime; Optionalinspection_date_time
, of type DateTime to be used to specify the time of a scheduled inspection;inspection_type
, of typeInspectionType
enum;inspection_category
of typeInspectionCategory
enum - Add
DELETE /works/{workReferenceNumber}/scheduled-inspections
to cancel the scheduled inspection for a work record. Note that there can only ever be one scheduled inspection per work record - Update the request body of
POST /works/{workReferenceNumber}/inspections
to an optional fieldcall_logged_reference
of type string - Update the
InspectionType
enum to renameslg
tolive_site
anddefect_inspection
tonon_compliance_follow_up
- Update the
InspectionCategory
enum to addsite_occupancy
andconditions
both selectable on the Create Inspection request if the InspectionType islive_site
- Update the
InspectionOutcomes
enum to renamewithdraw_defect
toagreed_site_compliance
and addworks_stopped
,works_stopped_apparatus_remaining
,works_in_progress
,works_in_progress_no_carriageway_incursion
- Update the validation of
POST /works/{workReferenceNumber}/inspections
the fieldswas_call_logged
,call_logged_to
,call_logged_summary
,call_logged_reference
are only accepted when when the InspectionType is set tolive_site
and the inspection outcome is set tofailed_high
- Update the of
POST /works
andPOST /works/{workReferenceNumber}/permits
to automatically add the mandatory permit conditionsNCT01a
andNCT01b
. If these conditions are supplied as part of the create requests theircomment
property will be ignored
Update Reporting API with the following changes:
- Update the
GET /forward-plans
endpoint to accept the following query parameters:forward_plan_status
, of typeForwardPlanStatus
array;start_date
of type DateTime;end_date
of type DateTime;query
of type string, which will search by street name or forward plan reference number
Update GeoJSON API with the following changes:
GET /works
,GET /activities
andGET /forward-plans
endpoints have been updated to return GeoJSON FeatureCollection objects. Each GeoJSON Feature object now contains ageometry
property which now reflects what theworks_coordinates
previously were. Each GeoJSON Feature object also now contains aproperties
property which contains all previously available fields returned from the respective endpoints, for examplework_reference_number
would be found here.
Update Street Lookup API with the following changes:
- Add
GET /nsg/search
endpoint. (See resource guide for details) GET /nsg/streets
andGET /nsg/streets/{usrn}
endpoints have been updated to returnstreet_special_desig_code
as an integer in order to reflect the [NSG specification](https://www.geoplace.co.uk/-/national-street-gazetteer-nsg-data-transfer-format-dtf-8-1-documents-released).
Version 1.6 (03/10/2019):
Updated Work API with the following changes:
- BREAKING CHANGE: Update Work API to change
POST /works/{workReferenceNumber}/inspections
andGET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
.failure_reasons
updated from a string array to an array ofFailReasonDetails
, which is composed of afailure_reason
, of typeFailReason
enum;site\_ids
, an array of affected sites; anddetails
, a free text field description - BREAKING CHANGE: How we receive and provide NSG Special Designation information from the API now matches the NSG specification, we've introduced
special_desig_start_time
,special_desig_end_time
andspecial_desig_periodicity_code
to various requests, see the swagger docs for more detail. - Update Work APIs
POST /works/{workReferenceNumber}/permits
to allow permit to be created on a works with only a forward plan. - Update
GET /works/{workReferenceNumber}/history
with anevent
which is an enum of high-level event types that can occur in the system. - Added
PUT /works/{workReferenceNumber}/forward-plans/{forwardPlanReferenceNumber}/cancel
endpoint to allow Promoters/Contractors to cancel forward plans. (See resource guide for details) - Restrict API users to the API interface and UI users to the UI interface
Updated Reporting API with non-breaking changes:
- Update Reporting API to add three optional query parameters added to the
GET /permits
andGET /alterations
endpoints in the Reporting API to enable lane rental filtering:lane_rental_assessment_outcome
, array ofLaneRentalAssessmentOutcome; charges_not_agreed
, of type boolean;lane_rental_charges_potentially_apply
, of type boolean - Update the
POST /works/updates
endpoint with anupdate_id
property. - Restrict API users to the API interface and UI users to the UI interface
Updated GeoJSON API with non-breaking changes:
- Added
GET /forward-plans
endpoint to fetch forward plans in particular bounding box - Restrict API users to the API interface and UI users to the UI interface
Updated Party API with the following changes:
- Update Party API to allow non-Admin, Planner users create and update workstreams associated with their organisation
- Restrict API users to the API interface and UI users to the UI interface
Updated Street Lookup API with the following changes:
- Restrict API users to the API interface and UI users to the UI interface
Version 1.5 (20/09/2019):
- Updated inspections endpoint in Work API
- Updated authentication endpoint response in Work API
- Updated Work API to add additional forward plan endpoints and fields in existing endpoints
- Added forward plan endpoints to Reporting API
- Updated GET /works/updates endpoint on the Reporting API to include details on comments.
- Updated API documentation to explain permit reference number generation.
Version 1.4 (05/09/2019):
- Added Revert start and stop endpoints to Work API
- Added activities endpoints to Work API.
- Updated PermitSummaryResponse object in Reporting API to return more fields.
- Added forward plan endpoints to Work API.
- Added permit discount endpoint for updating discount after assessment to Work API.
Version 1.3 (22/08/2019):
- Audit events in the history response will 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
- Contractors can use the Reporting API to extract data from the service both as JSON and CSV format. These endpoints allow you to extract most works information efficiently for the organisations for which you're working. swa_code parameters are available on the endpoints which must be used by contractors to provide the SWA code of the promoter they are working for.
- Added lane rental assessment endpoints to Work API.
- Added activities endpoint to GeoJSON API to find activities in a given area.
- Added forgot password and password reset endpoints to Party API.
- Updated WRN validation to allow underscores as a replace character for non-URL friendly characters.
Version 1.2 (07/08/2019):
Updated Work API with non-breaking changes:
- New optional boolean properties have been added to the Reporting API `GET /permits` and `GET /alterations` endpoints for filtering results
- `access_token` and `refresh_token` properties have been added to the response of `POST /authenticate`. The `refresh_token` can be provided to the new Party API `POST /refresh` endpoint to retrieve a refreshed `id_token` and `access_token`. The `access_token` can be provided to the Party API `POST /logout` endpoint to invalidate all tokens associated with a user.
Version 1.1 (25/07/2019):
- An optional parameter, workstream_prefix, has been added to POST /work and POST /works/{work reference number}/permits endpoints, to allow API users to specify workstream for permit (if not set will default to "000"), see API Documentation Resource guide for details
- API user can now request further information on the updates Permits by calling the POST /permits/search with a list of work reference numbers returned by the GET /works/updates end point, see API Documentation Resource guide for details
- The street lookup information can now be returned using a USRN rather than coordinates. The GET streets/{usrn} endpoint will return a single street for the supplied USRN, see API Documentation Resource guide for details Updated Work API with non-breaking changes:
- If the user does not supply a work_reference_number as part of the request body to POST /works 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.
More detail is available in the V1.1 API documentation Resource Guide for the Create work endpoint. - Updated Reporting API, added new sorting options for GET /permits to allow sorting by start/end/status Added new optional filter parameters for GET /fixed-penalty-notices to allow filtering by date Added new fields to GET /inspections response, returning Highway Authority and Promoter Organisation
Version 1.0 (30/4/2019):
- Added Environments section
- Added Versioning and Release Management section
- Added Roadmap section
- Referenced Onboarding and Business rule documents
- Updated Sequencing section with new flows and details
- Updated security section with details on user roles, see Security
- Added static Swagger JSON files, see Resource guide
- Added detail on continuous polling endpoint, see Technical Overview and Resource guide
Version 0.2 (27/03/2019 Draft)
- Exposed Street Lookup API, GeoJSON API and Reporting API for external use, see Technical Overview
- Details added for Polling endpoint planned for Reporting API, see Technical Overview
- Plans added for Notifications, see Technical Overview
- Details added for User account roles and permissions, see Security
- Additional features added to Work API
- Works history
- Works comments
- Submit immediate permit
- Permit alterations
- Scheduled inspections
- Permit cancellation
- Submit PAA
- Progress PAA to PA