openapi.yml

openapi: 3.0.0
info:
  title: HMPPS Integration API
  description:
    A long-lived API that exposes data from HMPPS systems such as the National Offender Management Information
    System (NOMIS), nDelius (probation system) and Offender Assessment System (OASys), providing a single point
    of entry for consumers.
  version: 0.0.1

paths:
  /v1/persons:
    get:
      tags:
        - persons
      summary: Returns person(s) by search criteria. At least one query parameter must be specified.
      parameters:
        - in: query
          name: first_name
          schema:
            type: string
          required: false
          description: The first name of the person
        - in: query
          name: last_name
          schema:
            type: string
          required: false
          description: The last name of the person
        - in: query
          name: pnc_number
          schema:
            type: string
          required: false
          description: A URL-encoded pnc identifier
        - in: query
          name: date_of_birth
          schema:
            type: string
          required: false
          description: The date of birth of the person
        - in: query
          name: search_within_aliases
          schema:
            type: boolean
            default: false
          required: false
          description: Whether to return results that match the search criteria within the aliases of a person
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: Successfully performed the query on upstream APIs. An empty list is returned when no results are found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/Person"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "400":
          description: There were no query parameters passed in. At least one must be specified.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/NoQueryParametersBadRequestError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"
  /v1/persons/{hmppsId}:
    get:
      tags:
        - persons
      summary: Returns a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      prisonerOffenderSearch:
                        $ref: "#/components/schemas/Person"
                      probationOffenderSearch:
                        $ref: "#/components/schemas/Person"
        "404":
          description: Failed to find a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/images:
    get:
      tags:
        - persons
      summary: Returns metadata of images associated with a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description:  >
            Successfully found a person with the provided HMPPS ID.
            If a person doesn't have any images, then an empty list (`[]`) is
            returned in the `data` property.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/Image"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/images/{id}:
    get:
      tags:
        - images
      summary: Returns an image in bytes as a JPEG.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successfully found an image with the provided ID.
          content:
            image/jpeg:
              schema:
                type: string
                format: byte
        "404":
          description: Failed to find an image with the provided ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                ImageNotFoundError:
                  $ref: "#/components/examples/ImageNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/addresses:
    get:
      tags:
        - persons
      summary: Returns addresses associated with a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: Successfully found a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/Address"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/offences:
    get:
      tags:
        - persons
      summary: >
        Returns offences associated with a person.

        Note: This API does not contain the complete list of offences for a person.
        Offences are retrieved from Prison and Probation systems exclusively.
        Prison systems record only custodial sentences, while Probation systems record only the main offence and some additional offences for case management purposes. Other offences recorded by HMCTS and police may not be included.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: Successfully found offences for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/Offence"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find offences a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/alerts:
    get:
      tags:
        - persons
        - alerts
      summary: Returns alerts associated with a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: Successfully found alerts for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/Alert"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find alerts a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/sentences:
    get:
      tags:
        - persons
      summary: Returns sentences associated with a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: Successfully found sentences for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/Sentence"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find sentences a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/sentences/latest-key-dates-and-adjustments:
    get:
      tags:
        - persons
      summary: Returns the key dates and adjustments about a person's release from prison for their latest sentence.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found latest sentence key dates and adjustments for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/LatestSentenceKeyDatesAndAdjustments"
        "404":
          description: Failed to find sentences a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/risks/scores:
    get:
      tags:
        - risks
      summary: Returns risk scores from the last year associated with a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
      responses:
        "200":
          description: Successfully found risk scores for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/RiskScore"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find risk scores for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/risks/categories:
    get:
      tags:
        - persons
      summary: Returns the categories related to an offender.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found risk categories for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      offenderNo:
                        type: string
                      assessments:
                        type: array
                        minItems: 0
                        items:
                          $ref: "#/components/schemas/RiskAssessment"
                      category:
                        type: string
                      categoryCode:
                          type: string
        "404":
          description: Failed to find risk categories a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/risks/mappadetail:
    get:
      tags:
        - persons
      summary: Returns the mappa detail related to a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found mappa detail for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      level:
                        type: number
                        example: 1
                      levelDescription:
                        type: string
                        example: Description of M1
                      category:
                        type: number
                        example: 2
                      categoryDescription:
                        type: string
                        example: Description of M2
                      startDate:
                        type: string
                        format: date
                        example: 2024-02-07
                      reviewDate:
                        type: string
                        format: date
                        example: 2024-02-07
                      notes:
                        type: string
                        example: "Mappa Detail for X00001"
        "404":
          description: Failed to find risk-related mappa detail a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/needs:
    get:
      tags:
        - needs
      summary: >
        Returns criminogenic needs associated with a person.

        Note: Criminogenic needs are dynamic factors that are directly linked to criminal behaviour. Eight criminogenic needs are measured in OASys: Accommodation, Employability, Relationships, Lifestyle and Associates, Drug Misuse, Alcohol Misuse, Thinking & Behaviour and Attitudes. These are scored according to whether there is “no need”, “some need” or “severe need”, and a need is identified in a specific section based on calculations around these scores.
              However, the process by which needs are assessed is changing as early as next year (2024), specifically moving to a strength-based model that seeks to identify and develop the strengths of people with convictions. As a consequence of this, the information provided by this endpoint will also change.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found criminogenic needs for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Needs"
        "404":
          description: Failed to find criminogenic needs for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{hmppsId}/risks:
    get:
      tags:
        - risks
      summary: Returns Risk of Serious Harm (ROSH) risks associated with a person. Returns only assessments completed in the last year.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found risks for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/Risks"
        "404":
          description: Failed to find risks for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/epf/person-details/{hmppsId}/{eventNumber}:
    get:
      summary: Probation case information for the Effective Proposals Framework service
      description: "<p>Accepts a Hmpps Id (hmppsId) and Delius Event number\n\
          \            and returns a data structure giving background information on\
          \ the probation case\n            for use in the Effective Proposals Framework\
          \ system. The information is used to\n            reduce the need for the\
          \ EPF user to re-key information already held in Delius.</p> "
      parameters:
        - name: hmppsId
          in: path
          required: true
          schema:
            type: string
        - name: eventNumber
          in: path
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseDetails'
        "404":
          description: "A person detail with the provided HmppsId and event number does not exist in Delius."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{Id}/adjudications:
    get:
      summary: Returns adjudications associated with a person.
      parameters:
        - name: hmppsId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Adjudication'
        "404":
          description: "Adjudications for the person with the provided HmppsId does not exist."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{HmppsId}/licences/conditions:
    get:
      summary: Returns license conditions associated with a person.
      parameters:
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found licenses for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonLicencesData"
        "404":
          description: Failed to find licenses for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /v1/persons/{HmppsId}/case-notes:
    get:
      summary: Returns case notes associated with a person.
      parameters:
        - in: query
          name: startDate
          schema:
             type: string
          required: false
          description: Filter case notes from this date
        - in: query
          name: endDate
          schema:
            type: string
          required: false
          description: Filter case notes up to this date
        - in: query
          name: locationId
          schema:
            type: string
          required: false
          description: Filter by the location. example MDI
        - $ref: "#/components/parameters/HmppsId"
      responses:
        "200":
          description: Successfully found case notes for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    minItems: 0
                    items:
                      $ref: "#/components/schemas/CaseNote"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
        "404":
          description: Failed to find case notes for a person with the provided HMPPS ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                PersonNotFoundError:
                  $ref: "#/components/examples/PersonNotFoundError"
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/accommodations:
    get:
      summary: FUTURE ENDPOINT - Returns accommodation and referral information associated with a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/interventions:
    get:
      summary: FUTURE ENDPOINT - Returns activities and Non-Statutory Interventions (NSIs) associated with a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/key-workers:
    get:
      summary: FUTURE ENDPOINT - Returns responsible officer history, transfer history and consolidated transfer review associated with a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/prisoner-visits:
    get:
      summary: FUTURE ENDPOINT -  Returns prisoner visits associated with a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/probation-contact-events:
    get:
      summary: FUTURE ENDPOINT - Returns probation contact events associated with a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/security:
    get:
      summary: FUTURE ENDPOINT - Returns security information such as prisoner non-associations and prisoner incidents for a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

  /{TBC}/v1/persons/{Id}/special-needs:
    get:
      summary: FUTURE ENDPOINT -  Returns special needs such as drugs test summaries, drug history and drugs test lists associated with a person.
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: Success.
        "500":
          description: An upstream service was not responding, so we cannot verify the accuracy of any data we did get.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                NoQueryParametersBadRequestError:
                  $ref: "#/components/examples/InternalServerError"

components:
  parameters:
    HmppsId:
      name: hmppsId
      description: A URL-encoded HMPPS identifier
      example: 2008%2F0545166T
      in: path
      required: true
      schema:
        type: string
    Id:
      name: Id
      description: An Id (TBC), potentially Case Reference Number (CRN)
      example: X00001
      in: path
      required: true
      schema:
        type: string
    Page:
      name: page
      in: query
      schema:
        type: number
        minimum: 0
        default: 1
      required: false
      description: The page number (starting from 1)
    PerPage:
      name: perPage
      in: query
      schema:
        type: number
        minimum: 1
        default: 10
      required: false
      description: The maximum number of results for a page
  schemas:
    Address:
      type: object
      properties:
        country:
          type: string
          example: England
        county:
          type: string
          example: Greater London
        endDate:
          type: string
          example: 20 May 2023
          format: date
        locality:
          type: string
          example: London Bridge
        name:
          type: string
          description: Name of the building of residence
        noFixedAddress:
          type: boolean
          example: true
          description: Indicates whether the person has a permanent place of residence
        number:
          type: string
          example: 1
        postcode:
          type: string
          example: SE1 1TE
        startDate:
          type: string
          example: 1 January 2023
          format: date
        street:
          type: string
          example: O'Meara Street
        town:
          type: string
          example: London
        types:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/AddressType"
          description: Type or usage of address
        notes:
          type: string
          example: This is their partner's address.
    AddressType:
      type: object
      properties:
        code:
          type: string
          example: BUS
          description: Address type code
        description:
          type: string
          example: Business Address
          description: Description of address type
    Adjudication:
      type: object
      properties:
        incidentDetails:
          $ref: '#/components/schemas/IncidentDetails'
        isYouthOffender:
          type: boolean
        incidentRole:
          $ref: '#/components/schemas/IncidentRole'
        offenceDetails:
          $ref: '#/components/schemas/OffenceDetail'
        hearings:
          type: array
          items:
            $ref: '#/components/schemas/Hearing'
        outcomes:
          type: array
          items:
            $ref: '#/components/schemas/Outcome'
        punishments:
          type: array
          items:
            $ref: '#/components/schemas/Punishment'
        punishmentComments:
          type: array
          items:
            $ref: '#/components/schemas/PunishmentComment'
    Alert:
      type: object
      properties:
        offenderNo:
          type: string
          example: Z1234ZZ
          description: Offender unique reference
        type:
          type: string
          example: X
          description: Alert type
        typeDescription:
          type: string
          example: Security
          description: Alert type description
        code:
          type: string
          example: PO
          description: Alert code
        codeDescription:
          type: string
          example: MAPPA Nominal
          description: Alert code description
        comment:
          type: string
          example: Professional lock pick
          description: Alert comment
        dateCreated:
          type: string
          format: date
          example: 2014-09-23
          description: Date of the alert, which might differ from the date it was created
        dateExpired:
          type: string
          format: date
          example: 2015-09-23
          description: Date that the alert expires
        expired:
          type: boolean
          example: true
          description: Whether the alert has expired
        active:
          type: boolean
          example: false
          description: Whether the alert is active
    Alias:
      type: object
      properties:
        firstName:
          type: string
          example: John
          description: first name
        middleName:
          type: string
          example: Michael
          nullable: true
          description: middle name
        lastName:
          type: string
          example: Marston
          description: last name
        dateOfBirth:
          type: string
          format: date
          example: 1965-12-01
          description: date of birth
        gender:
          type: string
          example: Male
          description: gender
        ethnicity:
          type: string
          example: Prefer not to say
          description: ethnicity
    CaseDetails:
      required:
        - age
        - dateOfBirth
        - gender
        - name
      type: object
      properties:
        nomsId:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        dateOfBirth:
          type: string
          format: date
        gender:
          type: string
        sentence:
          $ref: '#/components/schemas/CaseSentence'
        responsibleProvider:
          $ref: '#/components/schemas/ResponsibleProvider'
        ogrsScore:
          type: integer
          format: int64
        age:
          type: integer
          format: int64
        ageAtRelease:
          type: integer
          format: int64
    CaseNote:
      type: object
      properties:
        caseNoteId:
          type: string
          example: 1234
        offenderIdentifier:
          type: string
          example: A1234AA
        type:
          type: string
          example: KA
        typeDescription:
          type: string
          example: Key Worker
        subType:
          type: string
          example: KS
        subTypeDescription:
          type: string
          example: Key Worker Session
        CreatDateTime:
          type: string
          format: date
          example: 2023-09-05T10:15:41
          description: Date and Time of Case Note creation
        occurrenceDateTime:
          type: string
          format: date
          example: 2023-09-05T10:15:41
          description: Date and Time of when case note contact with offender was made
        text:
          type: string
          example: This is some text
        locationId:
          type: string
          example: MDI
        amendments:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/CaseNoteAmendment"
          description: List of amendments to the case note
    CaseNoteAmendment:
      type: object
      properties:
        caseNoteAmendmentId:
          type: integer
          example: 123232
          format: int64
        creationDateTime:
          type: string
          format: date
          example: 2023-09-05T10:15:41
          description: Date and Time of Case Note creation
        addtionalNoteText:
          type: string
          example: Some Additional Text
    CaseSentence:
      required:
        - date
        - sentencingCourt
      type: object
      properties:
        date:
          type: string
          format: date
        sentencingCourt:
          $ref: '#/components/schemas/Court'
        releaseDate:
          type: string
          format: date
    ContactDetails:
      properties:
        phoneNumbers:
          $ref: "#/components/schemas/PhoneNumbers"
        emails:
          type: array
          items:
            type: string
            example: "leslie.knope@pawnee.gov"
          description: A list of email addresses
    Court:
      required:
        - name
      type: object
      properties:
        name:
          type: string
    Error:
      type: object
      properties:
        status:
          type: integer
          enum: [ 400, 404, 500 ]
        errorCode:
          type: integer
          nullable: true
          example: null
        userMessage:
          type: string
        developerMessage:
          type: string
        moreInfo:
          type: string
          nullable: true
          example: null
    Hearing:
      type: object
      properties:
        dateTimeOfHearing:
          type: string
          format: date-time
          nullable: true
        oicHearingType:
          type: string
          nullable: true
        outcome:
          nullable: true
    HearingOutcome:
      type: object
      properties:
        code:
          type: string
          nullable: true
        details:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
        quashedReason:
          type: string
          nullable: true
        canRemove:
          type: boolean
          nullable: true
    Identifiers:
      type: object
      description: Other unique identifiers for a person.
      properties:
        nomisNumber:
          type: string
          example: A1234AA
          description: A prisoner identifier from NOMIS.
        croNumber:
          type: string
          example: SF80/655108T
          description: A Criminal Records Office identifier from National Identification Service (NIS) or National Automated Fingerprint Identification System (NAFIS).
        deliusCrn:
          type: string
          example: X00001
          description: A Case Reference Number from Delius.
    Image:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
          format: int64
          example: 2461788
          description: The Image ID, in reference to a unique identifier.
        active:
          type: boolean
          example: true
          description: A flag to indicate whether an image is in active use. It is no guarantee that the latest uploaded image will be the active one.
        captureDateTime:
          type: string
          format: date-time
          example: 2015-05-27T17:13:59
          description: The Date and Time of when the image was captured.
        view:
          type: string
          example: FACE
          enum: [FACE, TAT, OTH, SCAR, MARK, OIC]
          description: >
            View is the subject focus; describing the inner focus or subject of the image, normally referring to a marking, tattoo or deeper level focus of the orientation. In practise this is the interior foci of what is captured in the 'orientation' field.
              Options include:
              `FACE` - Facing,
              `TAT` - Tattoo,
              `OTH` - Other,
              `SCAR` - Scar,
              `MARK` - Mark,
              `OIC` - Offence in Custody
        orientation:
          type: string
          example: FRONT
          enum: [ANKLE, ARM, DAMAGE, EAR, ELBOW, FACE, FIGHT, FINGER, FOOT, FRONT, HAND, HEAD, INCIDENT, INJURY, KNEE, LEG, LIP, NECK, NOSE, SHOULDER, THIGH, TOE, TORSO]
          description: >
            Orientation is the scope focus; describing the scope or outer focus of the image, normally referring to the highest level object of interest within the bounds of the photo itself. This is normally a body part or an angle of photography, such as a photo of someone’s facial view (`FRONT`) or arm (`ARM`).
              Options include:
              `ANKLE` - Ankle,
              `ARM` - Arm,
              `DAMAGE` - Damage,
              `EAR` - Ear,
              `ELBOW` - Elbow,
              `FACE` - Face,
              `FIGHT` - Fight,
              `FINGER` - Finger,
              `FOOT` - Foot,
              `FRONT` - Front Facial View,
              `HAND` - Hand,
              `HEAD` - Head,
              `INCIDENT` - Incident,
              `INJURY` - Injury,
              `KNEE` - Knee,
              `LEG` - Leg,
              `LIP` - Lip,
              `NECK` - Neck,
              `NOSE` - Nose,
              `SHOULDER` - Shoulder,
              `THIGH` - Thigh,
              `TOE` - Toe,
              `TORSO` - Torso
        type:
          type: string
          example: OFF_BKG
          enum: [OFF_BKG, OFF_IDM, OIC, PPTY]
          description: >
            Type is the contextual focus; describing the context or scenario the image was taken within. It could be for a particular purpose or capturing the results of a particular type of incident.
              Options include:
              `OFF_BKG` - Offender Booking,
              `OFF_IDM` - Offender Identification Marks,
              `OIC` - Offence In Custody,
              `PPTY` - Property Image
    IncidentDetails:
      type: object
      properties:
        dateTimeOfIncident:
          type: string
          format: date-time
          nullable: true
    IncidentRole:
      type: object
      properties:
        roleCode:
          type: string
          nullable: true
        offenceRule:
          nullable: true
    LatestSentenceKeyDatesAndAdjustments:
      type: object
      properties:
        adjustments:
          $ref: "#/components/schemas/SentenceAdjustments"
        automaticRelease:
          $ref: "#/components/schemas/SentenceKeyDate"
        conditionalRelease:
          $ref: "#/components/schemas/SentenceKeyDate"
        dtoPostRecallRelease:
          $ref: "#/components/schemas/SentenceKeyDate"
        earlyTerm:
          $ref: "#/components/schemas/SentenceKeyDate"
        homeDetentionCurfew:
          $ref: "#/components/schemas/HomeDetentionCurfewDate"
        lateTerm:
          $ref: "#/components/schemas/SentenceKeyDate"
        licenceExpiry:
          $ref: "#/components/schemas/SentenceKeyDate"
        midTerm:
          $ref: "#/components/schemas/SentenceKeyDate"
        nonDto:
          $ref: "#/components/schemas/NonDtoDate"
        nonParole:
          $ref: "#/components/schemas/SentenceKeyDate"
        paroleEligibility:
          $ref: "#/components/schemas/SentenceKeyDate"
        postRecallRelease:
          $ref: "#/components/schemas/SentenceKeyDate"
        release:
          $ref: "#/components/schemas/ReleaseDate"
        sentence:
          $ref: "#/components/schemas/SentenceDate"
        topupSupervision:
          $ref: "#/components/schemas/TopupSupervision"
        actualParoleDate:
          type: string
          format: date
          example: 2023-03-01
          description: the offender's actual parole date
        earlyRemovalSchemeEligibilityDate:
          type: string
          format: date
          example: 2023-03-01
          description: the date on which offender will be eligible for early removal (under the Early Removal Scheme for foreign nationals).
        releaseOnTemporaryLicenceDate:
          type: string
          format: date
          example: 2023-03-01
          description: the date on which offender will be released on temporary licence.
        tariffDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which minimum term is reached for parole (indeterminate/life sentences).
        tariffEarlyRemovalSchemeEligibilityDate:
          type: string
          format: date
          example: 2023-03-01
          description: tariffEarlyRemovalSchemeEligibilityDate.

    Licence:
      type: object
      properties:
        status:
          type: string
          example: IN_PROGRESS
          "enum": [ "IN_PROGRESS","SUBMITTED","APPROVED","ACTIVE","VARIATION_IN_PROGRESS","VARIATION_SUBMITTED","VARIATION_APPROVED","VARIATION_REJECTED" ]
          description: Licence status
        typeCode:
          type: string
          example: AP
          enum: [ "AP","PSS","AP_PSS" ]
          description: The type of licence
        createdDate:
          type: string
          format: date
          example: 2015-09-23
          description: The date and time when the version/variation of the licence was created at
        approvedDate:
          type: string
          format: date
          example: 2015-09-24
          description: The date and time that the prison approved the licence, where licences approved before 01/04/2023 will not have an approved time
        updatedDate:
          type: string
          format: date
          example: 2015-10-23
          description: The date and time that the licence was last updated
        conditions:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/LicenceCondition"
          description: list of conditions. The type of conditions on a licence which can be AP (All Purpose) and/or PSS (Post Sentence Supervision)
    LicenceCondition:
      type: object
      properties:
        type:
          type: string
          example: Standard
          nullable: true
          description: Condition type
        code:
          type: string
          example: 5a105297-dce1-4d18-b9ea-4195b46b7594
          nullable: true
          description: The code shared by all instances of this condition
        category:
          type: string
          example: Residence at a specific place
          nullable: true
          description: The category to which the condition belongs
        condition:
          type: string
          example: You must not enter the location X
          nullable: true
          description: The condition of a licence, this can be a standard condition, a combination of inputted text and template text including any user input or the input for the bespoke condition
    Name:
      required:
        - forename
        - surname
      type: object
      properties:
        forename:
          type: string
        middleName:
          type: string
        surname:
          type: string
    Offence:
      type: object
      properties:
        serviceSource:
          type: string
          enum: [ NOMIS, NDELIUS ]
          example: NOMIS
          description: Which upstream API service the sentence originates from
        systemSource:
          type: string
          enum: [ PRISON_SYSTEMS, PROBATION_SYSTEMS ]
          example: PROBATION_SYSTEMS
          description: Which upstream API system the sentence originates from
        cjsCode:
          type: string
          example: RR84170
          description: Criminal Justice System offence code
        # Court dates has been documented as single string, however it's actually a list of strings. This has been done
        # in order to temporarily fix a rendering issue in our API docs whilst we look for a longer term solution for it.
        courtDates:
          type: string
          format: date
          description: Court dates associated with offences
          example:
            - "2018-02-10"
            - "2019-02-10"
        description:
          type: string
          example: Commit an act / series of acts with intent to pervert the course of public justice
          description: Description associated with the CJS offence code
        endDate:
          type: string
          format: date
          example: 2018-03-10
          description: End date of range over which the offence was believed to have taken place
        hoCode:
          type: string
          example: 06601
          description: Home Office code (HO Code)
        startDate:
          type: string
          format: date
          example: 1965-12-01
          description: Date the offence took place or start date if the offence occurred over a period of time
        statuteCode:
          type: string
          example: RR84
          description: Statute code
    OffenceDetail:
      type: object
      properties:
        offenceCode:
          type: number
          nullable: true
        offenceRule:
          nullable: true
    OffenceRuleDetails:
      type: object
      properties:
        paragraphNumber:
          type: string
          nullable: true
        paragraphDescription:
          type: string
          nullable: true
    Outcome:
      type: object
      properties:
        code:
          type: string
          nullable: true
        details:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
        quashedReason:
          type: string
          nullable: true
        canRemove:
          type: boolean
          nullable: true
    Pagination:
      type: object
      properties:
        isLastPage:
          type: boolean
          example: true
          description: Is the current page the last one?
        count:
          type: integer
          example: 1
          description: The number of results in `data` for the current page
        page:
          type: integer
          example: 1
          description: The current page number
        perPage:
          type: integer
          example: 10
          description: The maximum number of results in `data` for a page
        totalCount:
          type: integer
          example: 1
          description: The total number of results in `data` across all pages
        totalPages:
          type: integer
          example: 1
          description: The total number of pages
    Person:
      type: object
      properties:
        firstName:
          type: string
          example: Arthur
          description: first name
        middleName:
          type: string
          example: John
          nullable: true
          description: middle name
        lastName:
          type: string
          example: Morgan
          description: last name
        dateOfBirth:
          type: string
          format: date
          example: 1965-12-01
          description: date of birth
        gender:
          type: string
          example: Male
          description: gender
        ethnicity:
          type: string
          example: "White: Eng./Welsh/Scot./N.Irish/British"
          description: ethnicity
        aliases:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/Alias"
          description: list of aliases
        identifiers:
          $ref: "#/components/schemas/Identifiers"
        pncId:
          type: string
          example: 2008/0545166T
          description: An identifier from the Police National Computer (PNC)
        hmppsId:
          type: string
          example: X00001
          description: Currently a hmppsId is a CRN identifier however this will change in the future to be a new unique Hmpps identifier
        contactDetails:
          $ref: "#/components/schemas/ContactDetails"
    PhoneNumbers:
      type: array
      items:
        type: object
        properties:
          number:
            type: string
            example: "079123456789"
            description: "A phone number"
          type:
            type: string
            example: "TELEPHONE"
            description: "The type of number"
    PersonLicencesData:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/PersonLicences"
    PersonLicences:
      type: object
      properties:
        hmppsId:
          type: string
          example: 2008/0545166T
          description: Currently a hmppsId is a PNC identifier however this will change in the near future to be a CRN identifier
        offenderNumber:
          type: string
          example: Z1234ZZ
          nullable: true
          description: The prison identifier for the person on the licence. Also known as the NOMIS ID
        licences:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/Licence"
          description: list of licences
    Punishment:
      type: object
      properties:
        type:
          type: string
          nullable: true
        privilegeType:
          type: string
          nullable: true
        otherPrivilege:
          type: string
          nullable: true
        schedule:
          nullable: true
    PunishmentComment:
      type: object
      properties:
        comment:
          type: string
          nullable: true
        reasonForChange:
          type: string
          nullable: true
        dateTime:
          type: string
          format: date-time
          nullable: true
    PunishmentSchedule:
      type: object
      properties:
        days:
          type: number
          nullable: true
        startDate:
          type: string
          format: date
          nullable: true
        endDate:
          type: string
          format: date
          nullable: true
        suspendedUntil:
          type: string
          format: date
          nullable: true
    ResponsibleProvider:
      required:
        - code
        - name
      type: object
      properties:
        code:
          type: string
        name:
          type: string
    Sentence:
      type: object
      properties:
        serviceSource:
          type: string
          enum: [NOMIS, NDELIUS]
          example: NOMIS
          description: Which upstream API service the sentence originates from
        systemSource:
          type: string
          enum: [ PRISON_SYSTEMS, PROBATION_SYSTEMS ]
          example: PROBATION_SYSTEMS
          description: Which upstream API system the sentence originates from
        dateOfSentencing:
          type: string
          format: date
          example: 2009-09-09
          description: Date of sentencing
        description:
          type: string
          example: Young Offender Inst - >=12 mths
          description: Description of the sentence
        isActive:
          type: boolean
          example: true
          description: Whether the sentence is active
        isCustodial:
          type: boolean
          example: true
          description: Whether the sentence is a custodial sentence
        fineAmount:
          type: number
          example: 480.59
          description: The amount of fine related to the sentence and offence
        length:
          $ref: "#/components/schemas/SentenceLength"
    SentenceAdjustments:
      type: object
      properties:
        additionalDaysAwarded:
          type: integer
          example: 10
          description: Number of additional days awarded
        unlawfullyAtLarge:
          type: integer
          example: 16
          description: Number unlawfully at large days
        lawfullyAtLarge:
          type: integer
          example: 11
          description: Number of lawfully at large days
        restoredAdditionalDaysAwarded:
          type: integer
          example: 20
          description: Number of restored additional days awarded
        specialRemission:
          type: integer
          example: 14
          description: Number of special remission days
        recallSentenceRemand:
          type: integer
          example: 7
          description: Number of recall sentence remand days
        recallSentenceTaggedBail:
          type: integer
          example: 19
          description: Number of recall sentence tagged bail days
        remand:
          type: integer
          example: 3
          description: Number of remand days
        taggedBail:
          type: integer
          example: 13
          description: Number of tagged bail days
        unusedRemand:
          type: integer
          example: 13
          description: Number of tagged bail days
    SentenceKeyDate:
      type: object
      properties:
        date:
          type: string
          format: date
          example: 2023-03-01
          description: release date for offender
        overrideDate:
          type: string
          format: date
          example: 2023-03-01
          description: release override date for offender
        calculatedDate:
          type: string
          format: date
          example: 2023-03-01
          description: release calculated date for offender
    HomeDetentionCurfewDate:
      type: object
      properties:
        actualDate:
          type: string
          format: date
          example: 2023-03-01
          description: the offender's actual home detention curfew date.
        eligibilityCalculatedDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which offender will be eligible for home detention curfew (calculated).
        eligibilityDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which offender will be eligible for home detention curfew.
        eligibilityOverrideDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which offender will be eligible for home detention curfew (override).
        endDate:
          type: string
          format: date
          example: 2023-03-01
          description: Offender's home detention curfew end date - calculated as one day before the releaseDate.
    NonDtoDate:
      type: object
      properties:
        date:
          type: string
          format: date
          example: 2023-03-01
          description: Release date for non-DTO sentence (if applicable). This will be based on one of ARD, CRD, NPD or PRRD.
        releaseDateType:
          type: string
          enum: [ ARD, CRD, NPD, PRRD ]
          example: ARD
          description: Indicates which type of non-DTO release date is the effective release date. One of 'ARD', 'CRD', 'NPD' or 'PRRD'.
    ReleaseDate:
      type: object
      properties:
        date:
          type: string
          format: date
          example: 2023-03-01
          description: >
            Confirmed, actual, approved, provisional or calculated release date for offender, according to offender release date algorithm.

            Algorithm
            If there is a confirmed release date, the offender release date is the confirmed release date.
            If there is no confirmed release date for the offender, the offender release date is either the actual parole date or the home detention curfew actual date.
            If there is no confirmed release date, actual parole date or home detention curfew actual date for the offender, the release date is the later of the nonDtoReleaseDate or midTermDate value (if either or both are present)
        confirmedDate:
          type: string
          format: date
          example: 2023-03-01
          description: Confirmed release date for offender.
    SentenceDate:
      type: object
      properties:
        effectiveEndDate:
          type: string
          format: date
          example: 2023-03-01
          description: Effective sentence end date.
        expiryCalculatedDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which sentence expired (as calculated by NOMIS).
        expiryDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which sentence expires.
        expiryOverrideDate:
          type: string
          format: date
          example: 2023-03-01
          description: date on which sentence expires (override).
        startDate:
          type: string
          format: date
          example: 2023-03-01
          description: Sentence start date.
    TopupSupervision:
      type: object
      properties:
        expiryCalculatedDate:
          type: string
          format: date
          example: 2023-03-01
          description: (calculated) - top-up supervision expiry date for offender.
        expiryDate:
            type: string
            format: date
            example: 2023-03-01
            description: top-up supervision expiry date for offender.
        expiryOverrideDate:
          type: string
          format: date
          example: 2023-03-01
          description: (override) - top-up supervision expiry date for offender.
        startDate:
          type: string
          format: date
          example: 2023-03-01
          description: Top-up supervision start date for offender - calculated as licence end date + 1 day or releaseDate if licence end date not set.
    SentenceLength:
      type: object
      properties:
        duration:
          type: integer
          example: 10
          description: Duration of the sentence
        units:
          type: string
          enum: [Hours, Days, Weeks, Months, Years]
          example: Hours
          description: Time unit that is used in combination with the duration field
        terms:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/SentenceTerm"
    SentenceTerm:
      type: object
      properties:
        years:
          type: integer
          example: 5
          description: Number of years in the term
        months:
          type: integer
          example: 4
          description: Number of months in the term
        weeks:
          type: integer
          example: 3
          description: Number of weeks in the term
        days:
          type: integer
          example: 2
          description: Number of days in the term
        prisonTermCode:
          type: string
          enum: [CUR, DEF, DET, HOURS, IMP, LIC, PSYCH, SCUS, SEC104, SEC105, SEC86, SUP, SUSP]
          example: IMP
          description: >
            The sentence term code
              Options include:
              `CUR` - Curfew Period,
              `DEF` - Deferment Period,
              `DET` - Detention,
              `HOURS` - Hours Ordered,
              `IMP` - Imprisonment,
              `LIC` - Licence,
              `PSYCH` - Psychiatric Hospital,
              `SCUS` - Custodial Period,
              `SEC104` - Breach of supervision requirements,
              `SEC105` - Breach due to imprisonable offence,
              `SEC86` - Section 86 of 2000 Act,
              `SUP` - Sentence Length,
              `SUSP` - Suspension Period
    RiskAssessment:
      type: object
      properties:
        classificationCode:
          type: string
          example: C
          description: The classification code of the risk
        classification:
          type: string
          example: Cat C
          description: The classification of the code
        assessmentCode:
          type: string
          example: CATEGORY
          description: The assessment code
        assessmentDescription:
          type: string
          example: Categorisation
          description: The description of the assessment
        assessmentDate:
          type: string
          example: 2018-02-11
          description: The date of the assessment
        nextReviewDate:
          type: string
          example: 2018-02-11
          description: Next review date
        assessmentAgencyId:
          type: string
          example: MDI
          description: Agency ID of the assessment
        assessmentStatus:
          type: string
          example: P
          description: The status of the assessment
        assessmentComment:
          type: string
          example: Comment details
          description: Comments regarding the assessment
    RiskScore:
      type: object
      properties:
        completedDate:
          type: string
          format: date
          example: 2023-09-05T10:15:41
          description: Risk scores calculation completion date
        assessmentStatus:
          type: string
          enum: [ COMPLETE, LOCKED_INCOMPLETE ]
          example: COMPLETE
          description: Whether the risk score calculation is complete
        groupReconviction:
          $ref: "#/components/schemas/GroupReconviction"
        violencePredictor:
          $ref: "#/components/schemas/ViolencePredictor"
        generalPredictor:
          $ref: "#/components/schemas/GeneralPredictor"
        riskOfSeriousRecidivism:
          $ref: "#/components/schemas/RiskOfSeriousRecidivism"
        sexualPredictor:
          $ref: "#/components/schemas/SexualPredictor"


    GroupReconviction:
      type: object
      properties:
        scoreLevel:
          type: string
          enum: [ LOW, MEDIUM, HIGH, VERY_HIGH, NOT_APPLICABLE ]
          example: LOW
          description: >
            Indicator for risk of group reconviction. Options include:
            `LOW`,
            `MEDIUM`,
            `HIGH`,
            `VERY_HIGH`,
            `NOT_APPLICABLE`

    ViolencePredictor:
      type: object
      properties:
        scoreLevel:
          type: string
          enum: [ LOW, MEDIUM, HIGH, VERY_HIGH, NOT_APPLICABLE ]
          example: MEDIUM
          description: >
            Indicator for risk of violence. Options include:
            `LOW`,
            `MEDIUM`,
            `HIGH`,
            `VERY_HIGH`,
            `NOT_APPLICABLE`

    GeneralPredictor:
      type: object
      properties:
        scoreLevel:
          type: string
          enum: [ LOW, MEDIUM, HIGH, VERY_HIGH, NOT_APPLICABLE ]
          example: VERY_HIGH
          description: >
            Indicator for general prediction. Options include:
            `LOW`,
            `MEDIUM`,
            `HIGH`,
            `VERY_HIGH`,
            `NOT_APPLICABLE`

    RiskOfSeriousRecidivism:
      type: object
      properties:
        scoreLevel:
          type: string
          enum: [ LOW, MEDIUM, HIGH, VERY_HIGH, NOT_APPLICABLE ]
          example: MEDIUM
          description: >
            Indicator for risk of serious recidivism. Options include:
            `LOW`,
            `MEDIUM`,
            `HIGH`,
            `VERY_HIGH`,
            `NOT_APPLICABLE`

    SexualPredictor:
      type: object
      properties:
        indecentScoreLevel:
          type: string
          enum: [ LOW, MEDIUM, HIGH, VERY_HIGH, NOT_APPLICABLE ]
          example: HIGH
          description: >
            Indicator for risk of sexual indecency. Options include:
            `LOW`,
            `MEDIUM`,
            `HIGH`,
            `VERY_HIGH`,
            `NOT_APPLICABLE`,
        contactScoreLevel:
          type: string
          enum: [ LOW, MEDIUM, HIGH, VERY_HIGH, NOT_APPLICABLE ]
          example: MEDIUM
          description: >
            Indicator for risk of sexual contact. Options include:
            `LOW`,
            `MEDIUM`,
            `HIGH`,
            `VERY_HIGH`,
            `NOT_APPLICABLE`,

    Risks:
      type: object
      properties:
        assessedOn:
          type: string
          format: date
          example: 2023-09-05T10:15:41
          description: Date of risk assessment
        riskToSelf:
          $ref: "#/components/schemas/RiskToSelf"
        otherRisks:
          $ref: "#/components/schemas/OtherRisks"
        summary:
          $ref: "#/components/schemas/Summary"

    RiskToSelf:
      type: object
      properties:
        suicide:
          $ref: "#/components/schemas/Risk"
        selfHarm:
          $ref: "#/components/schemas/Risk"
        custody:
          $ref: "#/components/schemas/Risk"
        hostelSetting:
          $ref: "#/components/schemas/Risk"
        vulnerability:
          $ref: "#/components/schemas/Risk"

    Risk:
      type: object
      properties:
        risk:
          type: string
          example: "YES"
          enum: [ YES, NO, DK, NA ]
          description: Presence of risk
        previous:
          type: string
          example: "NO"
          enum: [ YES, NO, DK, NA ]
          description: Previous concerns
        previousConcernsText:
          type: string
          example: "Risk of self harm concerns due to ..."
          description: Supporting comments for any previous concerns
        current:
          type: string
          example: "YES"
          enum: [ YES, NO, DK, NA ]
          description: Current concerns
        currentConcernsText:
          type: string
          example: "Risk of self harm concerns due to ..."
          description: Supporting comments for any current concerns

    OtherRisks:
      type: object
      properties:
        escapeOrAbscond:
          type: string
          example: "YES"
          enum: [ YES, NO, DK, NA ]
          description: Risk of escape/abscond
        controlIssuesDisruptiveBehaviour:
          type: string
          example: "DK"
          enum: [ YES, NO, DK, NA ]
          description: Risk control issues/disruptive behaviour
        breachOfTrust:
          type: string
          example: "NO"
          enum: [ YES, NO, DK, NA ]
          description: Risk of breach of trust
        riskToOtherPrisoners:
          type: string
          example: "YES"
          enum: [ YES, NO, DK, NA ]
          description: Risk to other prisoners

    Summary:
      type: object
      properties:
        whoIsAtRisk:
          type: string
          example: "X, Y and Z are at risk"
          description: Who is at risk
        natureOfRisk:
          type: string
          example: "The nature of the risk is X"
          description: What is the nature of the risk
        riskImminence:
          type: string
          example: The risk is imminent and more probable in X situation
          description: When is the risk likely to be greatest. Consider the timescale and indicate whether risk is immediate or not. Consider the risks in custody as well as on release.
        riskIncreaseFactors:
          type: string
          example: If offender is in situation X the risk can be higher
          description: What circumstances are likely to increase risk. Describe factors, actions, events which might increase level of risk, now and in the future.
        riskMitigationFactors:
          type: string
          example: Giving offender therapy in X will reduce the risk
          description: What factors are likely to reduce the risk. Describe factors, actions, and events which may reduce or contain the level of risk. What has previously stopped them?
        overallRiskLevel:
          type: string
          example: HIGH
          enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
          description: The overall risk level
        riskInCommunity:
          type: object
          description: >
            Assess the risk of serious harm the offender poses on the basis that they could be released imminently back into the community. This field is a map which can return all or some of the properties given.
          properties:
            children:
              type: string
              example: HIGH
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            public:
              type: string
              example: Medium
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            knownAdult:
              type: string
              example: VERY_HIGH
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            staff:
              type: string
              example: HIGH
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            prisoners:
              type: string
              example: LOW
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
        riskInCustody:
          type: object
          description: >
            Assess both the risk of serious harm the offender presents now, in custody, and the risk they could present to others whilst in a custodial setting. This field is a map which can return all or some of the properties given.
          properties:
            children:
              type: string
              example: HIGH
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            public:
              type: string
              example: Medium
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            knownAdult:
              type: string
              example: VERY_HIGH
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            staff:
              type: string
              example: HIGH
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]
            prisoners:
              type: string
              example: LOW
              enum: [ VERY_HIGH, HIGH, MEDIUM, LOW ]

    Needs:
      type: object
      properties:
        assessedOn:
          type: string
          format: date
          example: 2023-09-05T10:15:41
          description: Needs assessment completion date
        identifiedNeeds:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/Need"
        notIdentifiedNeeds:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/Need"
        unansweredNeeds:
          type: array
          minItems: 0
          items:
            $ref: "#/components/schemas/Need"

    Need:
      type: object
      properties:
        type:
          type: string
          example: DRUG_MISUSE
          description: The type of need
        riskOfHarm:
          type: boolean
          example: true
          description: Risk of harm
        riskOfReoffending:
          type: boolean
          example: true
          description: Risk of reoffending
        severity:
          type: string
          example: "NO_NEED"
          description: Severity of need

  examples:
    PersonNotFoundError:
      value:
        status: 404
        errorCode: null
        userMessage: "404 Not found error: Could not find person with HMPPS id: 2003/0011991D"
        developerMessage: "Could not find person with HMPPS id: 2003/0011991D"
        moreInfo: null
    ImageNotFoundError:
      value:
        status: 404
        errorCode: null
        userMessage: "404 Not found error: Could not find an image with id: 123456"
        developerMessage: "Could not find an image with id: 123456"
        moreInfo: null
    NoQueryParametersBadRequestError:
      value:
        status: 400,
        errorCode: null,
        userMessage: "Validation failure: No query parameters specified."
        developerMessage: "No query parameters specified."
        moreInfo: null
    InternalServerError:
      value:
        status: 500
        errorCode: null,
        userMessage: "Internal Server Error"
        developerMessage: "Unable to complete request as an upstream service is not responding."
        moreInfo: null