API specification

Version 6.0

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

Reporting API Resource Guide

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

Pagination

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

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

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

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

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

The rows property contains the records for the current page.

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

Organisation specific data

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

Get permits

GET /permits

Note: If you know the work_reference_number of the permit you are searching for, try searching for works directly instead, as it is a more performant endpoint.

Query params:

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

Get permits - files

GET /permits/files

Retrieves a list of files that have been added to the latest version of a permit. The permit_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

permit_reference_number: Search by the reference number of the permit
file_type: The type of file to be filtered by. Either images or documents

Get inspections

Query params:

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

Get inspections - files

GET /inspections/files

Retrieves a list of files that have been added to any inspection. The inspection_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

inspection_reference_number: Search by the reference number of the inspection
file_type: The type of file to be filtered by. Either images or documents

Get reinspections

Retrieves a list of reinspections that have been added to any works record. Reinspections can be filtered using the query params described below.

Query params:

start_date: The reinspection_date_time or reinspection_date for reinspections
end_date: The reinspection_date or reinspection_date for reinspections
inspection_type: The inspection type i.e. live_site, reinstatement etc.
inspection_category: The inspection type i.e. a, b, third_party etc.
sort_column: The property of the reinspection to order results by
sort_direction: Ascending/descending
swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
organisation: Name of organisation associated with the permit (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
street_descriptor: Search by street, town or area (partial match)
usrn: Search by USRN
work_reference_number: Search by work reference number (partial match)

Get FPNs

GET /fixed-penalty-notices

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

Query params:

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

Get FPNs - Files

GET /fixed-penalty-notices/files

Retrieves a list of files that have been added to any FPN. The fpn_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

fpn_reference_number: Search by the reference number of the fpn
file_type: The type of file to be filtered by. Either images or documents

Get reinstatements

GET /reinstatements

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

Query params:

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

Get reinstatements - files

GET /reinstatements/files

Retrieves a list of files that have been added to any reinstatement. The reinstatement_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

reinstatement_reference_number: Search by the reference number of the reinstatement
file_type: The type of file to be filtered by. Either images or documents

Get expiring interim reinstatements

GET /reinstatements/expiring-interims

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

Query params:

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

Get alterations

GET /alterations

Query params:

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

Get forward plans

GET /forward-plans

Query params:

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

Activities

GET /activities

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

Query params:

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

Section 58s

GET /section-58s

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

Query params:

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

Section 74s

GET /section-74s

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

Query params:

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

Section 74s - files

GET /section-74/files

Retrieves a list of files that have been added to any section 74. The section_74_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

section_74_reference_number: Search by the reference number of the section 74
file_type: The type of file to be filtered by. Either images or documents

Get section 81s

GET /section-81s

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

Query params:

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

Get section 81s - files

GET /section-81s/files

Retrieves a list of files that have been added to any section 81. The section_81_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

section_81_reference_number: Search by the reference number of the section 81
file_type: The type of file to be filtered by. Either images or documents

CSV Exports

GET /csv-exports

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

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

Permits - Duration Challenges

GET /permits/duration-challenges

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

Query params:

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

Permit Alterations - Duration Challenges

GET /alterations/duration-challenges

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

Query params:

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

Get PBI Sample Inspection Targets

GET /pbi-sample-inspection-targets

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

Query params:

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

Get PBI Sample Inspections

GET /pbi-sample-inspections

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

Query params:

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

Get Non-compliances

GET /non-compliances

Retrieves a list of non-compliances associated with the authenticated user’s organisation.

Query params:

offset: The number of results to skip when returning the result set, used for pagination
sort_column: Choose the column you'd like to sort the non-compliances by, the default is date_created
sort_direction: Ascending/descending
geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
non_compliance_date_created_from: Date filtering based on the non-compliance created date
non_compliance_date_created_to: Date filtering based on the non-compliance created date
organisation: Name of organisation associated with the non-compliance (partial match). This param will match Promoter name.
street_descriptor: Search by street, town or area (partial match)
usrn: Search by USRN
swa_code: Used by contractors permitted to carry out works on behalf of promoters.
non_compliance_reference_number: Search by non-compliance reference number (partial match)
non_compliance_status: Search by status eg. Issued or Withdrawn.
ha_response_status: Search by HA response status eg. Issued or Withdrawn.
promoter_response_status: Search by Promoter response status eg. Issued or Withdrawn.
most_recent_inspection_type: Search by most recent inspection type eg. Reinstatement or Section 81.
most_recent_inspection_outcome: Search by most recent inspection outcome eg. Passed or Failed.
most_recent_promoter_response_status: Search by most recent Promoter response status eg. JSM required or No response.
most_recent_ha_response_status: Search by most recent HA response status eg. Reviewing dispute or No response.

Get Private Street Notices

GET /private-street-notices

Retrieves a list of private street notices associated with the authenticated user’s organisation.

Query params:

offset: The number of results to skip when returning the result set, used for pagination
sort_direction: Ascending/descending
geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
organisation: Name of organisation associated with the permit (partial match). This param will match Promoter name.
street_descriptor: Search by street, town or area (partial match)
usrn: Search by USRN
swa_code: Used by contractors permitted to carry out works on behalf of promoters.
private_street_reference_number: Search by private street reference number (partial match)
private_street_status: Search by status i.e. Cancelled or Issued.
start_date_from: Date filtering based on the private street notice start date
start_date_to: Date filtering based on the private street notice start date
end_date_from: Date filtering based on the private street notice end date
end_date_to: Date filtering based on the private street notice end date
date_created_from: Date filtering based on the private street notice created date
date_created_to: Date filtering based on the private street notice created date

Get Private Street Notices - Files

GET /private-street-notices/files

Retrieves a list of files that have been added to any private street notice. The private_street_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

private_street_reference_number: Search by the reference number of the private_street
file_type: The type of file to be filtered by. Either images or documents

Get Works By Work Reference Number

GET /works

Retrieves a list of works matching the work reference number supplied. It will either return an exact match, or 5 close matches. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of. Note that this endpoint differs from the other main reporting endpoints, as the results are not paginated.

Query params:

work_reference_number: Search by work reference number (partial match or exact match)
swa_code: Used by contractors permitted to carry out works on behalf of promoters

Get Works - Files

GET /works/files

Retrieves a list of files that have been added to any work. The work_reference_number is required to use the end point. The file_type can be used for filtering.

Query params:

work_reference_number: Search by the reference number of the work
file_type: The type of file to be filtered by. Either images or documents

Permits - Reinstatements Due

GET /permits/reinstatements-due

Retrieves a list of permits that require a reinstatement to be registered. The registration_due_date_from and registration_due_date_to filters can be used to search for permits with missing reinstatements (where the reinstatement due date has already passed) or permits which are due a reinstatement. At least one of the aforementioned filters will be required and if both are given one must be the present date. Contractors are required to provide optional swa_code parameter in order to state which promoter they are working on behalf of.

Query params:

swa_code: Used by contractors permitted to carry out works on behalf of promoters.
street_descriptor: Search by street, town or area (partial match).
usrn: Search by USRN
geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user.
organisation: Name of organisation associated with the permits (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
worker_reference_number: Search by work reference number (partial match).
work_end_date_from: Date filtering by actual end date if available, otherwise filter permits by proposed end date.
work_end_date_to: Date filtering by actual end date if available, otherwise filter permits by proposed end date.
registration_due_date_from: Date filtering by permits reinstatement registration due date.
registration_due_date_to: Date filtering by permits reinstatement registration due date.

Get Material Classifications

GET /material-classifications

Retrieves a list of material classifications that have been submitted. The material_classification_classification must be provided to return hazardous or non_hazardous material classifications. This list of Material Classifications will be returned in descending order with the most recently created at the top. The hazardous materials will only be returned for hazardous material classifications and hazardous_material_type_other_description will only be returned if Other was submitted as the hazardous_material_type_other_description contains the description of the hazardous material.

Query params:

offset: The number of results to skip when returning the result set, used for pagination
sort_direction: Ascending/descending
material_classification_classification: Mandatory filter to return the hazardous or non_hazardous material classifications
material_classification_reference_number: Search by material classification reference number.
street_descriptor: Search by street, town or area (partial match).
usrn: Search by USRN
date_sample_taken_from: Date filtering by material classification sample taken date.
date_sample_taken_to: Date filtering by material classification sample taken date.
date_created_from: Date filtering by material classification created date.
date_created_to: Date filtering by material classification created date.

Get PBI Sample Generation Jobs

GET /pbi-sample-generation-jobs

Retrieves a list of sample generation jobs that have been started by the user’s organisation. This endpoint is only accessible by HAs. Jobs will be returned in descending order with most recently started jobs at the top of the list.

Query params:

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

Get Interested Party Permits

GET /interested-party-permits

Retrieves a list of permits that the logged in user is an interested party of. Note this endpoint is for HA users only.

Query params:

work_status: The work status i.e. planned, completed
work_category: The work category i.e. minor, standard
sort_column: The property of the permit to order results by
sort_direction: Ascending/descending
work_start_date_from: Date filtering by actual start date if available, otherwise filter permits by proposed start date
work_start_date_to: Date filtering by actual start date if available, otherwise filter permits by proposed start date
work_end_date_from: Date filtering by actual end date if available, otherwise filter permits by proposed end date
work_end_date_to: Date filtering by actual end date if available, otherwise filter permits by proposed end date
start_date_created: Date filtering by permit date created. Filters permits created on or after start_date_created
end_date_created: Date filtering by permit date created. Filters permits created on or before start_date_created
is_high_impact_traffic_management: When true this will return permits with a traffic management type of road closure, contra-flow, lane closure, convoy workings, multi-way signals or two-way signals
geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
street_descriptor: Search by street, town or area (partial match)
usrn: Search by USRN
permit_reference_number: Search by the reference number of the permit
work_reference_number: Search by the work reference number of the permit
promoter_organisation_name: Name of the promoter organisation associated with the permit.
ha_organisation_name: Name of the HA organisation associated with the permit.

Get Change Requests

GET /change-requests

Retrieves a list of change requests that the logged in user is associated with.

Query params:

change_request_status: The change request status i.e. submitted, granted
change_request_type: The change request type i.e. work extension, HA imposed change
work_category: The work category i.e. minor, standard
sort_direction: Ascending/descending
start_date_created: Date range filtering based on the date_created property
end_date_created: Date range filtering based on the date_created property
swa_code: Used by contractors to provide the swa code of the promoter the contractor is working on behalf of
is_traffic_sensitive: When true this will return change requests where a traffic sensitive ASD has been selected
is_high_impact_traffic_management: When true this will return change requests with a traffic management type of road closure, contra-flow, lane closure, convoy workings, multi-way signals or two-way signals
geographical_area_reference_number: An array of Geographical Areas that you would like to filter your list by as a HA user
status_update_date_from: Date range filtering based on the status_update_date property
status_update_date_to: Date range filtering based on the status_update_date property
organisation: Name of organisation associated with the permit alteration (partial match). For HA users, this param will match Promoter name. For Promoter / Contractor users, this param will match Local Authority name.
street_descriptor: Search by street, town or area (partial match)
usrn: Search by USRN
change_request_reference_number: Search by the reference number of the change request