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.
Sampling API Resource Guide
GET /previous-annual-inspection-units
This endpoint will be used to retrieve the last three years worth of annual inspection unit information.
This endpoint accepts two arguments:
- promoter_org_ref - Reference of the organisation to retrieve annual inspection unit information on
- financial_year_start_date - The FY used to retrieve the previous three (including the provided FY) years' worth of annual inspection information
Calling this endpoint will return annual_inspection_units containing three array items with the following properties:
- financial_year_start_date - The start date of the annual inspection unit's FY
- annual_inspection_units - Annual inspection units for that FY
- is_auto_calculated - Specifies if this financial year's inspection units had been auto-generated by Street Manager rather than having been provided by a user
This endpoint will be used by HA users to calculate the maximum number of samples that can be completed per quarter based on previous number of inspections units and inspection rate.
The request body will take a list of inspection_units, requiring a minimum of 1 and maximum of 3, and an inspection_rate between 20 and 100. The response will return a quota which represents the maximum number of samples that could be completed in a quarter by taking an average of the inspection units, taking the percentage of the inspection rate and dividing that across 4 quarters.
POST /sample-inspection-targets
This endpoint will be used by HA users to create sample inspection targets for promoters.
Users must provide either a baseline estimate of inspection units for the given promoter, or the last two years of inspection units, if three previous years of inspection units do not exist on the system. The initial target for a promoter must have an inspection rate of either 30 or 50. If not the first quarter, the inspection rate must be the same as last quarter or increased/decreased by 5. If the target is not in the first quarter, the inspection rate must be the same as last quarter or increased/decreased by 5. If the last quarter the promoter was sampled in is more than 3 years in the past the inspection rate must be 30. The targets must be at least 5% of the calculated quarterly quota, unless quota less than 20 in which case can be zero or greater. The sum of the targets that the user provides must not exceed the calculated quarterly quota.
This endpoint will be used by HA users to begin the sample inspection generation process based on their targets. A job will be started in the background to generate sample inspections.
DELETE /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
This endpoint will be used by HA users to remove promoters from sample inspection targets. This can happen when there is currently no active quarter or before progress has occurred for that promoter on an active quarter
The request body will take a promoter_org_ref and return a success/failure status code.
PUT /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
This endpoint will be used by HA users to edit targets for a specific promoter. A active target can only be updated before any sample inspections are completed against that target.
Users must provide either a baseline estimate of inspection units for the given promoter, or the last two years of inspection units, if three previous years of inspection units do not exist on the system. The initial target for a promoter must have an inspection rate of either 30 or 50. If not the first quarter, the inspection rate must be the same as last quarter or increased by 5. It may be decreased in 5% increments, with a lower limit of 20%. If the target is not in the first quarter, the inspection rate must be the same as last quarter or increased by 5. It also may be decreased in 5% increments, with a lower limit of 20%. If the last quarter the promoter was sampled in is more than 3 years in the past the inspection rate must be 30. The targets must be at least 5% of the calculated quarterly quota, unless quota less than 20 in which case can be zero or greater. The sum of the targets that the user provides must not exceed the calculated quarterly quota.
POST /sample-inspections/start-quarter
This endpoint will be used by HA users to start a sample inspection quarter.
This can be done when a quarter is not already in progress, the upcoming quarter is not in a different financial year, and there are a sufficient number of samples. Users must provide a start_date that aligns with the start of a financial quarter and is today or in the past. The sample inspection targets for the upcoming quarter are then started. Any new targets created while a quarter is in progress are automatically assigned to that quarter.
POST /sample-inspections/end-quarter
This endpoint will be used by HA users to end a sample inspection quarter.
This can be done when a quarter has been previously started. The sample inspection targets for the quarter are then closed. Any samples that were not completed will be automatically expired. If the quarter being closed is not Q4, the targets will be copied across to the next quarter so promoters with existing targets do not need to be setup again.
GET /sample-inspection-targets/{sampleInspectionTargetReferenceNumber}
This endpoint will be used by HA users to get details of an individual sample inspection target by its target reference number.
POST /sample-inspections/revert-end-quarter
This endpoint will be used by HA users to revert the end of a sample inspection quarter.
This can be done when no quarters are currently in progress, and the previously ended quarter is the current quarter. Upon reverting, any not started targets will be deleted and the previously ended targets will become active again.
GET /previous-annual-inspection-units
This endpoint will be used by HA users to retrieve previous annual inspection units for a given promoter.
This will only return values if the system has annual inspection unit data for the promoter, and it will only return the previous three completed financial years in ascending order (oldest first).