Getting Started on Incidents API

All testing of the APIs must occur on the TEST environment. Subscription keys are associated to a specific Product and environment (LIVE/TEST) meaning that both the URL and Subscription Key have to be valid for that endpoint to accept the request.

Initial Connectivity Testing

To assist with connecting to the APIs, a few endpoints have been exposed to assist with these initial connectivity tests. Browse to the Hire API by browsing to APIs and select correct API. For the below tests, the API will be Incidents API - test - v1.

Once the endpoint for the selected API are showing, check that Group by tag is on to ensure the endpoints are grouped by API route.

The below tests are for the Incidents API group

1. Get Greeting

   • Locate GET - Get a greeting and click the green Try It button.

   • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

   • Click the red Send button at the bottom of the side bar and you should receive a greeting and local time of server (like below)

     • HTTP/1.1 200 OK

     • "Hello from Incidents API. The local server time is 2024-08-20 14:32:41"

2. Get ProblemDetails

   • NOTE: A ProblemDetails response is the standard payload returned for non-200 HTTP Status code request to the API (excluding validation failures).

   • Locate GET - Returns a ProblemDetails response and click the green Try It button.

   • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

   • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

     • HTTP/1.1 400 Bad Request

     • { "type": "BadHttpRequestException", "title": "Bad request.", "status": 400, "detail": "This is a dummy ProblemDetails response for testing purposes.", "instance": "/api/v1/incidents/test/problem-details", "traceid": "0HN60H97DJD9A:00000558" }

3. Get ValidationProblemDetails

   • NOTE: A ValidationProblemDetails response is the standard payload returned for a 422 HTTP status code which indicates the request was accepted, but the input failed validation for one or more reasons.

   • Locate GET - Returns a ValidationProblemDetails response and click the green Try It button.

   • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

   • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

     • HTTP/1.1 422 Unprocessable Entity

     • { "type": "ValidationException", "title": "One or more validation errors occurred.", "status": 422, "detail": "This is a dummy ValidationProblemDetails response for testing purposes.", "instance": "/api/v1/incidents/test/validation-problem-details", "errors": { "Property1": ["This is a validation failure message for Property 1."], "Property2": ["This is a validation failure message for Property 2."], "Property3": ["This is a validation failure message for Property 3."] }, "traceid": "0HN60H97DJD9A:00000565" }

   Fetching some data

   The below tests are for the Lookups API group Check that Group by tag is on to ensure the endpoints are grouped by API route.

   1. Get Organisations

      • Locate GET - Retrieves the lookups values and click the green Try It button.

      • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

        • Provide an code for the lookup (example IncidentType).

      • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

        • HTTP/1.1 200 OK

        • [{"id":10419,"value":"Intervention"},{"id":10420,"value":"Second Bite"},{"id":10421,"value":"Out of Hours"},{"id":10422,"value":"Surge"},{"id":10423,"value":"Services Only"}]

   The below tests are for the Incidents API group Check that Group by tag is on to ensure the endpoints are grouped by API route.

   1. Get Incidents

      • NOTE: This will only return incidents if they currently exists on the system for the current user.

      • Locate GET - Retrieves list of incident summaries and click the green Try It button.

      • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

        • Provide the PageNumber e.g. 2

        • Provide the PageSize e.g. 3

      • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

        • HTTP/1.1 200 OK

        • {"pageNumber":2,"pageSize":3,"pageCount":44,"itemCount":131,"hasPreviousPage":true,"hasNextPage":true,"isOutOfRange":false,"items":[{"status":"NewIncident","prospectiveCustomer":{"firstNames":"Frank","surname":"Williams"},"prospectiveCustomerVehicle":{"registrationNo":"LO22BNG","make":"VW","model":"Golf","groupName":"S1"},"id":"VMG-2048","externalReference":"TEST1234","createdAt":"2025-04-24T12:33:39+01:00","updatedAt":"2025-04-24T12:33:48+01:00"},{"status":"NewIncident","prospectiveCustomer":{"firstNames":"Jane","surname":"Doe"},"prospectiveCustomerVehicle":{"registrationNo":"LO20BHF","make":"VW","model":"Polo","groupName":"S2"},"id":"VMG-2044","externalReference":"TEST1234","createdAt":"2025-04-22T12:40:34+01:00","updatedAt":"2025-04-29T10:08:29+01:00"},{"status":"NewIncident","prospectiveCustomer":{"firstNames":"John","surname":"Smith"},"prospectiveCustomerVehicle":{"registrationNo":"DU07HZN","make":"VAUXHALL","model":"CORSA LIFE","groupName":"S2"},"id":"VMG-2037","externalReference":"RRN-150425-1332","createdAt":"2025-04-15T12:32:45+01:00","updatedAt":"2025-04-15T12:33:41+01:00"}]}