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.40 (21/11/2024):

Updated Works API with the following changes:

SM-12329: Updated POST /activity, PUT /activity/{activityReferenceNumber}, and PUT /activity/{activityReferenceNumber}/cancel to require the HA user to have the Work permission in order to use these endpoints. Otherwise an unauthorised error will be returned.

Updated Party API with the following changes:

SM-12328: Updated GET /users/{email} to return a new optional role_permissions property, returning a list of objects describing each role the user has and the associated permissions.

Updated Reporting API with the following changes:

SM-6711: Updated GET /permits to accept new properties reasonable_period_end_date_from and reasonable_period_end_date_to so that a given permit's reasonable_period_end_date can be filtered on.

Updated Data Export API with the following changes:

SM-6711: Updated POST /permits/csv to accept new properties reasonable_period_end_date_from and reasonable_period_end_date_to so that a given permit's reasonable_period_end_date can be filtered on.

Version 4.15.39 (07/11/2024):

Updated Works API with the following changes:

DELETE /files/{fildId} updated to prevent the deletion of files linked to a private street notice.

Updated Reporting API with the following changes:

SM-8074: Updated GET /inspections to include the inspector_name in the response if one is provided.

Version 4.15.38 (26/09/2024):

Updated Works API with the following changes:

SM-12265: Updated POST /permits/csv to return cancellation reasons for permit exports. Cancellation reason details are also added to DAMD responses.

Version 4.15.37 (12/09/2024):

Updated Works API with the following changes:

SM-12399: Updated POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations to fix a bug that prevented creation when the USRN belonged to an organisation with a zero padded SWA code.
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 and POST /forward-plans to automatically save interested parties for the USRN returned from the Street Lookup API.
SM-12097: The endpoint PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/ancillary-informations/{ancillaryInformationReferenceNumber}/remove will now return HTTP 412 if the ancillary information is already removed
SM-12155: Updated POST works/{workReferenceNumber}/inspections to only allow an inspection_type of section_81 when applicable (work status is Section 81 and the Section 81 type is not "Unattributed works - Completed" or "Unattributed works - Live site").

Updated Street Lookup API with the following changes:

SM-11915: Updated POST /nsg/streets/search and GET /nsg/streets/{usrn} to return the swa_code for each organisation returned in the interest_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 and PUT /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 as under_assessment when work stop was logged. If an immediate permit was under_assessment when work stop was logged, revert work stop will set the permit as under_assessment. If a planned permit was under_assessment when work stop was logged, revert work stop will set the permit as submitted

Version 4.15.34 (04/07/2024):

Updated Works API with the following changes:

SM-12058: Updated GET /works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber} to return jsm_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 an inspection_category for section 81 inspections (initial on first and follow up on subsequent). These will be returned as upcoming_enum on v4.

Updated Sampling API with the following changes:

SM-11770: Includes the following changes:
1. POST /sample-inspection-targets constraints updated to allow a target_c of 0 when less than two years worth (not including current FY) of auto_calculated annual inspection units exist.
2. PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber} constraints updated to allow a target_c of 0 when less than two years worth (not including current FY) of auto_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:
1. Re-named two properties of the returned CSV for GET inspections/csv. Details below -
  1. 'Promoter reason for dispute' renamed to 'Promoter response details'.
  2. 'Highway authority reason for accepting' renamed to 'Highway authority response details'.
2. Re-named two properties of the Download all my data Inspection CSV. Details below -
  1. 'promoter_reason_for_dispute' renamed to 'promoter_response_details'.
  2. 'ha_reason_for_accepting' renamed to 'ha_response_details'.

Updated Works API with the following changes:

SM-11422: Includes the following changes:
1. PUT /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}/withdraw updated to withdraw the linked non-compliance when withdrawing an inspection linked to only one non-compliance.
2. GET /works/{workReferenceNumber}/non-compliances/{nonComplianceReferenceNumber} updated to support the promoter_response_status and ha_response_status of accept_suggestion.
SM-11891: Updated PbiSampleInspectionSummaryResponse to return sample_expiry_date.

Updated Reporting API with the following changes:

SM-11891: Updated GET /pbi-sample-inspections to return sample_expiry_date. It can also now be filtered by sample_expiry_date_from and sample_expiry_date_to, and sorted by providing either work_end_date or sample_expiry_date in the sort_column.

Updated Data Export API with the following changes:

SM-11891: Updated POST /pbi-sample-inspections-due/csv to allow filtering by sample_expiry_date_from and sample_expiry_date_to. The resulting CSV now also contains a sample expiry date field.

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 use POST /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 and POST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements to set reinstatement_registration_due_date as null to the provided permit or active permit, if none provided, if the reinstatement_type is excavation.

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 the POST /api-notifications/subscribe and POST /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 correct object_reference, internal_user_identifier, and internal_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 to PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber} to ensure the new value of target_a must be greater than the value of the current completed inspections and the new values of target_b and target_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 return reinstatement_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:
1. 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 its target_a, target_b and target_c values set to 0. These must be updated before generating samples.
2. POST /sample-inspections/start-quarter will now allow starting a quarter with no targets set.
3. 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 an org_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 setting alteration_status to granted_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 adding assessment_comments when alteration_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 the linked_inspections field:
1. ha_response_status
2. ha_response_status_string
3. ha_response_status_change_date
4. ha_reason_for_accepting
5. promoter_response_status
6. promoter_response_status_string
7. promoter_response_status_change_date
8. 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 and POST /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 and GET /section-58s now return a validation error if a provided ha_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 provided ha_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 in non_compliances are:
1. non_compliance_reference_number
2. non_compliance_date
3. non_compliance_status
4. 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:
1. POST /activity
2. POST /ancillary-informations
3. POST /forward-plans
4. POST /historic-works/fixed-plenty-notices
5. POST /historic-works/inspections
6. POST /non-notifiable-works/sites
7. POST /section-81-works/section-81s
8. POST /works/{workReferenceNumber}/sites
9. 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 and PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber} endpoints to accept a new optional inspection_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 when works_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 a non_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 for POST /section-58s/csv, POST /permits/csv, POST /section-74s/csv and POST /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 field non_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 and PUT/works/{workReferenceNumber}/permits/{permitReferenceNumber}/current-traffic-management-type to include internal_user_name and internal_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 an actual_end_date. Also as part of this change the following endpoints were updated to check for actual_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 show swaCode 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 of cancelled when calculating inspection_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 the id and name 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 filters is_incoming and is_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 parameter export_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 params is_incoming and is_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:
1. export_description
2. csv_export_type
3. csv_export_type_string
4. 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 the is_covid_19_response value to false because the COVID measures are no longer applicable.
SM-10878: Inspections created via the POST /works/{workReferenceNumber}/inspections and POST /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 is disabled to tell them to contact their admin.
SM-10910: Updated the following endpoints to allow 1500 characters for the comment property on permit conditions:
1. POST works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
2. POST /works
3. POST /works/{workReferenceNumber}/permits
4. POST works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/impose
Also updated PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber}/status to allow 1500 characters on the assessment_comments property. And updated PUT works/{workReferenceNumber}/permits/{permitReferenceNumber}/assessment to allow 1500 characters on the additional_comments property.

Version 4.15.9 (11/05/2023)

Updated Work API with the following changes:

SM-8539: Removed the following deprecated endpoints:
1. POST /sample-inspection-targets
2. GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
3. PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
4. PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
5. POST /sample-inspection
Removed the sample_inspections property from the WorkResponse.
SM-10871: Increased internal_user_name valid length to 100 characters. Increased username property of inspectionCreateRequest and historicInspectionCreateRequest 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 provided usrns exist. This endpoint will now also return a 404 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:
1. GET /sample-inspection-targets
2. 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 and PUT /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 of date_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 version 14.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:
1. GET /works/{workReferenceNumber}/fixed-penalty-notices/{fpnReferenceNumber}
2. GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
3. GET /works/{workReferenceNumber}/section-74s/{section74ReferenceNumber}
4. GET /works/{workReferenceNumber}/section-81s/{section81ReferenceNumber}
5. GET /works/{workReferenceNumber}/sites/{siteReferenceNumber}
6. GET /works/{workReferenceNumber}/all-sites
7. GET /works/{workReferenceNumber}
8. GET /works/{workReferenceNumber}/history
9. 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 version 14.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 version 14.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 and swa_code_filter. The fee_report_format property can only be set to single_org_one_csv at the moment. Using single_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 optional fee_report_format value of all_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 version 14.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 version 14.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 version 14.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 version 14.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 version 14.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 the inspection_units property from the following endpoints:
1. POST /works/{workReferenceNumber}/sites
2. POST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
3. POST /non-notifiable-works/sites
SM-8488: The following endpoints relating to deprecated sample inspections functionality will now return a 410 Gone response code:
1. POST /sample-inspection-targets
2. GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
3. PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
4. PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
5. POST /sample-inspection
The new Sampling API endpoints should be used instead.
SM-8360: Updated POST /works/{workReferenceNumber}/inspections endpoint to prohibit:
1. raising a category A inspection unless an active target is present that has not yet met the quota for category As;
2. raising a category B inspection unless a category B sample is present on the work;
3. raising a category C inspection unless a category C sample is present on the work.
Updated 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:
1. GET /sample-inspections
2. GET /sample-inspection-targets
The following new PBI endpoints should be used instead:
1. GET /pbi-sample-inspections
2. 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 a 410 Gone response code. The new POST /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} and GET /works/{workReferenceNumber}/permitReferenceNumber will now return street_line.

Updated Sampling API with the following changes:

SM-10866: Updated POST /sample-inspection-targets and PUT /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 and pbi_sample_inspection_target tables. Additionally removed the sample_inspection table.
SM-10852: Updated validation on POST /sample-inspection-targets and PUT /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 and GET /nsg/streets/{usrn}.

Updated Reporting API with the following changes:

SM-5049: Updated GET /comments to include optional query params for work_reference_number and author_email_address.

Updated Data Export API with the following changes:

SM-5049: Updated POST /comments/csv to include optional query params for work_reference_number and author_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 recalculate inspection_units when the excavation_carried_out value differs between the active permit and request. Also made GET /workReferenceNumber to always return inspection_units and changed when creating a work to default the number of inspection_units to 0 instead of 1.

Updated Sampling API with the following changes:

SM-8670: Updated POST /sample-inspection-targets to set the financial_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 the organisation_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 require location_description as a mandatory field when ancillary_info_type is portable_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:
1. promoter_outcome_status
2. 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:
1. promoter_outcome_status
2. 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 fields work_reference_number and permit_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 include standard_fee, cost and challenge_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 returning upcoming-enum for null values of traffic_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 the standard_fee and total_cost of the PAA, PA, and Change request.
SM-8542: (BREAKING CHANGE): POST works/{workReferenceNumber} and POST works/{workReferenceNumber}/permits now supports NCT03 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 a SampleInspectionTargetResponse 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 make date_removed and ancillary_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 optional pbi_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. Updated POST /works/{workReferenceNumber}/scheduled-inspections to prevent Cat B or C inspections as the scheduled_inspection_category

Updated Data Export API with the following changes:

SM-8411: Updated endpoint POST /section-58s/csv to make use of swa_code so that a contractor can export section 58s.
SM-6390: Added additional optional filter param to the InspectionCSVExportRequest model used by the POST /inspections/csv endpoint. New filter param includes:
1. inspection_category

Updated Reporting API with the following changes:

SM-6390: Added additional optional filtering to the GET /inspections endpoint. New filter params includes:
1. 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 and PUT /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 ensure section_81_severity and section_81_severity_string are now optional and will be returned as null if section_81_type is unattributed_works_live_site or unattributed_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 and ha_response_status_string. Promoter fields are only returned if promoter_response_status_id is populated and Highway authority fields are only returned if ha_response_status_id is populated.
SM-8378: Updated POST /works, POST /works/{workReferenceNumber}/permits and POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations to make close_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 and ha_reason_for_accepting. Promoter fields are only returned if promoter_response_status_id is populated, additionally promoter_reason_for_dispute is only returned if promoter_response_status_id is a value of inspection_outcome_disputed. Highway authority fields are only returned if ha_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 and current_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}/permitsendpoint 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 property close_footpath to WorkCreateRequest and PermitRequest. close_footpath can be one of two enum values, yes_discussed_with_ha or no.
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 the GET /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 allow work_type = permit_works when accepting unattributed works.

Updated Work API with the following changes:

SM-7800: POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/{permitAlterationReferenceNumber} replaced with POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations/impose for changes imposed by HA officers.
SM-8371: Deprecated the following endpoints:
1. POST /works/sample-inspection-targets
2. GET /works/sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
3. PUT /works/sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
4. PUT /works/sample-inspection-targets/{sampleInspectionTargetReferenceNumber}/close
5. POST /works/sample-inspection
These endpoints will continue to be functional until Street Manager and integrators switch to using performance based inspection samples in line with consultation.
SM-8278: Updated PUT /works/{workReferenceNumber}/stop and PUT /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 and current_traffic_management_emergency_contact_number in permit.csv

Updated Event API with the following changes:

SM-8159: Updated GET /works/updates and GET /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 new POST /nsg/streets/search endpoint. This endpoint accepts a StreetsRequest 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} and POST works/{workReferenceNumber}/permits now supports NCT09d as a permit condition.

Updated Reporting API with the following changes:

SM-8187: Removed query query parameter from all endpoints except GET /activities.

Updated Data Export API with the following changes:

SM-8187: Removed query from BaseCSVExportRequest on all endpoints.

Version 4.9 (15/09/2022):

Updated Event API with the following changes:

SM-7864: Added site_subsumed and inspection_deleted to AuditEvent enum. Corrected permit_duration_non_acceptance_response to be permit_duration_challenge_non_acceptance_response

Updated Work API with the following changes:

SM-7864: Added site_subsumed and inspection_deleted to AuditEvent enum. Corrected permit_duration_non_acceptance_response to be permit_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 return current_traffic_management_type, current_traffic_management_type_string, current_traffic_management_emergency_update_date, current_traffic_management_emergency_contact_name and current_traffic_management_emergency_contact_number

Updated Reporting API with the following changes:

SM-7932: Updated GET /section-58s/list to add additional section_58_reference_number, USRN and street_descriptor filters.
SM-7864: Added site_subsumed and inspection_deleted to AuditEvent enum. Corrected permit_duration_non_acceptance_response to be permit_duration_challenge_non_acceptance_response

Updated Data Export API with the following changes:

SM-7932: Updated POST /section-58s/csv to add additional section_58_reference_number, USRN and street_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 and is_subsumed are now required properties in ReinstatementReportingResponse
SM-7903: Includes the following changes:
- Updated GET /fixed-penalty-notices to add additional street_descriptor, usrn and work_reference_number filters.
- Updated GET /inspections to add additional street_descriptor, usrn and work_reference_number filters.
- Updated GET /sample-inspections to add additional street_descriptor, usrn and work_reference_number filters.

Updated Work API with the following changes:

SM-7971: is_active_reinstatement is now a required property in ReinstatementResponse
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 additional street_descriptor, usrn and work_reference_number filters.
- Updated GET /inspections to add additional street_descriptor, usrn and work_reference_number filters.
- Updated GET /sample-inspections to add additional street_descriptor, usrn and work_reference_number filters.

Version 4.7 (18/08/2022):

Updated Reporting API with the following changes:

SM-5195: Updated GET /section-81s to add additional section_81_type filter and added section_81_type and section_81_type_string to the response.
SM-7623: site_number is no longer returned in ReinstatementReportingResponse.
SM-7904: Includes the following changes:
- Updated GET /reinstatements to add additional street_descriptor, usrn, work_reference_number and work_reference_number_exact filters.
- Updated GET /section-81s to add additional street_descriptor, usrn and section_81_reference_number filters.

Updated Work API with the following changes:

SM-7623: site_number is no longer returned as part of failure_reason_details in InspectionResponse.
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 additional section_81_type filter.
SM-7904: Includes the following changes:
- Updated POST /reinstatements/csv to add additional street_descriptor, usrn and work_reference_number filters.
- Updated POST /section-81s/csv to add additional street_descriptor, usrn and section_81_reference_number filters.

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 the GET /works/updates endpoint on the Reporting API, except for the following:
1. previous_minutes param has been removed
2. Maximum allowed range between start_date and end_date has been reduced from 24 hours to 12 hours

Updated Reporting API with the following changes:

SM-6792: Removed GET /works/updates and POST /permits/search endpoints.
SM-7902: Includes the following changes:
- Updated GET /forward-plans to add additional street_descriptor, usrn and forward_plan_reference_number filters.
- Updated GET /alterations to add additional street_descriptor, usrn and permit_alteration_reference_number filters.

Updated Data Export API with the following changes:

SM-7902: Includes the following changes:
- Updated POST /forward-plans/csv to add additional street_descriptor, usrn and forward_plan_reference_number filters.
- Updated POST /alterations/csv to add additional street_descriptor, usrn and permit_alteration_reference_number filters.
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 of section_81_type and section_81_type_string.
SM-7974: Updated GET works/{workReferenceNumber}/permits/{permitReferenceNumber} , GET works/{workReferenceNumber}/sites/{siteReferenceNumber} and GET 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 same workstream_prefix as a permit currently on the works record. The permit can also be rejected if it has a different workstream_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 exclude reinstatement_date and end_date when a site is subsumed and the reinstatement is active.
SM-7901: Updated GET /permits to add a work_reference_number filter.

Updated Work API with the following changes:

SM-7953: Updated GET /works/{workReferenceNumber}/sites/{siteReferenceNumber} to exclude completed_date, reinstatement_date and end_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 have emergency contacts because they were created on v3. Included in this was a small fix that stops Highway Authority users editing more than the permit_conditions in a HA imposed change.

Updated Data Export API with the following changes:

SM-7901: Updated POST /permits/csv to add a work_reference_number filter.

Version 4.4 (07/07/2022):

Updated Reporting API with the following changes:

SM-6243: Update GET /works/updates to correctly populate event_type when value is inspection_agreed_site_compliance.
SM-7900: Updated GET /permits to add separate street_descriptor, usrn and permit_reference_number filters.

Updated Work API with the following changes:

SM-8034: Updated emergency_contact_name and emergency_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 in GetWorkCategoryRequest.

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 to hs2_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 additional street_descriptor, usrn and permit_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 additional street_descriptor, usrn and section_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 the query filter and add separate street_descriptor, usrn and section_74_reference_number filters.

Updated Work API with the following changes:

SM-7987: Increased character limit on emergency_contact_number, in WorkCreateRequest and PermitRequest, from 20 to 100 characters.

Updated Party API with the following changes:

SM-7987: Increased character limits on emergency_contact_name and emergency_contact_number, in WorkstreamCreateRequest and WorkstreamUpdateRequest, 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 and made_safe_by_ha will be optional in the create request if section_81_type is unattributed_works_live_site or unattributed_works_completed.

Version 4.1 (26/05/2022):

Updated Work API with the following changes:

SM-7883: Updated WorkCreateRequest, PermitRequest and PermitResponse to include the following optional properties:
1. emergency_contact_name
2. 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 is cancelled.
SM-6802: Update ReinstatementResponse to return a new optional is_active_reinstatement property.

Updated Reporting API with the following changes:

SM-6802: Update ReinstatementReportingResponse to return new optional is_active_reinstatement and is_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.
1. /section-81s/csv
2. /reinstatements/csv
3. /fixed-penalty-notices/csv
4. /permits/csv
5. /inspections/csv
6. /forward-plans/csv
7. /alterations/csv
8. /comments/csv
9. /section-74s/csv
10. /sample-inspections-due/csv
The 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 to workstreamCreateRequest, workstreamUpdateRequest and workstreamResponse 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 to SiteSummaryResponse and ReinstatementResponse to indicate if a site has been subsumed. If a site is subsumed reinstatement_date and end_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 and end_date will be null if a site is subsumed. This has now been resolved and the reinstatement_date and end_date will retain their previous value when a site is subsumed.
SM-7863: Changes made to GetWorkCategoryRequest to include an optional activity_type. This will be used to progress a forward plan as a major if the duration is a major category and the activity type is optional_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 return organisation_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 maximum page_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 of unable_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 and PUT /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 the GET /section-74s, GET /section-81s and GET /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 the GET /fixed-penalty-notices, GET /inspections and GET /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 the GET /works/updates and POST /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 the GET /alterations and GET /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 and PUT /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 the GET /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 to Section74SummaryResponse which forms part of the WorkResponse. This means that the endpoint GET /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 history reinstatement_deleted and site_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 and activity_type_string properties to PermitSummaryResponse which forms part of the response from the GET /permits endpoint.
SM-6629: Added work_reference_number and permit_reference_number properties to Section74SummaryResponse which forms part of the response from the GET /section-74s endpoint.
SM-6511: The GET /works/updates endpoint will return reinstatement_deleted and site_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 and GET /section-58/{section58ReferenceNumber} endpoints to be pluralised in line with other endpoints. They are now POST /section-58s and GET /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:
1. GET /works/{workReferenceNumber}/sites/{siteNumber} is now GET /works/{workReferenceNumber}/sites/{siteReferenceNumber}
2. POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements is now POST /works/{workReferenceNumber}/sites/{siteReferenceNumber}/reinstatements
Providing site number to these endpoints will result in a 404 NOT FOUND error.
SM-7604: Replaced the site_numbers property with site_reference_numbers in the FailureReasonDetails model. failure_reason_details provided as part of the request to the POST /works/${workReferenceNumber}/inspections endpoint should now include site_reference_numbers rather than site_numbers.
SM-7604: Added site_reference_number to the SiteDetails model. For all inspections created from this version onwards, site_reference_number will be returned as part of the failure_reason_details property from the GET /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 return site_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:
1. site_reference_number and reinstatement_reference_number will now be returned by POST /works/{workReferenceNumber}/sites as part of the SiteCreateResponse
2. site_reference_number and reinstatement_reference_number will now be returned by POST /non-notifiable-works/sites as part of the NonNotifiableSiteCreateResponse
3. reinstatement_reference_number will be returned by POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements as part of the new ReinstatementCreateResponse
4. site_reference_number and reinstatement_reference_number have been added to the SiteSummaryResponse and will contain the values for the most recently created reinstatement. reinstatement_reference_number has also been added to the ReinstatementResponse. These will now be returned by GET /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 and reinstatement_reference_number properties to ReinstatementSummaryResponse models. This change affects the GET /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 the GET /works/updates endpoint.
SM-3363: PermitSummaryResponse has been updated to return paa_to_pa_deadline_date on the POST /permits/search and GET /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 to reasonable_period_end_date are flagged as a difference. This fixes an issue where an error was returned if reasonable_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 the original and proposed PermitResponse properties in the permit alteration response returned from GET /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. Additionally PermitResponse and PermitAlterationResponse have been updated to return duration_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:
1. GET /permits/category
2. 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 the PermitResponse:
1. duration_challenge_review_status
2. duration_challenge_review_status_string
3. duration_challenge_reason_for_non_acceptance
4. duration_challenge_review_update_date
5. duration_challenge_non_acceptance_response_status
6. duration_challenge_non_acceptance_response_status_string
7. duration_challenge_non_acceptance_response_details
8. duration_challenge_non_acceptance_response_update_date
9. duration_challenge_non_acceptance_response_new_reasonable_period_end_date
10. 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 the POST /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 return section74s property which is an array of Section74SummaryResponse 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:
1. POST /works/{workReferenceNumber}/files
2. POST /works
3. POST /works/{workReferenceNumber}/permits
4. POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations
5. POST /works/{workReferenceNumber}/fixed-penalty-notices
6. POST /historic-works/fixed-penalty-notices
7. POST /historic-works/inspections
8. POST /works/{workReferenceNumber}/inspections
9. POST /non-notifiable-works/sites
10. POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
11. POST /works/{workReferenceNumber}/sites
12. POST /works/{workReferenceNumber}/section-74s
13. 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:
1. The end date cannot extend for road categories 1, 2, 5 and 10
2. The end date cannot extend for road categories 3 and 4 that are also traffic sensitive
3. The end date can extend for road categories 3 and 4 that are not traffic sensitive
4. 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 to GET /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 and POST /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:
1. duration_challenge_review_status
2. duration_challenge_review_status_string
3. duration_challenge_reason_for_non_acceptance
4. duration_challenge_review_update_date
5. duration_challenge_non_acceptance_response_status
6. duration_challenge_non_acceptance_response_status_string
7. duration_challenge_non_acceptance_response_details
8. duration_challenge_non_acceptance_response_update_date
9. duration_challenge_non_acceptance_response_new_reasonable_period_end_date
10. 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 the GET /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:
1. section_74_warning_issued
2. section_74_warning_acknowledged
3. section_74_site_visited_and_rectified
4. section_74_charges_ended
5. section_74_warning_disputed
6. section_74_withdrawn
7. section_74_draft_invoice_issued
8. section_74_resolved
9. section_74_draft_invoice_acknowledged
10. section_74_charge_under_review
11. 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:
1. section_74_warning_issued
2. section_74_warning_acknowledged
3. section_74_site_visited_and_rectified
4. section_74_charges_ended
5. section_74_warning_disputed
6. section_74_withdrawn
7. section_74_draft_invoice_issued
8. section_74_resolved
9. section_74_draft_invoice_acknowledged
10. section_74_charge_under_review
11. 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 the GET /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 the GET /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 alteration status_changed_date:
1. status_update_date_from
2. 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 alteration status_changed_date:
1. status_update_date_from
2. 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 the GET /fixed-penalty-notices endpoint.

Updated the Party API with the following changes:

SM-7071: New StreetWorksAdmin role added to RoleResponse enum, which is returned in the UserResponse from the GET /users/{email} endpoint.

Updated Reporting API with the following changes:

SM-6835: Updated the query property filtering to enable searching across street_name, town and area_name as a single column meaning search terms like GREEN OAK AVENUE, SHEFFIELD are valid. This change has been applied to:
1. GET /forward-plans
2. GET /fixed-penalty-notices
3. GET /inspections
4. GET /alterations
5. GET /permits
6. GET /reinstatements
7. GET /section-81s
8. 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 and area_name as a single column meaning search terms like GREEN OAK AVENUE, SHEFFIELD are valid. This change has been applied to exports generated by:
1. POST /forward-plans/csv
2. POST /fixed-penalty-notices/csv
3. POST /inspections/csv
4. POST /alterations/csv
5. POST /permits/csv
6. POST /reinstatements/csv
7. POST /section-81s/csv
8. 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 the GET /fixed-penalty-notices endpoint. This provided query will search against the following properties:
1. work_reference_number
2. fpn_reference_number
3. street_name
4. USRN
5. promoter_organisation_name - for HA users
6. ha_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 optional query property. The provided query will search against the following properties:
1. work_reference_number
2. fpn_reference_number
3. street_name
4. USRN
5. promoter_organisation_name - for HA users
6. ha_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 API GET /sample-inspection-targets will only return active targets (is_active_target = true)

Updated the Party API with the following changes:

SM-6813: organisation_status and organisation_status_string have been added as optional properties to UserResponse, OrganisationResponse and OrganisationSummaryResponse. These properties will now be returned by the following endpoints:
1. GET /organisations
2. GET /organisations/{organisationReference}
3. 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 and POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements to use the earliest actual_start_date across all permits associated with a work when validating reinstatement_date. The reinstatement date cannot be before the earliest actual_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 the update_id parameter to be used without needing to provide either the start_date and end_date, or previous_minutes. When the update_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.
1. GET /works
2. GET /activities
3. GET /forward-plans
4. 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 endpoint
1. registration_date_from: filter reinstatements to those created on or after this date
2. registration_date_to: filter reinstatements to those created on or before this date
3. end_date_from: filter reinstatements to those with an expiry date on or after this date
4. end_date_to: filter reinstatements to those with an expiry date on or before this date
5. sort_direction: change the sort order. This can be either asc or desc
6. sort_column: change the column results are sorted on. Currently limited to end_date

Updated Data Export API with the following changes:

SM-4032: Added additional filter params to the GET /reinstatements/csv endpoint
1. registration_date_from: filter reinstatements to those created on or after this date
2. registration_date_to: filter reinstatements to those created on or before this date
3. end_date_from: filter reinstatements to those with an expiry date on or after this date
4. end_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:
1. 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 the GET /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:
1. usrn
2. street_name
3. town
4. promoter_organisation_name where the authenticated user is a HA
5. ha_organisation_name where the authenticated user is a promoter
Partial searching is supported for each of the above fields. This change has been applied to the following endpoints:
1. GET /permits
2. GET /alterations
3. GET /forward-plans
SM-6640: Fixed a bug with GET /inspections endpoint where including leading 0s in query excluded valid search results when using query 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:
1. usrn
2. street_name
3. town
4. promoter_organisation_name where the authenticated user is a HA
5. ha_organisation_name where the authenticated user is a promoter
Partial searching is supported for each of the above fields. This change has been applied to the following endpoints:
1. POST /permits/csv
2. POST /alterations/csv
3. POST /forward-plans/csv
SM-6640: Fixed a bug with POST /inspections/csv endpoint where including leading 0s in query excluded valid search results when using query 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 to csvId. This means that a bad request error will be returned a where an invalid value has been provided as csvId. 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:
1. 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.
2. 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:
1. Category A: expires from eligibility on the proposed end date of the work record
2. Category B: expires from eligibility when the latest reinstatement at the time of creation is 6 months old
3. Category C: the work contains a reinstatement with an end_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:
1. Optional query param offset added to enable moving through the pages.
2. Response model updated with new properties:
  1. pagination: This object contains pagination information; has_next_page and total_rows
  2. 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.
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:
1. Added the following properties to Section81CreateRequest:
  1. section_81_evidence (required)
  2. file_ids (optional)
2. Added the following properties to Section81Response:
  1. files (required)
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:
1. Added the following additional properties to InspectionResponse:
  1. inspection_status (required)
  2. inspection_reason_for_withdrawal (optional)
  3. withdrawal_details (optional)
2. Added the following additional required properties to InspectionSummaryResponse:
  1. inspection_status
3. Updated the POST /works/{workReferenceNumber}/inspections endpoint to set inspection_status = recorded.
4. New inspection_withdrawn audit event type has been added, to be used in upcoming functionality for withdrawing inspections.
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 the permit_status property which remains as type PermitStatus and a new permit_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.
1. New filter params include:
  1. status_changed_date_from
  2. status_changed_date_to
2. New sorting params include:
  1. sort_column values: issue_date_time (default), status_changed_date
  2. sort_direction values: asc, desc (default)
SM-6315:
1. Added the following additional required properties to InspectionSummaryResponse:
  1. inspection_status
  2. date_modified
2. New inspection_withdrawn audit event type has been added, to be used in upcoming functionality for withdrawing inspections.

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:
1. status_changed_date_from
2. status_changed_date_to

Updated Party API with the following changes:

SM-6214: Updated the type query param for the GET /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. This upcoming_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 contains permit_status property which remains as type PermitStatus and a new permit_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 the WorkCategory enum. This can be returned by the WorkResponse

Updated Party API with the following changes:

Updated the POST /organisations/{organisationReference}/workstreams and PUT /organisations/{organisationReference}/workstreams/{workstreamPrefix} endpoints to accept optional internal_user_identifier and internal_user_name properties.

Updated Work API with the following changes:

Updated the POST /geographical-areas and PUT /geographical-areas/{geographicalAreaReferenceNumber} endpoints to accept optional internalUserIdentifier and internalUserName query params.
Removed the is_progressable_paa field from the PermitResponse object. This field was never intended to be returned and was never populated in the response object.
Updated the POST /activity and PUT /activity/{activityReferenceNumber} endpoints to accept start_date and start_time values in the past.
Updated the POST /works/${workReferenceNumber}/comments endpoint to return a CommentCreateResponse containing the comment_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 optional linked_section_81 property, which contains the work_reference_number and section_81_reference_number properties of a linked Section 81.
Updated the Section81Response interface to include an optional linked_permit property, which contains the work_reference_number and permit_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:
1. section_81_linked_to_permit
2. section_81_unlinked_from_permit
3. 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 to v1 and latest. latest routes point to the latest version of the code which is currently v2.

Updated Reporting API with the following changes:

Added additional optional query param to the GET /inspections endpoint. This provided query will search against the following properties:
1. work_reference_number
2. street_name
3. USRN
4. promoter_organisation_name
5. ha_organisation_name
Added additional optional filtering to the GET /fixed-penalty-notices endpoint. New filter params include:
1. offence_code

Updated Data Export API with the following changes:

Updated the POST /inspections/csv to use the optional query property. The provided query will search against the following properties:
1. work_reference_number
2. street_name
3. USRN
4. promoter_organisation_name
5. ha_organisation_name
Added additional optional filter properties to the FPNCSVExportRequest model used by the POST /fixed-penalty-notices/csv endpoint. New filter properties include:
1. offence_code

Version 2.5 (17/09/2020):

Updated Works API with the following changes:

New optional hs2_additional_usrns property added to WorkCreateRequest, PermitCreateRequest and PermitResponse 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. A 423 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:
1. inspection_type
2. inspection_outcome
3. start_date_created
4. end_date_created

Updated Data Export API with the following changes:

Added additional optional filter properties to the InspectionCSVExportRequest model used by the POST /inspections/csv endpoint. New filter properties include:
1. inspection_type
2. inspection_outcome
3. start_date_created
4. end_date_created

Version 2.4 (03/09/2020):

Updated Works API with the following changes:

Updated GET permits/category endpoint to return minor/standard work_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 a work_type of PAA
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:
1. POST /forward-plans/
BREAKING CHANGE: Added the following mandatory (only for HS2 Promoters) properties to the ForwardPlanCreateRequest interface for the POST /forward-plans/ endpoint. These were also added as optional properties to the ForwardPlanResponse interface.
1. hs2_in_act_limits
2. hs2_consultation_requested_response_date
3. hs2_highway_exemption
4. 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 the POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations endpoint.
1. hs2_consultation_requested_response_date
2. 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:
1. POST /works/{workReferenceNumber}/permits
2. POST /works
3. 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 the HistoricFPNCreateRequest interfaces for the POST /works/{workReferenceNumber}/fixed-penalty-notices and POST /historic-works/fixed-penalty-notices endpoints. These were also added as optional properties to the FPNResponse interface.
1. officer_address
2. representations_contact
3. representations_contact_address
4. 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 by POST /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 to WorkCreateRequest, PermitCreateRequest and PermitResponse 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 the POST /works/{workReferenceNumber}/comments endpoint:
1. FORWARD_PLAN
2. CHANGE_REQUEST
3. IMPOSED_VARIATION
4. DURATION_CHALLENGE
5. SECTION_81
These values can also now be returned in the topic field of the WorkHistoryResponse.
Implemented new optional is_internal property added to POST /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 the GET /comments endpoint:
1. FORWARD_PLAN
2. CHANGE_REQUEST
3. IMPOSED_VARIATION
4. DURATION_CHALLENGE
5. SECTION_81
Response from GET /comments endpoint updated to include the following properties:
1. comment_reference_number
2. is_internal (boolean)
3. is_read (boolean)
4. read_by (optional string - should be the user's email address)
5. read_on_date (optional date)

Updated Data Export API with the following changes:

Added the following comment topics to the CommentTopicEnum used in the POST /comments/csv endpoint:
1. FORWARD_PLAN
2. CHANGE_REQUEST
3. IMPOSED_VARIATION
4. DURATION_CHALLENGE
5. SECTION_81
The hourly generated CSV files exposed through the GET /work-data and GET /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 to WorkCreateRequest, PermitCreateRequest and PermitResponse 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:
1. new_service_connection
2. works_for_road_purposes
3. 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):
1. FORWARD_PLAN
2. CHANGE_REQUEST
3. IMPOSED_VARIATION
4. DURATION_CHALLENGE
5. SECTION_81
The InspectionResponse and InspectionSummaryResponse response models have been updated to make the inspection_category property optional.
The definitions for ASDCode and ASDPeriodicityCode 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 properties special_desig_start_date and special_desig_end_date. These fields will be stored against the work and returned on the appropriate responses where available. Affected models include:
1. ForwardPlanCreateRequest
2. ForwardPlanResponse
3. ForwardPlanUpdateRequest
4. PermitRequest
5. PermitResponse
6. WorkCreateRequest
While these fields are optional and requests will succeed without providing them, the Work API does compare the ASDs submitted in the request with ASDs returned by the Street Lookup API for the given USRN. This is to determine whether an ASD was provided. In order for the ASD to be correctly flagged as provided, where these properties were returned by the street lookup API, these fields will need to match the Lookup API response.

Updated Reporting API with the following changes:

CommentReportingResponse updated to include the string property comment_reference_number.
CommentTopic model has been updated to include the following additional values (please note these will not be useable until a future release):
1. FORWARD_PLAN
2. CHANGE_REQUEST
3. IMPOSED_VARIATION
4. DURATION_CHALLENGE
5. SECTION_81
The InspectionSummaryResponse response model has been updated to make the inspection_category property optional.

Updated Street Lookup API with the following changes:

AdditionalSpecialDesignationsResponse updated to include new optional date properties special_desig_start_date and special_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:
1. date_created_from
2. date_created_to
3. topic

Updated Street Lookup API with the following changes:

AdditionalSpecialDesignationsResponse updated to include the optional whole_road: boolean and asd_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:
1. date_created_from
2. date_created_to
3. topic

The following changes will be made to the Works API in a future release:

New optional is_internal property will be added to POST /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 to POST /works/{workReferenceNumber}/fixed-penalty-notices endpoint allowing a fixed penalty notice to be associated with a permit.
Delegated user properties internal_user_identifier and internal_user_name are being stored against audit events generated by POST and PUT endpoints. These are being returned as part of GET /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:
1. Update a geographical area PUT /geographical-areas/{geographicalAreaReferenceNumber} endpoint
The following audit event types have been added:
1. update_geographical_area
2. 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 the query 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 and POST /historic-works/inspections endpoints. An empty array value ([]) for the failure_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 maximum total_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 new town 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 and reasonable_period_end_date
The POST /fees/csv endpoint will now generate a CSV that will include a new Area 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:
1. alteration_deemed
2. 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 returns inspection_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 and number_of_holes request properties to now allow a value of 0. This will impact the following endpoints:
1. POST /non-notifiable-works/sites
2. POST /works/{workReferenceNumber}/sites
3. POST /works/{workReferenceNumber}/sites/{siteNumber}/reinstatements
4. PUT /works/{workReferenceNumber}/inspection-units
The following audit event types have been added, these are used when creating a work:
1. planned_works_record_created
2. in_progress_works_record_created
3. historic_works_record_created
4. non_notifiable_works_record_created
5. section_81_works_record_created
6. unattributable_works_record_created
Updated the GET /work-data endpoint so that it is now accessible to users with the following roles:
1. Planner
2. Contractor
3. HighwayAuthority
4. Admin
5. 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 and GET /nsg/streets/{usrn}.
Property reinstatement_types added to the response of the following endpoints: GET /nsg/streets and GET /nsg/streets/{usrn}. This property contains a collection of reinstatement type codes and corresponding location text. For more information on the reinstatement_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 and GET /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 in GET /works/{workReferenceNumber}/sites/{siteNumber}. This change was applied to the GET /works/{workReferenceNumber} and GET /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 values reasonable_period_end_date and is_duration_challenged
The PermitResponse has been updated to return is_duration_challenged

Updated Party API with the following changes:

Updated the GET /users/{email} endpoint to accept swaCode 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:
1. geographical_area_reference_number
2. is_duration_challenged
POST /permits/csvhas been updated with the new geographical_area_reference_number property
POST /alterations/csvhas been updated with the new geographical_area_reference_number property
POST /forward-plans/csvhas been updated with the new geographical_area_reference_number property
POST /reinstatements/csvhas been updated with the new geographical_area_reference_number property
POST /section-81s/csvhas been updated with the new geographical_area_reference_number property
POST /inspections/csvhas been updated with the new geographical_area_reference_number property
POST /fixed-penalty-notices/csvhas been updated with the new geographical_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:
1. Highway authority swa code
2. Works category reference
3. Traffic management type reference
4. Assessment status reference
5. Permit status reference
6. 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 the event_type and object_type properties. Returns updates for new events, for more information, see audit events in the documentation 'History' section.
GET /alterations endpoint now accepts the following sort_column values: date_created, proposed_start_date, proposed_end_date and status_changed_date
GET permits/csv endpoint now accepts the additional value is_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:
1. GET /permits
2. GET /alterations
3. GET /forward-plans
4. GET /reinstatements
5. GET /section-81s
6. GET /inspections
7. GET /comments
8. GET /fixed-penalty-notices

Version 1.16 (20/02/2020):

Work API has been updated with the following changes:

The topic property on WorkHistoryResponse has been updated with new values specific to permit alterations and permit applications. The content of the details property has also been updated for multiple audit events. This will affect the GET /works/{workReferenceNumber} and GET /works/{workReferenceNumber}/history endpoints.
The AlterationType enum has been updated to include modified_permit as a valid type

Reporting API has been updated with the following changes:

GET /permits and GET /forward-plans endpoints have been updated to include explicit date range filtering for start and end dates
GET /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 include modified_permit as a valid type

Data Export API has been updated with the following changes:

POST /permits/csv and POST /forward-plans/csv endpoints have been updated to include explicit date range filtering for start and end dates
POST /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 include modified_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 the hs2_acknowledged property
The PermitResponse has been updated to return the hs2_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 the additional_contact, additional_contact_number, and additional_contact_email properties
The PermitResponse has been updated to return the additional_contact, additional_contact_number, and additional_contact_email properties
The WorkCreateRequest has been updated to include the additional_contact, additional_contact_number, and additional_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 include hs2_highway_works as a valid type
The WorkCategory enum has been updated to include hs2_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 the historical_permit_reference
The WorkResponse has been updated to return the description_of_work property
The WorkResponse has been updated to return the description_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 include status_changed_date
The GET /permits/category endpoint has been extended to accept a hs2_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 and permit_id response fields have removed. These have been replaced with site_number and permit_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 and permit_id response fields have removed. These have been replaced with site_number and permit_reference_number respectively. The biggest impact of this change to when fetching the details of a site, the existing GET /works/{workReferenceNumber}/sites/{siteId} endpoint has been replaced with GET /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, optional workstream_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 and POST /permit-alterations requests updated to make special_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 and street_centre_point on GET /nsg/streets response will be returned as GeoJSON object rather than string
BREAKING CHANGE: street_line and street_centre_point on GET /nsg/streets/{usrn} response will be returned as GeoJSON object rather than string
BREAKING CHANGE: street_centre_point on GET /nsg/search response will be returned as GeoJSON object rather than string
BREAKING CHANGE: GET /nsg/streets/{usrn} response updated to make special_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 existing PUT /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status endpoint. The following fields will be removed from the latter:
1. reasons_for_refusal
2. assessment_discount
3. revoke_reason
4. pending_change_details
Deeming is no longer tracked as an assessment_status. It is now available via an is_deemed boolean in the response of GET /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 for POST /works/${workReferenceNumber}/sites. This is to prepare for the introduction of non-notifiable reinstatement work records. The value provided to this field should be excavation 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 same reinstatement_type
BREAKING CHANGE: final_reinstatement property has been removed from PUT /works/{workReferenceNumber}/inspection-units. This can now be updated using the new PUT /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 and permit_id response fields have removed. These have been replaced with site_number and permit_reference_number respectively. The biggest impact of this change to when fetching the details of a site, the existing GET /works/{workReferenceNumber}/sites/{siteId} endpoint has been replaced with GET /works/{workReferenceNumber}/sites/{siteNumber}
inspection_units added to response of GET /works/${workReferenceNumber}
A new endpoint PUT /works/{workReferenceNumber}/final-reinstatement has been created to update the final_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 for POST /works/${workReferenceNumber}/sites and POST /works/${workReferenceNumber}/sites/${siteId}/reinstatements. Default to 1.
length, width, depth and final_reinstatement fields will be optional for POST /works/${workReferenceNumber}/sites and POST /works/${workReferenceNumber}/sites/${siteId}/reinstatements. They will still be mandatory for reinstatements where reinstatement_type is set to excavation. This is in preparation for non-notifiable works.
secondary_reinstatement_coordinates optional field will be introduced to POST /works/${workReferenceNumber}/sites and POST /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 to POST /works/${workReferenceNumber}/sites and POST /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 of GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}
BREAKING CHANGE: permit_id has been made optional from the response of GET /works/{workReferenceNumber} "sites" property
BREAKING CHANGE: permit_id has been made optional from the response of GET /works/{workReferenceNumber}/sites/{siteId}
work_status will be added to the responses of the following endpoints:
1. GET /works/{workReferenceNumber}
2. GET /works/{workReferenceNumber}/permits/{permitReferenceNumber}

Updated Reporting API with the following changes:

BREAKING CHANGE: swa_organisation_name has been removed from the response of GET /reinstatements endpoint, replaced by promoter_organisation and highway_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 on GET /forward-plans endpoint
BREAKING CHANGE: sort_column and sort_direction have been removed as parameters on GET /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 a permit_modification_request. See sequencing section for more details.
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber} to make close_footway mandatory
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits to make close_footway mandatory
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations to make close_footway mandatory
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber} to remove highway_authority
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber} to remove promoter_organisation
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber} to remove promoter_contact_details
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits to remove promoter_contact_details
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations to remove promoter_contact_details
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber} to rename approved_contractor to secondary_contact
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits to rename approved_contractor to secondary_contact
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations to rename approved_contractor to secondary_contact
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber} to rename contractor_contact_details to secondary_contact_number
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits to rename contractor_contact_details to secondary_contact_number
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/alterations to rename contractor_contact_details to secondary_contact_number
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/permits/{permitReferenceNumber}/status to make reasons_for_refusal mandatory when refusing permits
BREAKING CHANGE: Update the request body of POST /works/{workReferenceNumber}/inspections to make inspection_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 and after query params removed
offset 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 count
page_start property removed from PaginationResponse
ReportingSummaryResponse removed, meaning the cursor 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 field unable_to_complete_details to inspection_outcome_details, allowing non_compliant inspections and unable_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 of GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber} renaming the field additional_failure_comments to additional_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; Optional inspection_date_time, of type DateTime to be used to specify the time of a scheduled inspection; inspection_type, of type InspectionType enum; inspection_category of type InspectionCategory 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 field call_logged_reference of type string
Update the InspectionType enum to rename slg to live_site and defect_inspection to non_compliance_follow_up
Update the InspectionCategory enum to add site_occupancy and conditions both selectable on the Create Inspection request if the InspectionType is live_site
Update the InspectionOutcomes enum to rename withdraw_defect to agreed_site_compliance and add works_stopped, works_stopped_apparatus_remaining, works_in_progress, works_in_progress_no_carriageway_incursion
Update the validation of POST /works/{workReferenceNumber}/inspections the fields was_call_logged, call_logged_to, call_logged_summary, call_logged_reference are only accepted when when the InspectionType is set to live_site and the inspection outcome is set to failed_high
Update the of POST /works and POST /works/{workReferenceNumber}/permits to automatically add the mandatory permit conditions NCT01a and NCT01b. If these conditions are supplied as part of the create requests their comment 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 type ForwardPlanStatus 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 and GET /forward-plans endpoints have been updated to return GeoJSON FeatureCollection objects. Each GeoJSON Feature object now contains a geometry property which now reflects what the works_coordinates previously were. Each GeoJSON Feature object also now contains a properties property which contains all previously available fields returned from the respective endpoints, for example work_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 and GET /nsg/streets/{usrn} endpoints have been updated to return street_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 and GET /works/{workReferenceNumber}/inspections/{inspectionReferenceNumber}. failure_reasons updated from a string array to an array of FailReasonDetails, which is composed of a failure_reason, of type FailReason enum; site\_ids, an array of affected sites; and details, 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 and special_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 an event 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 and GET /alterations endpoints in the Reporting API to enable lane rental filtering: lane_rental_assessment_outcome, array of LaneRentalAssessmentOutcome; charges_not_agreed, of type boolean; lane_rental_charges_potentially_apply, of type boolean
Update the POST /works/updates endpoint with an update_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
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