openapi: 3.0.3
info:
  title: 'Kamma HMO Checker API'
  description: 'Kamma HMO Checker API docs.'
  version: 1.0.0
servers:
  -
    url: 'https://hmo-checker.api.kammadata.com'
paths:
  /api/hmo-check:
    post:
      summary: 'HMO Checker.'
      description: 'Determine the HMO state for a given address, determining if the given UPRN has ever had an HMO licence.'
      parameters:
        -
          in: header
          name: Content-Type
          description: ''
          example: application/json
          schema:
            type: string
        -
          in: header
          name: Accept
          description: ''
          example: application/json
          schema:
            type: string
      responses:
        200:
          description: 'when no licence match is found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 918cf0cc-75ba-4459-a19f-27bb45de9acf
                  status:
                    code: 200
                    message: OK
                    description: Success
                    error: 0
                  has_hmo_licence: 'Has not been a Local Authority licensed HMO'
                  description: 'The UPRN is valid. However, there is no record of any current or past licence for that property across the Mandatory, Additional or Selective schemes.'
                properties:
                  api_id:
                    type: string
                    example: 918cf0cc-75ba-4459-a19f-27bb45de9acf
                    description: 'The UUID if the API request.'
                  status:
                    type: object
                    example:
                      code: 200
                      message: OK
                      description: Success
                      error: 0
                    description: 'The response status information.'
                  has_hmo_licence:
                    type: string
                    example: 'Has not been a Local Authority licensed HMO'
                    description: 'The HMO state determination.'
                  description:
                    type: string
                    example: 'The UPRN is valid. However, there is no record of any current or past licence for that property across the Mandatory, Additional or Selective schemes.'
                    description: 'The HMO state determination reason given as human readable prose.'
        403:
          description: 'when there is an invalid or missing api_key'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 918cf195-dc12-42ee-9b70-444ebd2de370
                  status:
                    code: 403
                    message: Forbidden
                    description: 'Missing or invalid API key'
                    error: 110
                properties:
                  api_id:
                    type: string
                    example: 918cf195-dc12-42ee-9b70-444ebd2de370
                    description: 'The UUID if the API request.'
                  status:
                    type: object
                    example:
                      code: 403
                      message: Forbidden
                      description: 'Missing or invalid API key'
                      error: 110
                    description: 'The response status information.'
        422:
          description: 'when the given UPRN is not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 918cf154-a1f9-49cd-8778-b9ea7dd07784
                  status:
                    code: 422
                    message: 'Unprocessable Entity'
                    description: 'The given UPRN was not found.'
                    error: 160
                properties:
                  api_id:
                    type: string
                    example: 918cf154-a1f9-49cd-8778-b9ea7dd07784
                    description: 'The UUID if the API request.'
                  status:
                    type: object
                    example:
                      code: 422
                      message: 'Unprocessable Entity'
                      description: 'The given UPRN was not found.'
                      error: 160
                    description: 'The response status information.'
        500:
          description: 'when there are internal issues with the Kamma SDK'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 4d51b620-59b0-40fe-8bb5-6f80e1ba4269
                  status:
                    code: 500
                    message: 'Internal Error'
                    description: 'An internal error has occurred, this has been logged. If this issue persists please contact Kamma.'
                    error: 140
                properties:
                  api_id:
                    type: string
                    example: 4d51b620-59b0-40fe-8bb5-6f80e1ba4269
                    description: 'The UUID if the API request.'
                  status:
                    type: object
                    example:
                      code: 500
                      message: 'Internal Error'
                      description: 'An internal error has occurred, this has been logged. If this issue persists please contact Kamma.'
                      error: 140
                    description: 'The response status information.'
      tags:
        - 'HMO Checking'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_key:
                  type: string
                  description: 'The API key used to authorise the request. Must be 32 characters.'
                  example: aa22aabaab12bbab212abaa1ba1b112b
                address:
                  type: string
                  description: 'The full address of the property to be checked. Must not be greater than 1000 characters.'
                  example: 'Prime Minister & First Lord of the Treasury, 10 Downing Street, SW1A 2AA'
                postcode:
                  type: string
                  description: 'The postcode of the property to be checked. Must not be greater than 8 characters.'
                  example: 'SW1A 2AA'
                uprn:
                  type: string
                  description: 'The UPRN of the property to be checked. Must not be greater than 12 characters.'
                  example: '100023336956'
              required:
                - api_key
                - address
                - postcode
                - uprn
tags:
  -
    name: 'HMO Checking'
    description: "\nAPI's for checking HMO status' for given property details."
components:
  securitySchemes:
    default: []
security:
  -
    default: []