openapi: 3.0.3
info:
  title: 'Kamma Property Services API'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://property-service.kammadata.com'
paths:
  '/api/v1/properties/{property_id}/update-compliance':
    patch:
      summary: 'Update property compliance.'
      operationId: updatePropertyCompliance
      description: 'This endpoint updates the regulation compliance for a specific property.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01jsycn2e0tt4e95mq263jcj34
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                properties:
                  api_id:
                    type: string
                    example: 01jsycn2e0tt4e95mq263jcj34
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'property not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01jsydtr2djq02n0f5zj19ejy3
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 01jbvtckf6vqaky33n228nw9nr
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This property could not be updated.'
                      has_errors: true
                      error_count: 2
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:property:.'
                          - 'The kamma id format is invalid.'
                properties:
                  api_id:
                    type: string
                    example: 01jsydtr2djq02n0f5zj19ejy3
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 01jbvtckf6vqaky33n228nw9nr
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This property could not be updated.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:property:.'
                                  - 'The kamma id format is invalid.'
                                items:
                                  type: string
      tags:
        - 'Compliance Endpoints'
    parameters:
      -
        in: path
        name: property_id
        description: 'The ULID for the property.'
        example: 'kamma:property:01hb8a2kgtfq35516ygtdnhbax'
        required: true
        schema:
          type: string
  /api/v1/client_preferences:
    get:
      summary: 'Returns the clients preferences.'
      operationId: returnsTheClientsPreferences
      description: 'Return a response of a ClientPreference entity by sso_group_id header.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01j7dq104vx6ekcd3v5pzmcbhm
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    sso_group_id: 139
                    agent_roles:
                      - rentCollection
                    agent_instructions: null
                    property_statuses: null
                    created_at: null
                    updated_at: null
                    deleted_at: null
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This ClientPreference has been shown successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01j7dq104vx6ekcd3v5pzmcbhm
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      sso_group_id:
                        type: integer
                        example: 139
                      agent_roles:
                        type: array
                        example:
                          - rentCollection
                        items:
                          type: string
                      agent_instructions:
                        type: string
                        example: null
                      property_statuses:
                        type: string
                        example: null
                      created_at:
                        type: string
                        example: null
                      updated_at:
                        type: string
                        example: null
                      deleted_at:
                        type: string
                        example: null
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This ClientPreference has been shown successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a non-existent sso group'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no client preferences found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
      tags:
        - Endpoints
  '/api/v1/licences/{licence_id}':
    get:
      summary: 'Return single licence.'
      operationId: returnSingleLicence
      description: 'Return a response of a Licence entity by identifier.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn2q60vzvscwddchw9g3z2j
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    scheme_id: 12345
                    external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                    document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                    application_ref: application-00001
                    status: granted
                    type: mandatory
                    occupants: 5
                    bedrooms: 4
                    households: 3
                    submitted_by: 'Mr John Doe'
                    notes: 'notes on this licence'
                    state: in_breach
                    kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                    kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                    dates:
                      applied: '2020-01-24'
                      start: '2020-01-25'
                      end: '2025-01-25'
                    file: null
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This licence has been shown successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn2q60vzvscwddchw9g3z2j
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      scheme_id:
                        type: integer
                        example: 12345
                      external_ref:
                        type: string
                        example: ext-O2ZMqcouP2sTsJc6gRCBD
                      document_ref:
                        type: string
                        example: doc-00lsbzlnwi3KARBX475EQ6H172
                      application_ref:
                        type: string
                        example: application-00001
                      status:
                        type: string
                        example: granted
                      type:
                        type: string
                        example: mandatory
                      occupants:
                        type: integer
                        example: 5
                      bedrooms:
                        type: integer
                        example: 4
                      households:
                        type: integer
                        example: 3
                      submitted_by:
                        type: string
                        example: 'Mr John Doe'
                      notes:
                        type: string
                        example: 'notes on this licence'
                      state:
                        type: string
                        example: in_breach
                      kamma_id:
                        type: string
                        example: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                      kamma_property_id:
                        type: string
                        example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      dates:
                        type: object
                        properties:
                          applied:
                            type: string
                            example: '2020-01-24'
                          start:
                            type: string
                            example: '2020-01-25'
                          end:
                            type: string
                            example: '2025-01-25'
                      file:
                        type: string
                        example: null
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This licence has been shown successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a licence of a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc053yv5bn8sx1g6rmqh927y
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 'xkamma:licence:01hc052x60mvh7my3e6j8kbs88x'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be shown.'
                      has_errors: true
                      error_count: 2
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:licence:.'
                        licence_id:
                          - 'The licence id field must be a valid ULID.'
                properties:
                  api_id:
                    type: string
                    example: 01hc053yv5bn8sx1g6rmqh927y
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'xkamma:licence:01hc052x60mvh7my3e6j8kbs88x'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be shown.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:licence:.'
                                items:
                                  type: string
                              licence_id:
                                type: array
                                example:
                                  - 'The licence id field must be a valid ULID.'
                                items:
                                  type: string
      tags:
        - 'Licence Endpoints'
    patch:
      summary: 'Update licence.'
      operationId: updateLicence
      description: "This endpoint with update an existing Licence entities with the data provided in the request body.\nThe response being a reflection of the updated entities and their state."
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc05b5bm0mx9pqkyqtg50sen
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    -
                      scheme_id: null
                      external_ref: ext-2
                      document_ref: doc-
                      application_ref: application-00001
                      status: granted
                      type: selective
                      occupants: 2
                      bedrooms: 2
                      households: 2
                      submitted_by: 'Ms Jane Doe'
                      notes: 'notes on this licence have been updated'
                      kamma_id: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                      kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      dates:
                        applied: '2020-01-02'
                        start: '2021-01-02'
                        end: '2021-01-26'
                      file: null
                      data_status:
                        http: 200
                        code: 200
                        message: OK
                        description: 'This licence has been updated successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hc05b5bm0mx9pqkyqtg50sen
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: array
                    example:
                      -
                        scheme_id: null
                        external_ref: ext-2
                        document_ref: doc-
                        application_ref: application-00001
                        status: granted
                        type: selective
                        occupants: 2
                        bedrooms: 2
                        households: 2
                        submitted_by: 'Ms Jane Doe'
                        notes: 'notes on this licence have been updated'
                        kamma_id: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                        kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          applied: '2020-01-02'
                          start: '2021-01-02'
                          end: '2021-01-26'
                        file: null
                        data_status:
                          http: 200
                          code: 200
                          message: OK
                          description: 'This licence has been updated successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                    items:
                      type: object
                      properties:
                        scheme_id:
                          type: string
                          example: null
                        external_ref:
                          type: string
                          example: ext-2
                        document_ref:
                          type: string
                          example: doc-
                        application_ref:
                          type: string
                          example: application-00001
                        status:
                          type: string
                          example: granted
                        type:
                          type: string
                          example: selective
                        occupants:
                          type: integer
                          example: 2
                        bedrooms:
                          type: integer
                          example: 2
                        households:
                          type: integer
                          example: 2
                        submitted_by:
                          type: string
                          example: 'Ms Jane Doe'
                        notes:
                          type: string
                          example: 'notes on this licence have been updated'
                        kamma_id:
                          type: string
                          example: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                        kamma_property_id:
                          type: string
                          example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          type: object
                          properties:
                            applied:
                              type: string
                              example: '2020-01-02'
                            start:
                              type: string
                              example: '2021-01-02'
                            end:
                              type: string
                              example: '2021-01-26'
                        file:
                          type: string
                          example: null
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 200
                            code:
                              type: integer
                              example: 200
                            message:
                              type: string
                              example: OK
                            description:
                              type: string
                              example: 'This licence has been updated successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
        400:
          description: 'malformed request syntax'
          content:
            application/json:
              schema:
                type: object
                example:
                  status:
                    http: 400
                    code: 400
                    message: 'Bad Request'
                    description: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
                properties:
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 400
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Bad Request'
                      description:
                        type: string
                        example: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc05c79vqdjg1amth27yrasc
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    external_ref: ext-2
                    document_ref: doc-
                    application_ref: application-00001
                    type: selective
                    status: granted
                    occupants: 2
                    households: 2
                    bedrooms: 2
                    submitted_by: 'Ms Jane Doe'
                    notes: 'notes on this licence have been updated'
                    dates:
                      applied: '2021-01-05'
                      start: '2021-01-02'
                      end: '2021-01-26'
                    kamma_id: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                    kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be updated.'
                      has_errors: true
                      error_count: 2
                      errors:
                        dates:
                          applied:
                            - 'The dates.applied must be a date before or equal to dates.start.'
                          start:
                            - 'The dates.start must be a date after or equal to dates.applied.'
                properties:
                  api_id:
                    type: string
                    example: 01hc05c79vqdjg1amth27yrasc
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      external_ref:
                        type: string
                        example: ext-2
                      document_ref:
                        type: string
                        example: doc-
                      application_ref:
                        type: string
                        example: application-00001
                      type:
                        type: string
                        example: selective
                      status:
                        type: string
                        example: granted
                      occupants:
                        type: integer
                        example: 2
                      households:
                        type: integer
                        example: 2
                      bedrooms:
                        type: integer
                        example: 2
                      submitted_by:
                        type: string
                        example: 'Ms Jane Doe'
                      notes:
                        type: string
                        example: 'notes on this licence have been updated'
                      dates:
                        type: object
                        properties:
                          applied:
                            type: string
                            example: '2021-01-05'
                          start:
                            type: string
                            example: '2021-01-02'
                          end:
                            type: string
                            example: '2021-01-26'
                      kamma_id:
                        type: string
                        example: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                      kamma_property_id:
                        type: string
                        example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be updated.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              dates:
                                type: object
                                properties:
                                  applied:
                                    type: array
                                    example:
                                      - 'The dates.applied must be a date before or equal to dates.start.'
                                    items:
                                      type: string
                                  start:
                                    type: array
                                    example:
                                      - 'The dates.start must be a date after or equal to dates.applied.'
                                    items:
                                      type: string
      tags:
        - 'Licence Endpoints'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                scheme_id:
                  type: integer
                  description: ''
                  example: 12
                external_ref:
                  type: string
                  description: 'Must be at least 1 character. Must not be greater than 99 characters.'
                  example: asyzwszwtxpeqqi
                document_ref:
                  type: string
                  description: 'Must be at least 1 character. Must not be greater than 99 characters.'
                  example: kymwkiinfowtzmi
                application_ref:
                  type: string
                  description: 'Must be at least 1 character. Must not be greater than 99 characters.'
                  example: xkolowyuffszfrc
                type:
                  type: string
                  description: 'This field is required when <code>status</code> is <code>submitted_to_kamma</code>, <code>requested</code>, <code>rejected</code>, or <code>granted</code>.'
                  example: selective
                  enum:
                    - unknown
                    - mandatory
                    - additional
                    - selective
                    - none
                status:
                  type: string
                  description: ''
                  example: exemption
                  enum:
                    - submitted_to_kamma
                    - requested
                    - granted
                    - rejected
                    - exemption
                occupants:
                  type: integer
                  description: 'Must be at least 1. Must not be greater than 99.'
                  example: 22
                households:
                  type: integer
                  description: 'Must be at least 1. Must not be greater than 99.'
                  example: 22
                bedrooms:
                  type: integer
                  description: 'Must be at least 1. Must not be greater than 99.'
                  example: 23
                submitted_by:
                  type: string
                  description: 'Must be at least 1 character. Must not be greater than 99 characters.'
                  example: vxezhebdrxkpiyp
                notes:
                  type: string
                  description: 'Must not be greater than 2048 characters.'
                  example: muihrdifekzagqz
                dates:
                  type: object
                  description: ''
                  example: []
                  properties:
                    applied:
                      type: string
                      description: 'Must be a valid date in the format <code>Y-m-d</code>.'
                      example: '2023-01-01'
                    start:
                      type: string
                      description: ''
                      example: '2023-01-01'
                    end:
                      type: string
                      description: 'This field is required when <code>status</code> is <code>granted</code>.  Must be a valid date in the format <code>Y-m-d</code>.'
                      example: '2023-09-01'
                property_id:
                  type: string
                  description: 'Must start with one of <code>kamma:property:</code> Must match the regex /^kamma:property:[0-7][0-9A-HJKMNP-TV-Z]{25}$/i.'
                  example: 'kamma:property:7ZVPZVRXK5KMACXEVDAAG6HWRZ$/i'
    delete:
      summary: 'Delete licence.'
      operationId: deleteLicence
      description: 'Remove the specified resource from storage.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc05hwrw250zrvzfp5fvzqw0
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    kamma_id: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This licence has been deleted successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hc05hwrw250zrvzfp5fvzqw0
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This licence has been deleted successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a licence of a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc05gv025xsyjydr9vcgzqm1
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 'kkamma:licence:01hc052x60mvh7my3e6j8kbs88'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be deleted.'
                      has_errors: true
                      error_count: 1
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:licence:.'
                properties:
                  api_id:
                    type: string
                    example: 01hc05gv025xsyjydr9vcgzqm1
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kkamma:licence:01hc052x60mvh7my3e6j8kbs88'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be deleted.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:licence:.'
                                items:
                                  type: string
      tags:
        - 'Licence Endpoints'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cleanup:
                  type: string
                  description: ''
                  example: null
    parameters:
      -
        in: path
        name: licence_id
        description: 'The ULID for the API request.'
        example: 'kamma:licence:01hbtw8t50czq6tfc477kexsmf'
        required: true
        schema:
          type: string
  '/api/v1/licences/{licence_id}/download':
    get:
      summary: 'Download licence file.'
      operationId: downloadLicenceFile
      description: 'This will return the file attached to a licence'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            text/plain:
              schema:
                type: string
                example: 'returns a file'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a licence of a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc22y8rht3vw2hg8evn950mk
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 'xkamma:licence:01hc224sf7rf1jh1r4jy0n2mw0'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be errors.action.download.'
                      has_errors: true
                      error_count: 1
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:licence:.'
                properties:
                  api_id:
                    type: string
                    example: 01hc22y8rht3vw2hg8evn950mk
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'xkamma:licence:01hc224sf7rf1jh1r4jy0n2mw0'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be errors.action.download.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:licence:.'
                                items:
                                  type: string
      tags:
        - 'Licence Endpoints'
    parameters:
      -
        in: path
        name: licence_id
        description: 'The ULID for the API request.'
        example: 'kamma:licence:01hbtw8t50czq6tfc477kexsmf'
        required: true
        schema:
          type: string
  '/api/v1/licences/{licence_id}/upload':
    post:
      summary: 'Upload licence file.'
      operationId: uploadLicenceFile
      description: 'This handles the file upload and links the file to the licence'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc21kmq4qa7y0cpntb6xx53c
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    -
                      kamma-id: 'kamma:file:01HC21KMZTSSB974GFY0HCT0X8'
                      data_status:
                        http: 200
                        code: 200
                        message: OK
                        description: 'This file has been uploaded successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hc21kmq4qa7y0cpntb6xx53c
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: array
                    example:
                      -
                        kamma-id: 'kamma:file:01HC21KMZTSSB974GFY0HCT0X8'
                        data_status:
                          http: 200
                          code: 200
                          message: OK
                          description: 'This file has been uploaded successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                    items:
                      type: object
                      properties:
                        kamma-id:
                          type: string
                          example: 'kamma:file:01HC21KMZTSSB974GFY0HCT0X8'
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 200
                            code:
                              type: integer
                              example: 200
                            message:
                              type: string
                              example: OK
                            description:
                              type: string
                              example: 'This file has been uploaded successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a licence of a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc22y8rht3vw2hg8evn950mk
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 'xkamma:licence:01hc224sf7rf1jh1r4jy0n2mw0'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be errors.action.download.'
                      has_errors: true
                      error_count: 1
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:licence:.'
                properties:
                  api_id:
                    type: string
                    example: 01hc22y8rht3vw2hg8evn950mk
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'xkamma:licence:01hc224sf7rf1jh1r4jy0n2mw0'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be errors.action.download.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:licence:.'
                                items:
                                  type: string
      tags:
        - 'Licence Endpoints'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 'Must be a file. Must not be greater than 2048 kilobytes.'
              required:
                - file
    parameters:
      -
        in: path
        name: licence_id
        description: 'The ULID for the API request.'
        example: 'kamma:licence:01hbtw8t50czq6tfc477kexsmf'
        required: true
        schema:
          type: string
  '/api/v1/licences/{licence_id}/restore':
    put:
      summary: 'Restore deleted licence.'
      operationId: restoreDeletedLicence
      description: 'Restore the specified resource in storage.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc061fdz5k38wrv9mnq1rb5h
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    kamma_id: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This licence has been restored successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hc061fdz5k38wrv9mnq1rb5h
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kamma:licence:01hc052x60mvh7my3e6j8kbs88'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This licence has been restored successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a licence of a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc061yx51xs8w23cx1b0wmer
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 'xkamma:licence:01hc052x60mvh7my3e6j8kbs88'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be restored.'
                      has_errors: true
                      error_count: 1
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:licence:.'
                properties:
                  api_id:
                    type: string
                    example: 01hc061yx51xs8w23cx1b0wmer
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'xkamma:licence:01hc052x60mvh7my3e6j8kbs88'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be restored.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:licence:.'
                                items:
                                  type: string
      tags:
        - 'Licence Endpoints'
    parameters:
      -
        in: path
        name: licence_id
        description: 'The ULID for the API request.'
        example: 'kamma:licence:01hbtw8t50czq6tfc477kexsmf'
        required: true
        schema:
          type: string
  '/api/v1/properties/{property_id}/licences':
    get:
      summary: 'Return multiple licences.'
      operationId: returnMultipleLicences
      description: 'Return all licences belonging to a property'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn2sdv2hgemy4a71d640b7n
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    -
                      scheme_id: null
                      external_ref: ext-1
                      document_ref: doc-00lnd7l3qp4D8CS643QZM8M2HW
                      application_ref: application-00001
                      status: requested
                      type: mandatory
                      occupants: 5
                      bedrooms: 4
                      households: 3
                      submitted_by: 'Mr John Doe'
                      notes: 'notes on this licence'
                      state: null
                      kamma_id: 'kamma:licence:01hc004xr5p8n57bzr4j0f05p5'
                      kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      dates:
                        applied: '2020-01-24'
                        start: null
                        end: null
                      file: null
                      data_status:
                        http: 200
                        code: 200
                        message: OK
                        description: 'This licence has been listed successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                    -
                      scheme_id: 12345
                      external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                      document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                      application_ref: application-00002
                      status: granted
                      type: mandatory
                      occupants: 5
                      bedrooms: 4
                      households: 3
                      submitted_by: 'Mr John Doe'
                      notes: 'notes on this licence'
                      state: in_breach
                      kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                      kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      dates:
                        applied: '2020-01-24'
                        start: '2020-01-25'
                        end: '2025-01-25'
                      file: null
                      data_status:
                        http: 200
                        code: 200
                        message: OK
                        description: 'This licence has been listed successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn2sdv2hgemy4a71d640b7n
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: array
                    example:
                      -
                        scheme_id: null
                        external_ref: ext-1
                        document_ref: doc-00lnd7l3qp4D8CS643QZM8M2HW
                        application_ref: application-00001
                        status: requested
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        state: null
                        kamma_id: 'kamma:licence:01hc004xr5p8n57bzr4j0f05p5'
                        kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          applied: '2020-01-24'
                          start: null
                          end: null
                        file: null
                        data_status:
                          http: 200
                          code: 200
                          message: OK
                          description: 'This licence has been listed successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                      -
                        scheme_id: 12345
                        external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                        document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                        application_ref: application-00002
                        status: granted
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        state: in_breach
                        kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                        kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          applied: '2020-01-24'
                          start: '2020-01-25'
                          end: '2025-01-25'
                        file: null
                        data_status:
                          http: 200
                          code: 200
                          message: OK
                          description: 'This licence has been listed successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                    items:
                      type: object
                      properties:
                        scheme_id:
                          type: string
                          example: null
                        external_ref:
                          type: string
                          example: ext-1
                        document_ref:
                          type: string
                          example: doc-00lnd7l3qp4D8CS643QZM8M2HW
                        application_ref:
                          type: string
                          example: application-00001
                        status:
                          type: string
                          example: requested
                        type:
                          type: string
                          example: mandatory
                        occupants:
                          type: integer
                          example: 5
                        bedrooms:
                          type: integer
                          example: 4
                        households:
                          type: integer
                          example: 3
                        submitted_by:
                          type: string
                          example: 'Mr John Doe'
                        notes:
                          type: string
                          example: 'notes on this licence'
                        state:
                          type: string
                          example: null
                        kamma_id:
                          type: string
                          example: 'kamma:licence:01hc004xr5p8n57bzr4j0f05p5'
                        kamma_property_id:
                          type: string
                          example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          type: object
                          properties:
                            applied:
                              type: string
                              example: '2020-01-24'
                            start:
                              type: string
                              example: null
                            end:
                              type: string
                              example: null
                        file:
                          type: string
                          example: null
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 200
                            code:
                              type: integer
                              example: 200
                            message:
                              type: string
                              example: OK
                            description:
                              type: string
                              example: 'This licence has been listed successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access licences of a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc005nz5hs6avm3q9xcc1j1p
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: null
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This licence could not be listed.'
                      has_errors: true
                      error_count: 2
                      errors:
                        kamma_property_id:
                          - 'The kamma property id must start with one of the following: kamma:property:.'
                        property_id:
                          - 'The property id field must be a valid ULID.'
                properties:
                  api_id:
                    type: string
                    example: 01hc005nz5hs6avm3q9xcc1j1p
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: null
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This licence could not be listed.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              kamma_property_id:
                                type: array
                                example:
                                  - 'The kamma property id must start with one of the following: kamma:property:.'
                                items:
                                  type: string
                              property_id:
                                type: array
                                example:
                                  - 'The property id field must be a valid ULID.'
                                items:
                                  type: string
      tags:
        - 'Licence Endpoints'
    post:
      summary: 'Create licence.'
      operationId: createLicence
      description: "This endpoint with create new Licence entities with the newly created data returned within the request body.\nThe response being a reflection of the saved entities and their state."
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn1sm0zs9983yexp6sv34kz
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    -
                      scheme_id: null
                      external_ref: ext-1
                      document_ref: doc-00lnd7l3qp4D8CS643QZM8M2HW
                      application_ref: application-00001
                      status: requested
                      state: null
                      type: mandatory
                      occupants: 5
                      bedrooms: 4
                      households: 3
                      submitted_by: 'Mr John Doe'
                      notes: 'notes on this licence'
                      kamma_id: 'kamma:licence:01hc004xr5p8n57bzr4j0f05p5'
                      dates:
                        applied: '2020-01-24'
                        start: null
                        end: null
                      file: null
                      data_status:
                        http: 201
                        code: 201
                        message: Created
                        description: 'This licence has been created successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                    -
                      scheme_id: 12345
                      external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                      document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                      application_ref: application-00002
                      status: granted
                      type: mandatory
                      occupants: 5
                      bedrooms: 4
                      households: 3
                      submitted_by: 'Mr John Doe'
                      notes: 'notes on this licence'
                      state: in_breach
                      kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                      kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      dates:
                        applied: null
                        start: '2020-01-25'
                        end: '2025-01-25'
                      file: null
                      data_status:
                        http: 201
                        code: 201
                        message: Created
                        description: 'This licence has been created successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn1sm0zs9983yexp6sv34kz
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: array
                    example:
                      -
                        scheme_id: null
                        external_ref: ext-1
                        document_ref: doc-00lnd7l3qp4D8CS643QZM8M2HW
                        application_ref: application-00001
                        status: requested
                        state: null
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        kamma_id: 'kamma:licence:01hc004xr5p8n57bzr4j0f05p5'
                        dates:
                          applied: '2020-01-24'
                          start: null
                          end: null
                        file: null
                        data_status:
                          http: 201
                          code: 201
                          message: Created
                          description: 'This licence has been created successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                      -
                        scheme_id: 12345
                        external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                        document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                        application_ref: application-00002
                        status: granted
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        state: in_breach
                        kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                        kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          applied: null
                          start: '2020-01-25'
                          end: '2025-01-25'
                        file: null
                        data_status:
                          http: 201
                          code: 201
                          message: Created
                          description: 'This licence has been created successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                    items:
                      type: object
                      properties:
                        scheme_id:
                          type: string
                          example: null
                        external_ref:
                          type: string
                          example: ext-1
                        document_ref:
                          type: string
                          example: doc-00lnd7l3qp4D8CS643QZM8M2HW
                        application_ref:
                          type: string
                          example: application-00001
                        status:
                          type: string
                          example: requested
                        state:
                          type: string
                          example: null
                        type:
                          type: string
                          example: mandatory
                        occupants:
                          type: integer
                          example: 5
                        bedrooms:
                          type: integer
                          example: 4
                        households:
                          type: integer
                          example: 3
                        submitted_by:
                          type: string
                          example: 'Mr John Doe'
                        notes:
                          type: string
                          example: 'notes on this licence'
                        kamma_id:
                          type: string
                          example: 'kamma:licence:01hc004xr5p8n57bzr4j0f05p5'
                        dates:
                          type: object
                          properties:
                            applied:
                              type: string
                              example: '2020-01-24'
                            start:
                              type: string
                              example: null
                            end:
                              type: string
                              example: null
                        file:
                          type: string
                          example: null
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 201
                            code:
                              type: integer
                              example: 201
                            message:
                              type: string
                              example: Created
                            description:
                              type: string
                              example: 'This licence has been created successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
        400:
          description: 'malformed request syntax'
          content:
            application/json:
              schema:
                type: object
                example:
                  status:
                    http: 400
                    code: 400
                    message: 'Bad Request'
                    description: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
                properties:
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 400
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Bad Request'
                      description:
                        type: string
                        example: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hc02kdkxc1g48hjw7s9r8r7y
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    -
                      scheme_id: null
                      external_ref: ext-1
                      document_ref: doc-00lnd949jm3VRJKWWWNQTKKF7A
                      application_ref: application-00001
                      status: requested
                      type: mandatory
                      occupants: 5
                      bedrooms: 4
                      households: 3
                      submitted_by: 'Mr John Doe'
                      notes: 'notes on this licence'
                      kamma_id: 'kamma:licence:01hc02kdnf79aj5yj37p34an85'
                      kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      dates:
                        applied: '2020-01-24'
                        start: null
                        end: null
                      file: null
                      data_status:
                        http: 201
                        code: 201
                        message: Created
                        description: 'This licence has been created successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                    -
                      external_ref: ext-2
                      document_ref: doc-00lnd949jm3VRJKWWWNQTKKF7A
                      application_ref: application-00002
                      type: mandatory
                      status: granted
                      occupants: 5
                      households: 3
                      bedrooms: 4
                      submitted_by: 'Mr John Doe'
                      notes: 'notes on this licence'
                      dates:
                        applied: '2020-01-24'
                        start: '2021-01-25'
                        end: '2021-01-24'
                      kamma_id: null
                      kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      data_status:
                        http: 422
                        code: 422
                        message: 'Unprocessable Content'
                        description: 'This licence could not be created.'
                        has_errors: true
                        error_count: 2
                        errors:
                          dates:
                            start:
                              - 'The dates.start must be a date before dates.end.'
                            end:
                              - 'The dates.end must be a date after dates.start.'
                properties:
                  api_id:
                    type: string
                    example: 01hc02kdkxc1g48hjw7s9r8r7y
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: array
                    example:
                      -
                        scheme_id: null
                        external_ref: ext-1
                        document_ref: doc-00lnd949jm3VRJKWWWNQTKKF7A
                        application_ref: application-00001
                        status: requested
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        kamma_id: 'kamma:licence:01hc02kdnf79aj5yj37p34an85'
                        kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          applied: '2020-01-24'
                          start: null
                          end: null
                        file: null
                        data_status:
                          http: 201
                          code: 201
                          message: Created
                          description: 'This licence has been created successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                      -
                        external_ref: ext-2
                        document_ref: doc-00lnd949jm3VRJKWWWNQTKKF7A
                        application_ref: application-00002
                        type: mandatory
                        status: granted
                        occupants: 5
                        households: 3
                        bedrooms: 4
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        dates:
                          applied: '2020-01-24'
                          start: '2021-01-25'
                          end: '2021-01-24'
                        kamma_id: null
                        kamma_property_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        data_status:
                          http: 422
                          code: 422
                          message: 'Unprocessable Content'
                          description: 'This licence could not be created.'
                          has_errors: true
                          error_count: 2
                          errors:
                            dates:
                              start:
                                - 'The dates.start must be a date before dates.end.'
                              end:
                                - 'The dates.end must be a date after dates.start.'
                    items:
                      type: object
                      properties:
                        scheme_id:
                          type: string
                          example: null
                        external_ref:
                          type: string
                          example: ext-1
                        document_ref:
                          type: string
                          example: doc-00lnd949jm3VRJKWWWNQTKKF7A
                        application_ref:
                          type: string
                          example: application-00001
                        status:
                          type: string
                          example: requested
                        type:
                          type: string
                          example: mandatory
                        occupants:
                          type: integer
                          example: 5
                        bedrooms:
                          type: integer
                          example: 4
                        households:
                          type: integer
                          example: 3
                        submitted_by:
                          type: string
                          example: 'Mr John Doe'
                        notes:
                          type: string
                          example: 'notes on this licence'
                        kamma_id:
                          type: string
                          example: 'kamma:licence:01hc02kdnf79aj5yj37p34an85'
                        kamma_property_id:
                          type: string
                          example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        dates:
                          type: object
                          properties:
                            applied:
                              type: string
                              example: '2020-01-24'
                            start:
                              type: string
                              example: null
                            end:
                              type: string
                              example: null
                        file:
                          type: string
                          example: null
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 201
                            code:
                              type: integer
                              example: 201
                            message:
                              type: string
                              example: Created
                            description:
                              type: string
                              example: 'This licence has been created successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
      tags:
        - 'Licence Endpoints'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: 'multiple licences'
              example:
                -
                  scheme_id: 123
                  external_ref: ext-12345
                  document_ref: doc-12345
                  application_ref: application-12345
                  status: requested
                  type: none
                  occupants: 5
                  households: 2
                  bedrooms: 15
                  submitted_by: 'Joe Smith'
                  notes: 'Needs to be reviewed'
                  dates:
                    applied: '2023-01-01'
                    start: '2023-01-01'
                    end: '2023-09-01'
              items:
                type: object
                properties:
                  scheme_id:
                    type: integer
                    description: "It's for licences of type exemption to specify which scheme we're using for the override"
                    example: 123
                  external_ref:
                    type: string
                    description: 'Your own internal identifier or reference to bind to this Property, which is external to us.'
                    example: ext-12345
                  document_ref:
                    type: string
                    description: "The document's reference for this licence."
                    example: doc-12345
                  application_ref:
                    type: string
                    description: 'The application reference for this licence.'
                    example: application-12345
                  status:
                    type: string
                    description: ''
                    example: requested
                    enum:
                      - submitted_to_kamma
                      - requested
                      - granted
                      - rejected
                      - exemption
                  type:
                    type: string
                    description: ''
                    example: none
                    enum:
                      - unknown
                      - mandatory
                      - additional
                      - selective
                      - none
                  occupants:
                    type: integer
                    description: 'Must be at least 1. Must not be greater than 99.'
                    example: 5
                  households:
                    type: integer
                    description: 'Must be at least 1. Must not be greater than 99.'
                    example: 2
                  bedrooms:
                    type: integer
                    description: 'Must be at least 1. Must not be greater than 99.'
                    example: 15
                  submitted_by:
                    type: string
                    description: 'Must be at least 1 character. Must not be greater than 99 characters.'
                    example: 'Joe Smith'
                  notes:
                    type: string
                    description: 'Must not be greater than 2048 characters.'
                    example: 'Needs to be reviewed'
                  dates:
                    type: object
                    description: ''
                    example:
                      applied: '2023-01-01'
                    properties:
                      applied:
                        type: string
                        description: 'Must be a valid date in the format Y-m-d. Must be a date before or equal to dates.start'
                        example: '2023-01-01'
                      start:
                        type: string
                        description: 'This field is required when status is granted and dates.end is present. Must be a valid date in the format Y-m-d. Must be a date after or equal to dates.applied. Must be a date before dates.end.'
                        example: '2023-01-01'
                      end:
                        type: string
                        description: 'This field is required when status is granted. Must be a valid date in the format Y-m-d. Must be a date after dates.start.'
                        example: '2023-09-01'
                required:
                  - external_ref
    parameters:
      -
        in: path
        name: property_id
        description: 'The ULID for the API request.'
        example: 'kamma:property:01hb8a2kgtfq35516ygtdnhbax'
        required: true
        schema:
          type: string
  /api/v1/managers:
    get:
      summary: 'Returns all managers.'
      operationId: returnsAllManagers
      description: 'Return all managers belonging to an sso group id.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01kbd5krqez19yn6z32kpfdqar
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    -
                      id: 01kbczzkdqf2ap6bhkn31f05tp
                      code: LEID
                    -
                      id: 01kbd01q10q6xfh0wnx0c9kkpq
                      code: DLA
                    -
                      id: 01kbd09pmvn3f0jt8s81kcbhd5
                      code: TSE
                properties:
                  api_id:
                    type: string
                    example: 01kbd5krqez19yn6z32kpfdqar
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: array
                    example:
                      -
                        id: 01kbczzkdqf2ap6bhkn31f05tp
                        code: LEID
                      -
                        id: 01kbd01q10q6xfh0wnx0c9kkpq
                        code: DLA
                      -
                        id: 01kbd09pmvn3f0jt8s81kcbhd5
                        code: TSE
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 01kbczzkdqf2ap6bhkn31f05tp
                        code:
                          type: string
                          example: LEID
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a non-existent sso group'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
      tags:
        - 'Manager Endpoints'
  /api/v1/properties:
    get:
      summary: 'All properties.'
      operationId: allProperties
      description: 'Returns all properties belondong to an sso group id. Can be filtered.'
      parameters:
        -
          in: query
          name: 'filter[address]'
          description: 'Optional. Filter by address or postcode. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. If value matches a UK postcode, it will filter by postcode (spaces ignored); otherwise, it will filter by address_customer.'
          example: null
          required: false
          schema:
            type: array
            description: 'Optional. Filter by address or postcode. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. If value matches a UK postcode, it will filter by postcode (spaces ignored); otherwise, it will filter by address_customer.'
            example: null
            items:
              type: string
        -
          in: query
          name: 'filter[action_text][]'
          description: 'Optional. Filter by action text. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. To do multiple OR logic, use | to separate the values.'
          example: null
          required: false
          schema:
            type: array
            description: 'Optional. Filter by action text. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. To do multiple OR logic, use | to separate the values.'
            example: null
            items:
              type: string
        -
          in: query
          name: 'filter[authority_code]'
          description: 'Optional. Filter by authority code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example: 'filter[authority_code]=EQUAL:ons:gss:E12345678'
          required: false
          schema:
            type: string
            description: 'Optional. Filter by authority code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example: 'filter[authority_code]=EQUAL:ons:gss:E12345678'
        -
          in: query
          name: 'filter[scheme_type][]'
          description: 'Optional. Filter by scheme type. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example: null
          required: false
          schema:
            type: array
            description: 'Optional. Filter by scheme type. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example: null
            items:
              type: string
        -
          in: query
          name: 'filter[future_scheme_type][]'
          description: 'Optional. Filter by future scheme type. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example: null
          required: false
          schema:
            type: array
            description: 'Optional. Filter by future scheme type. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example: null
            items:
              type: string
        -
          in: query
          name: 'filter[compliance_status][]'
          description: 'Optional. Filter by compliance status. Use format OPERATOR:value, where OPERATOR is EQUAL.'
          example: null
          required: false
          schema:
            type: array
            description: 'Optional. Filter by compliance status. Use format OPERATOR:value, where OPERATOR is EQUAL.'
            example: null
            items:
              type: string
        -
          in: query
          name: 'filter[property_manager]'
          description: 'Optional. Filter by manager code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. Use NULL as value to filter for properties without manager codes.'
          example: 'filter[property_manager]=EQUAL:MGR001 or filter[property_manager]=EQUAL:NULL'
          required: false
          schema:
            type: string
            description: 'Optional. Filter by manager code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. Use NULL as value to filter for properties without manager codes.'
            example: 'filter[property_manager]=EQUAL:MGR001 or filter[property_manager]=EQUAL:NULL'
        -
          in: query
          name: exclude_associated
          description: ''
          example: null
          required: false
          schema:
            type: string
            description: ''
            example: null
        -
          in: query
          name: cursor
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter
          description: ''
          example: []
          required: false
          schema:
            type: object
            description: ''
            example: []
            properties: {  }
        -
          in: query
          name: filter.id
          description: 'Must start with one of <code>kamma:property:</code>.'
          example: 'kamma:property:pasy'
          required: false
          schema:
            type: string
            description: 'Must start with one of <code>kamma:property:</code>.'
            example: 'kamma:property:pasy'
        -
          in: query
          name: filter.has_future_scheme
          description: ''
          example: false
          required: false
          schema:
            type: boolean
            description: ''
            example: false
        -
          in: query
          name: filter.action_text
          description: ''
          example: null
          required: false
          schema:
            type: object
            description: ''
            example: null
            properties: {  }
        -
          in: query
          name: filter.future_scheme
          description: ''
          example:
            - REQUIRED
          required: true
          schema:
            type: array
            description: ''
            example:
              - REQUIRED
            items:
              type: string
        -
          in: query
          name: filter.address
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.compliance_status
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.authority_code
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.scheme_type
          description: ''
          example: null
          required: false
          schema:
            type: object
            description: ''
            example: null
            properties: {  }
        -
          in: query
          name: filter.future_scheme_type
          description: ''
          example: null
          required: false
          schema:
            type: object
            description: ''
            example: null
            properties: {  }
        -
          in: query
          name: filter.external_id
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.property_manager
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn2ebhat0g8q2qenvdhr1k7
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  meta:
                    per_page: 15
                    current_page: 1
                    total: 1
                  links:
                    first: 'https://property-service.kammadata.com/api/v1/properties?page=1'
                    last: 'https://property-service.kammadata.com/api/v1/properties?page=1'
                    prev: null
                    next: null
                  data:
                    -
                      kamma_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      external_id: 3GayVId2IEHGz1nQazRD7
                      friendly_name: "The Prime Minister's house"
                      notes: 'A very nice house'
                      addressing:
                        address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                        postcode: 'SW1A 2AA'
                        uprn: 100023336956
                        lat: 51.503541
                        lon: -0.12767
                        authority: Westminster
                        country_name: England
                      details:
                        occupants: 5
                        households: 3
                        bedrooms: 3
                        storeys:
                          internal: 2
                          external: 1
                        is_above_commercial: true
                        rent: null
                        valuation: null
                      classification:
                        category: s254
                        class: flat
                      plannings: []
                      compliancy:
                        compliant: false
                        action_texts:
                          -
                            key: licence_upload
                            description: 'Upload a valid licence.'
                            action: 'Review licence'
                          -
                            key: licence_households
                            description: 'Please verify the number of households for the granted licence.'
                            action: 'Review licence'
                      dates:
                        created: '2024-02-27 10:25:38'
                        updated: '2024-02-27 10:32:26'
                      regulations:
                        -
                          type: mandatory
                        -
                          type: additional
                      scheme:
                        type: selective
                        required: MAYBE
                        override:
                          type: none
                          reason: 'Property Is Less Than 10 Years Old'
                          created: '2024-12-20'
                      article4: null
                      data_status:
                        http: 200
                        code: 200
                        message: OK
                        description: 'This property has been listed successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn2ebhat0g8q2qenvdhr1k7
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  meta:
                    type: object
                    properties:
                      per_page:
                        type: integer
                        example: 15
                      current_page:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: 'https://property-service.kammadata.com/api/v1/properties?page=1'
                      last:
                        type: string
                        example: 'https://property-service.kammadata.com/api/v1/properties?page=1'
                      prev:
                        type: string
                        example: null
                      next:
                        type: string
                        example: null
                  data:
                    type: array
                    example:
                      -
                        kamma_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        external_id: 3GayVId2IEHGz1nQazRD7
                        friendly_name: "The Prime Minister's house"
                        notes: 'A very nice house'
                        addressing:
                          address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                          postcode: 'SW1A 2AA'
                          uprn: 100023336956
                          lat: 51.503541
                          lon: -0.12767
                          authority: Westminster
                          country_name: England
                        details:
                          occupants: 5
                          households: 3
                          bedrooms: 3
                          storeys:
                            internal: 2
                            external: 1
                          is_above_commercial: true
                          rent: null
                          valuation: null
                        classification:
                          category: s254
                          class: flat
                        plannings: []
                        compliancy:
                          compliant: false
                          action_texts:
                            -
                              key: licence_upload
                              description: 'Upload a valid licence.'
                              action: 'Review licence'
                            -
                              key: licence_households
                              description: 'Please verify the number of households for the granted licence.'
                              action: 'Review licence'
                        dates:
                          created: '2024-02-27 10:25:38'
                          updated: '2024-02-27 10:32:26'
                        regulations:
                          -
                            type: mandatory
                          -
                            type: additional
                        scheme:
                          type: selective
                          required: MAYBE
                          override:
                            type: none
                            reason: 'Property Is Less Than 10 Years Old'
                            created: '2024-12-20'
                        article4: null
                        data_status:
                          http: 200
                          code: 200
                          message: OK
                          description: 'This property has been listed successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                    items:
                      type: object
                      properties:
                        kamma_id:
                          type: string
                          example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        external_id:
                          type: string
                          example: 3GayVId2IEHGz1nQazRD7
                        friendly_name:
                          type: string
                          example: "The Prime Minister's house"
                        notes:
                          type: string
                          example: 'A very nice house'
                        addressing:
                          type: object
                          properties:
                            address:
                              type: string
                              example: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                            postcode:
                              type: string
                              example: 'SW1A 2AA'
                            uprn:
                              type: integer
                              example: 100023336956
                            lat:
                              type: number
                              example: 51.503541
                            lon:
                              type: number
                              example: -0.12767
                            authority:
                              type: string
                              example: Westminster
                            country_name:
                              type: string
                              example: England
                        details:
                          type: object
                          properties:
                            occupants:
                              type: integer
                              example: 5
                            households:
                              type: integer
                              example: 3
                            bedrooms:
                              type: integer
                              example: 3
                            storeys:
                              type: object
                              properties:
                                internal:
                                  type: integer
                                  example: 2
                                external:
                                  type: integer
                                  example: 1
                            is_above_commercial:
                              type: boolean
                              example: true
                            rent:
                              type: string
                              example: null
                            valuation:
                              type: string
                              example: null
                        classification:
                          type: object
                          properties:
                            category:
                              type: string
                              example: s254
                            class:
                              type: string
                              example: flat
                        plannings:
                          type: array
                          example: []
                        compliancy:
                          type: object
                          properties:
                            compliant:
                              type: boolean
                              example: false
                            action_texts:
                              type: array
                              example:
                                -
                                  key: licence_upload
                                  description: 'Upload a valid licence.'
                                  action: 'Review licence'
                                -
                                  key: licence_households
                                  description: 'Please verify the number of households for the granted licence.'
                                  action: 'Review licence'
                              items:
                                type: object
                                properties:
                                  key:
                                    type: string
                                    example: licence_upload
                                  description:
                                    type: string
                                    example: 'Upload a valid licence.'
                                  action:
                                    type: string
                                    example: 'Review licence'
                        dates:
                          type: object
                          properties:
                            created:
                              type: string
                              example: '2024-02-27 10:25:38'
                            updated:
                              type: string
                              example: '2024-02-27 10:32:26'
                        regulations:
                          type: array
                          example:
                            -
                              type: mandatory
                            -
                              type: additional
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                example: mandatory
                        scheme:
                          type: object
                          properties:
                            type:
                              type: string
                              example: selective
                            required:
                              type: string
                              example: MAYBE
                            override:
                              type: object
                              properties:
                                type:
                                  type: string
                                  example: none
                                reason:
                                  type: string
                                  example: 'Property Is Less Than 10 Years Old'
                                created:
                                  type: string
                                  example: '2024-12-20'
                        article4:
                          type: string
                          example: null
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 200
                            code:
                              type: integer
                              example: 200
                            message:
                              type: string
                              example: OK
                            description:
                              type: string
                              example: 'This property has been listed successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
        403:
          description: 'when trying to access a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The sso group id field is required. (and 2 more errors)'
                  errors:
                    sso_group_id:
                      - 'The sso group id field is required.'
                    external_id:
                      - 'The external id must be a string.'
                      - 'The external id must be at least 1 characters.'
                properties:
                  message:
                    type: string
                    example: 'The sso group id field is required. (and 2 more errors)'
                  errors:
                    type: object
                    properties:
                      sso_group_id:
                        type: array
                        example:
                          - 'The sso group id field is required.'
                        items:
                          type: string
                      external_id:
                        type: array
                        example:
                          - 'The external id must be a string.'
                          - 'The external id must be at least 1 characters.'
                        items:
                          type: string
      tags:
        - 'Property Endpoints'
    post:
      summary: 'Create property.'
      operationId: createProperty
      description: "This endpoint with create new property entities with the data provided as array in the request body.\nThe response being a reflection of the saved entities and their state."
      parameters:
        -
          in: query
          name: exclude_associated
          description: "Temporary flag that can be removed once we use APIv3 in Reapit. If true, licences, compliancy, etc. don't get returned and the regulations and compliance data get stored asynchronously."
          example: false
          required: false
          schema:
            type: boolean
            description: "Temporary flag that can be removed once we use APIv3 in Reapit. If true, licences, compliancy, etc. don't get returned and the regulations and compliance data get stored asynchronously."
            example: false
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn1je2g2v3pm9p1c5gjyrye
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    -
                      kamma_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      external_id: 3GayVId2IEHGz1nQazRD7
                      friendly_name: "The Prime Minister's house"
                      notes: 'A very nice house'
                      addressing:
                        address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                        postcode: 'SW1A 2AA'
                        uprn: 100023336956
                        lat: 51.503541
                        lon: -0.12767
                      details:
                        occupants: 5
                        households: 5
                        bedrooms: 15
                        storeys:
                          internal: 2
                          external: 1
                        is_above_commercial: true
                        rent: 1250
                        valuation: 5600000
                      classification:
                        category: s254
                        class: flat
                      plannings: []
                      agency:
                        office_ids:
                          - OXF
                          - SOL
                        kamma_id: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                        roles: []
                        instructions:
                          - letting
                        statuses:
                          - toLet
                        dates:
                          created: null
                          updated: null
                      compliancy:
                        compliant: false
                        action_texts:
                          -
                            key: missing_licence
                            description: 'Add a valid licence.'
                            action: 'Review licence'
                      dates:
                        created: '2024-02-27 10:25:38'
                        updated: '2024-02-27 10:25:38'
                      licences: []
                      data_status:
                        http: 201
                        code: 201
                        message: Created
                        description: 'This property has been created successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn1je2g2v3pm9p1c5gjyrye
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: array
                    example:
                      -
                        kamma_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        external_id: 3GayVId2IEHGz1nQazRD7
                        friendly_name: "The Prime Minister's house"
                        notes: 'A very nice house'
                        addressing:
                          address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                          postcode: 'SW1A 2AA'
                          uprn: 100023336956
                          lat: 51.503541
                          lon: -0.12767
                        details:
                          occupants: 5
                          households: 5
                          bedrooms: 15
                          storeys:
                            internal: 2
                            external: 1
                          is_above_commercial: true
                          rent: 1250
                          valuation: 5600000
                        classification:
                          category: s254
                          class: flat
                        plannings: []
                        agency:
                          office_ids:
                            - OXF
                            - SOL
                          kamma_id: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                          roles: []
                          instructions:
                            - letting
                          statuses:
                            - toLet
                          dates:
                            created: null
                            updated: null
                        compliancy:
                          compliant: false
                          action_texts:
                            -
                              key: missing_licence
                              description: 'Add a valid licence.'
                              action: 'Review licence'
                        dates:
                          created: '2024-02-27 10:25:38'
                          updated: '2024-02-27 10:25:38'
                        licences: []
                        data_status:
                          http: 201
                          code: 201
                          message: Created
                          description: 'This property has been created successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                    items:
                      type: object
                      properties:
                        kamma_id:
                          type: string
                          example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                        external_id:
                          type: string
                          example: 3GayVId2IEHGz1nQazRD7
                        friendly_name:
                          type: string
                          example: "The Prime Minister's house"
                        notes:
                          type: string
                          example: 'A very nice house'
                        addressing:
                          type: object
                          properties:
                            address:
                              type: string
                              example: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                            postcode:
                              type: string
                              example: 'SW1A 2AA'
                            uprn:
                              type: integer
                              example: 100023336956
                            lat:
                              type: number
                              example: 51.503541
                            lon:
                              type: number
                              example: -0.12767
                        details:
                          type: object
                          properties:
                            occupants:
                              type: integer
                              example: 5
                            households:
                              type: integer
                              example: 5
                            bedrooms:
                              type: integer
                              example: 15
                            storeys:
                              type: object
                              properties:
                                internal:
                                  type: integer
                                  example: 2
                                external:
                                  type: integer
                                  example: 1
                            is_above_commercial:
                              type: boolean
                              example: true
                            rent:
                              type: integer
                              example: 1250
                            valuation:
                              type: integer
                              example: 5600000
                        classification:
                          type: object
                          properties:
                            category:
                              type: string
                              example: s254
                            class:
                              type: string
                              example: flat
                        plannings:
                          type: array
                          example: []
                        agency:
                          type: object
                          properties:
                            office_ids:
                              type: array
                              example:
                                - OXF
                                - SOL
                              items:
                                type: string
                            kamma_id:
                              type: string
                              example: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                            roles:
                              type: array
                              example: []
                            instructions:
                              type: array
                              example:
                                - letting
                              items:
                                type: string
                            statuses:
                              type: array
                              example:
                                - toLet
                              items:
                                type: string
                            dates:
                              type: object
                              properties:
                                created:
                                  type: string
                                  example: null
                                updated:
                                  type: string
                                  example: null
                        compliancy:
                          type: object
                          properties:
                            compliant:
                              type: boolean
                              example: false
                            action_texts:
                              type: array
                              example:
                                -
                                  key: missing_licence
                                  description: 'Add a valid licence.'
                                  action: 'Review licence'
                              items:
                                type: object
                                properties:
                                  key:
                                    type: string
                                    example: missing_licence
                                  description:
                                    type: string
                                    example: 'Add a valid licence.'
                                  action:
                                    type: string
                                    example: 'Review licence'
                        dates:
                          type: object
                          properties:
                            created:
                              type: string
                              example: '2024-02-27 10:25:38'
                            updated:
                              type: string
                              example: '2024-02-27 10:25:38'
                        licences:
                          type: array
                          example: []
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 201
                            code:
                              type: integer
                              example: 201
                            message:
                              type: string
                              example: Created
                            description:
                              type: string
                              example: 'This property has been created successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
        400:
          description: 'malformed request syntax'
          content:
            application/json:
              schema:
                type: object
                example:
                  status:
                    http: 400
                    code: 400
                    message: 'Bad Request'
                    description: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
                properties:
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 400
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Bad Request'
                      description:
                        type: string
                        example: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1rk76vy27k5eyydphtcvd
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    -
                      external_id: 00lnbknv0dCBA32RKM9019E966
                      friendly_name: floofy
                      notes: 'These are my notes!'
                      kamma_id: 'kamma:property:01hbx1rkgt1jdc7c0rek06g7n1'
                      addressing:
                        address: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                        postcode: 'SW1A 2AA'
                        uprn: 19
                      details:
                        occupants: 5
                        households: 4
                        bedrooms: 3
                        storeys:
                          internal: 12
                          external: 14
                        is_above_commercial: true
                        rent: 360000
                        valuation: 5600000
                      classification:
                        category: single
                        class: flat
                      dates:
                        created: '2020-01-24'
                        updated: '2021-01-25'
                      data_status:
                        http: 201
                        code: 201
                        message: Created
                        description: 'This property has been created successfully.'
                        has_errors: false
                        error_count: 0
                        errors: []
                    -
                      external_id: 00lnbknv0dCBA32RKM9019E966
                      friendly_name: floofy
                      notes: 'These are my notes!'
                      address:
                        uprn: '19'
                        address: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                        postcode: 'SW1A 2AA'
                      details:
                        occupants: 5
                        bedrooms: 3
                        households: 4
                        storeys:
                          internal: 12
                          external: 14
                        is_above_commercial: true
                        rent: 360000
                        valuation: 5600000
                        s257: true
                      classification:
                        category: single
                        class: flat
                      licence:
                        external_ref: ext-00lnbknv0dCBA32RKM9019E966
                        document_ref: ref-00lnbknv0dCBA32RKM9019E966
                        application_ref: application-00001
                        type: mandatory
                        status: requested
                        occupants: 5
                        households: 3
                        bedrooms: 4
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        dates:
                          applied: '2020-01-24'
                          start: '2020-01-25'
                          end: '2025-01-25'
                      planning:
                        status: inprogress
                        reference: ref-12345
                      sso_group_id: 1
                      kamma_id: null
                      data_status:
                        http: 422
                        code: 422
                        message: 'Unprocessable Content'
                        description: 'This property could not be created.'
                        has_errors: true
                        error_count: 3
                        errors:
                          external_id:
                            - 'The external id must be unique within the specified SSO group or property.'
                          addressing:
                            address:
                              - 'The addressing.address field is required.'
                            postcode:
                              - 'The addressing.postcode field is required.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1rk76vy27k5eyydphtcvd
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: array
                    example:
                      -
                        external_id: 00lnbknv0dCBA32RKM9019E966
                        friendly_name: floofy
                        notes: 'These are my notes!'
                        kamma_id: 'kamma:property:01hbx1rkgt1jdc7c0rek06g7n1'
                        addressing:
                          address: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                          postcode: 'SW1A 2AA'
                          uprn: 19
                        details:
                          occupants: 5
                          households: 4
                          bedrooms: 3
                          storeys:
                            internal: 12
                            external: 14
                          is_above_commercial: true
                          rent: 360000
                          valuation: 5600000
                        classification:
                          category: single
                          class: flat
                        dates:
                          created: '2020-01-24'
                          updated: '2021-01-25'
                        data_status:
                          http: 201
                          code: 201
                          message: Created
                          description: 'This property has been created successfully.'
                          has_errors: false
                          error_count: 0
                          errors: []
                      -
                        external_id: 00lnbknv0dCBA32RKM9019E966
                        friendly_name: floofy
                        notes: 'These are my notes!'
                        address:
                          uprn: '19'
                          address: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                          postcode: 'SW1A 2AA'
                        details:
                          occupants: 5
                          bedrooms: 3
                          households: 4
                          storeys:
                            internal: 12
                            external: 14
                          is_above_commercial: true
                          rent: 360000
                          valuation: 5600000
                          s257: true
                        classification:
                          category: single
                          class: flat
                        licence:
                          external_ref: ext-00lnbknv0dCBA32RKM9019E966
                          document_ref: ref-00lnbknv0dCBA32RKM9019E966
                          application_ref: application-00001
                          type: mandatory
                          status: requested
                          occupants: 5
                          households: 3
                          bedrooms: 4
                          submitted_by: 'Mr John Doe'
                          notes: 'notes on this licence'
                          dates:
                            applied: '2020-01-24'
                            start: '2020-01-25'
                            end: '2025-01-25'
                        planning:
                          status: inprogress
                          reference: ref-12345
                        sso_group_id: 1
                        kamma_id: null
                        data_status:
                          http: 422
                          code: 422
                          message: 'Unprocessable Content'
                          description: 'This property could not be created.'
                          has_errors: true
                          error_count: 3
                          errors:
                            external_id:
                              - 'The external id must be unique within the specified SSO group or property.'
                            addressing:
                              address:
                                - 'The addressing.address field is required.'
                              postcode:
                                - 'The addressing.postcode field is required.'
                    items:
                      type: object
                      properties:
                        external_id:
                          type: string
                          example: 00lnbknv0dCBA32RKM9019E966
                        friendly_name:
                          type: string
                          example: floofy
                        notes:
                          type: string
                          example: 'These are my notes!'
                        kamma_id:
                          type: string
                          example: 'kamma:property:01hbx1rkgt1jdc7c0rek06g7n1'
                        addressing:
                          type: object
                          properties:
                            address:
                              type: string
                              example: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                            postcode:
                              type: string
                              example: 'SW1A 2AA'
                            uprn:
                              type: integer
                              example: 19
                        details:
                          type: object
                          properties:
                            occupants:
                              type: integer
                              example: 5
                            households:
                              type: integer
                              example: 4
                            bedrooms:
                              type: integer
                              example: 3
                            storeys:
                              type: object
                              properties:
                                internal:
                                  type: integer
                                  example: 12
                                external:
                                  type: integer
                                  example: 14
                            is_above_commercial:
                              type: boolean
                              example: true
                            rent:
                              type: integer
                              example: 360000
                            valuation:
                              type: integer
                              example: 5600000
                        classification:
                          type: object
                          properties:
                            category:
                              type: string
                              example: single
                            class:
                              type: string
                              example: flat
                        dates:
                          type: object
                          properties:
                            created:
                              type: string
                              example: '2020-01-24'
                            updated:
                              type: string
                              example: '2021-01-25'
                        data_status:
                          type: object
                          properties:
                            http:
                              type: integer
                              example: 201
                            code:
                              type: integer
                              example: 201
                            message:
                              type: string
                              example: Created
                            description:
                              type: string
                              example: 'This property has been created successfully.'
                            has_errors:
                              type: boolean
                              example: false
                            error_count:
                              type: integer
                              example: 0
                            errors:
                              type: array
                              example: []
      tags:
        - 'Property Endpoints'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: 'multiple properties'
              example:
                -
                  external_id: ext-12345
                  notes: 'A very nice house'
                  friendly_name: "The Prime Minister's house"
                  addressing:
                    uprn: '100023336956'
                    address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                    postcode: 'SW1A 2AA'
                    lat: 51.503541
                    lon: -0.12767
                    distance_to_refdata: 10.0
                  details:
                    occupants: 5
                    bedrooms: 15
                    households: 5
                    rent: 360000
                    valuation: 10000000
                    value: 12000000
                    storeys:
                      internal: 2
                      external: 1
                    is_above_commercial: true
                  classification:
                    category: s254
                    class: flat
                  agency:
                    roles:
                      - culpa
                    instructions:
                      - culpa
                    statuses:
                      - culpa
                    office_ids:
                      - culpa
                  extra:
                    custom_field: value
                    another_field: 123
              items:
                type: object
                properties:
                  external_id:
                    type: string
                    description: 'Your own unique internal identifier or reference to bind to this property, which is external to us.'
                    example: ext-12345
                  notes:
                    type: string
                    description: 'Any other notes that you wish to be stored for the property. Must not be greater than 2048 characters.'
                    example: 'A very nice house'
                  friendly_name:
                    type: string
                    description: 'A consumer defined name to give context to this property.'
                    example: "The Prime Minister's house"
                  addressing:
                    type: object
                    description: ''
                    example: []
                    properties:
                      uprn:
                        type: string
                        description: 'Must be between 1 and 12 digits.'
                        example: '100023336956'
                      address:
                        type: string
                        description: ''
                        example: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                      postcode:
                        type: string
                        description: ''
                        example: 'SW1A 2AA'
                      lat:
                        type: number
                        description: Latitude
                        example: 51.503541
                      lon:
                        type: number
                        description: Longitude
                        example: -0.12767
                      distance_to_refdata:
                        type: number
                        description: 'Distance to refdata in meters.'
                        example: 10.0
                  details:
                    type: object
                    description: ''
                    example:
                      occupants: 5
                    properties:
                      occupants:
                        type: integer
                        description: 'Must be at least 0. Must not be greater than 99.'
                        example: 5
                      bedrooms:
                        type: integer
                        description: 'Must be at least 0. Must not be greater than 99.'
                        example: 15
                      households:
                        type: integer
                        description: 'Must be at least 0. Must not be greater than 99.'
                        example: 5
                      rent:
                        type: integer
                        description: 'Amount of rent paid. Weekly. In pence'
                        example: 360000
                      valuation:
                        type: integer
                        description: 'The valuation for this property. In pence.'
                        example: 10000000
                      value:
                        type: integer
                        description: 'How much was paid for this property. In pence.'
                        example: 12000000
                      storeys:
                        type: object
                        description: ''
                        example:
                          internal: 2
                        properties:
                          internal:
                            type: integer
                            description: 'Must be at least 0. Must not be greater than 99.'
                            example: 2
                          external:
                            type: integer
                            description: 'Must be at least 0. Must not be greater than 99.'
                            example: 1
                      is_above_commercial:
                        type: boolean
                        description: ''
                        example: true
                  classification:
                    type: object
                    description: ''
                    example:
                      category: s254
                    properties:
                      category:
                        type: string
                        description: ''
                        example: s254
                        enum:
                          - single
                          - s254
                          - s257
                          - licensable
                      class:
                        type: string
                        description: ''
                        example: flat
                        enum:
                          - other
                          - house
                          - flat
                  agency:
                    type: object
                    description: ''
                    example:
                      roles:
                        - culpa
                    properties:
                      roles:
                        type: array
                        description: ''
                        example:
                          - culpa
                        items:
                          type: string
                      instructions:
                        type: array
                        description: ''
                        example:
                          - culpa
                        items:
                          type: string
                      statuses:
                        type: array
                        description: ''
                        example:
                          - culpa
                        items:
                          type: string
                      office_ids:
                        type: array
                        description: ''
                        example:
                          - culpa
                        items:
                          type: string
                  extra:
                    type: object
                    description: 'Additional custom data as JSON object.'
                    example:
                      custom_field: value
                      another_field: 123
                    properties: {  }
                required:
                  - external_id
                  - addressing
  '/api/v1/properties/{property_id}':
    get:
      summary: 'Returns a property.'
      operationId: returnsAProperty
      description: 'Return a response of a Property entity by $identifier.'
      parameters:
        -
          in: query
          name: exclude_associated
          description: "Temporary flag that can be removed once we use APIv3 in Reapit. If true, licences, compliancy, etc. don't get returned and the regulations and compliance data get stored asynchronously."
          example: false
          required: false
          schema:
            type: boolean
            description: "Temporary flag that can be removed once we use APIv3 in Reapit. If true, licences, compliancy, etc. don't get returned and the regulations and compliance data get stored asynchronously."
            example: false
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn1yxbtg47hyagxc9nateza
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    kamma_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                    external_id: 3GayVId2IEHGz1nQazRD7
                    friendly_name: "The Prime Minister's house"
                    notes: 'A very nice house'
                    addressing:
                      address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                      postcode: 'SW1A 2AA'
                      uprn: 100023336956
                      lat: 51.503541
                      lon: -0.12767
                    details:
                      occupants: 5
                      households: 2
                      bedrooms: 3
                      storeys:
                        internal: 2
                        external: 1
                      is_above_commercial: true
                      rent: 1250
                      valuation: 5600000
                    classification:
                      category: s254
                      class: flat
                    plannings: []
                    agency:
                      office_ids:
                        - OXF
                        - SOL
                      kamma_id: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                      roles: []
                      instructions:
                        - letting
                      statuses:
                        - toLet
                      dates:
                        created: null
                        updated: null
                    compliancy:
                      compliant: false
                      action_texts:
                        -
                          key: licence_upload
                          description: 'Upload a valid licence.'
                          action: 'Review licence'
                        -
                          key: licence_households
                          description: 'Please verify the number of households for the granted licence.'
                          action: 'Review licence'
                    dates:
                      created: '2024-02-27 10:25:38'
                      updated: '2024-02-27 10:32:26'
                    licences:
                      -
                        scheme_id: 12345
                        external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                        document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                        application_ref: application-00001
                        status: granted
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        state: in_breach
                        kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                        dates:
                          applied: null
                          start: '2020-01-25'
                          end: '2025-01-25'
                        file: null
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This property has been shown successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn1yxbtg47hyagxc9nateza
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      external_id:
                        type: string
                        example: 3GayVId2IEHGz1nQazRD7
                      friendly_name:
                        type: string
                        example: "The Prime Minister's house"
                      notes:
                        type: string
                        example: 'A very nice house'
                      addressing:
                        type: object
                        properties:
                          address:
                            type: string
                            example: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                          postcode:
                            type: string
                            example: 'SW1A 2AA'
                          uprn:
                            type: integer
                            example: 100023336956
                          lat:
                            type: number
                            example: 51.503541
                          lon:
                            type: number
                            example: -0.12767
                      details:
                        type: object
                        properties:
                          occupants:
                            type: integer
                            example: 5
                          households:
                            type: integer
                            example: 2
                          bedrooms:
                            type: integer
                            example: 3
                          storeys:
                            type: object
                            properties:
                              internal:
                                type: integer
                                example: 2
                              external:
                                type: integer
                                example: 1
                          is_above_commercial:
                            type: boolean
                            example: true
                          rent:
                            type: integer
                            example: 1250
                          valuation:
                            type: integer
                            example: 5600000
                      classification:
                        type: object
                        properties:
                          category:
                            type: string
                            example: s254
                          class:
                            type: string
                            example: flat
                      plannings:
                        type: array
                        example: []
                      agency:
                        type: object
                        properties:
                          office_ids:
                            type: array
                            example:
                              - OXF
                              - SOL
                            items:
                              type: string
                          kamma_id:
                            type: string
                            example: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                          roles:
                            type: array
                            example: []
                          instructions:
                            type: array
                            example:
                              - letting
                            items:
                              type: string
                          statuses:
                            type: array
                            example:
                              - toLet
                            items:
                              type: string
                          dates:
                            type: object
                            properties:
                              created:
                                type: string
                                example: null
                              updated:
                                type: string
                                example: null
                      compliancy:
                        type: object
                        properties:
                          compliant:
                            type: boolean
                            example: false
                          action_texts:
                            type: array
                            example:
                              -
                                key: licence_upload
                                description: 'Upload a valid licence.'
                                action: 'Review licence'
                              -
                                key: licence_households
                                description: 'Please verify the number of households for the granted licence.'
                                action: 'Review licence'
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  example: licence_upload
                                description:
                                  type: string
                                  example: 'Upload a valid licence.'
                                action:
                                  type: string
                                  example: 'Review licence'
                      dates:
                        type: object
                        properties:
                          created:
                            type: string
                            example: '2024-02-27 10:25:38'
                          updated:
                            type: string
                            example: '2024-02-27 10:32:26'
                      licences:
                        type: array
                        example:
                          -
                            scheme_id: 12345
                            external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                            document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                            application_ref: application-00001
                            status: granted
                            type: mandatory
                            occupants: 5
                            bedrooms: 4
                            households: 3
                            submitted_by: 'Mr John Doe'
                            notes: 'notes on this licence'
                            state: in_breach
                            kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                            dates:
                              applied: null
                              start: '2020-01-25'
                              end: '2025-01-25'
                            file: null
                        items:
                          type: object
                          properties:
                            scheme_id:
                              type: integer
                              example: 12345
                            external_ref:
                              type: string
                              example: ext-O2ZMqcouP2sTsJc6gRCBD
                            document_ref:
                              type: string
                              example: doc-00lsbzlnwi3KARBX475EQ6H172
                            application_ref:
                              type: string
                              example: application-00001
                            status:
                              type: string
                              example: granted
                            type:
                              type: string
                              example: mandatory
                            occupants:
                              type: integer
                              example: 5
                            bedrooms:
                              type: integer
                              example: 4
                            households:
                              type: integer
                              example: 3
                            submitted_by:
                              type: string
                              example: 'Mr John Doe'
                            notes:
                              type: string
                              example: 'notes on this licence'
                            state:
                              type: string
                              example: in_breach
                            kamma_id:
                              type: string
                              example: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                            dates:
                              type: object
                              properties:
                                applied:
                                  type: string
                                  example: null
                                start:
                                  type: string
                                  example: '2020-01-25'
                                end:
                                  type: string
                                  example: '2025-01-25'
                            file:
                              type: string
                              example: null
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This property has been shown successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a property belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no property found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqwg13kpbbfsgj35e7csaj4
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 01hb8a2kgtfq35516ygtdnhbaxx
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This property could not be shown.'
                      has_errors: true
                      error_count: 1
                      errors:
                        kamma_id:
                          - 'The kamma id format is invalid.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqwg13kpbbfsgj35e7csaj4
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 01hb8a2kgtfq35516ygtdnhbaxx
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This property could not be shown.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id format is invalid.'
                                items:
                                  type: string
      tags:
        - 'Property Endpoints'
    patch:
      summary: 'Update property.'
      operationId: updateProperty
      description: "This endpoint will update an existing property entities with the data provided in the request body.\nThe response being a reflection of the updated entities and their state."
      parameters:
        -
          in: query
          name: exclude_associated
          description: "Temporary flag that can be removed once we use APIv3 in Reapit. If true, licences, compliancy, etc. don't get returned and the regulations and compliance data get stored asynchronously."
          example: false
          required: false
          schema:
            type: boolean
            description: "Temporary flag that can be removed once we use APIv3 in Reapit. If true, licences, compliancy, etc. don't get returned and the regulations and compliance data get stored asynchronously."
            example: false
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hqn2kk85qk0f3f7fdc00g66r
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    kamma_id: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                    external_id: O2ZMqcouP2sTsJc6gRCBD
                    friendly_name: "The Prime Minister's house"
                    notes: 'A very nice house'
                    addressing:
                      address: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                      postcode: 'SW1A 2AA'
                      uprn: 100023336956
                      lat: 51.503541
                      lon: -0.12767
                    details:
                      occupants: 5
                      households: 4
                      bedrooms: 3
                      storeys:
                        internal: 1
                        external: 2
                      is_above_commercial: true
                      rent: 360000
                      valuation: 10000000
                    classification:
                      category: s254
                      class: flat
                    plannings: []
                    agency:
                      office_ids:
                        - OXF
                        - SOL
                      kamma_id: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                      roles: []
                      instructions:
                        - letting
                      statuses:
                        - toLet
                      dates:
                        created: null
                        updated: null
                    compliancy:
                      compliant: false
                      action_texts:
                        -
                          key: licence_upload
                          description: 'Upload a valid licence.'
                          action: 'Review licence'
                        -
                          key: licence_occupants
                          description: 'Please verify the number of occupants for the granted licence.'
                          action: 'Review licence'
                        -
                          key: licence_households
                          description: 'Please verify the number of households for the granted licence.'
                          action: 'Review licence'
                    dates:
                      created: '2024-02-27 10:25:38'
                      updated: '2024-02-27 10:43:44'
                    licences:
                      -
                        scheme_id: 12345
                        external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                        document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                        application_ref: application-00001
                        status: granted
                        type: mandatory
                        occupants: 5
                        bedrooms: 4
                        households: 3
                        submitted_by: 'Mr John Doe'
                        notes: 'notes on this licence'
                        state: in_breach
                        kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                        dates:
                          applied: null
                          start: '2020-01-25'
                          end: '2025-01-25'
                        file: null
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This property has been updated successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hqn2kk85qk0f3f7fdc00g66r
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kamma:property:01hqn1jeag1kvhe3tgr4jba0fe'
                      external_id:
                        type: string
                        example: O2ZMqcouP2sTsJc6gRCBD
                      friendly_name:
                        type: string
                        example: "The Prime Minister's house"
                      notes:
                        type: string
                        example: 'A very nice house'
                      addressing:
                        type: object
                        properties:
                          address:
                            type: string
                            example: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                          postcode:
                            type: string
                            example: 'SW1A 2AA'
                          uprn:
                            type: integer
                            example: 100023336956
                          lat:
                            type: number
                            example: 51.503541
                          lon:
                            type: number
                            example: -0.12767
                      details:
                        type: object
                        properties:
                          occupants:
                            type: integer
                            example: 5
                          households:
                            type: integer
                            example: 4
                          bedrooms:
                            type: integer
                            example: 3
                          storeys:
                            type: object
                            properties:
                              internal:
                                type: integer
                                example: 1
                              external:
                                type: integer
                                example: 2
                          is_above_commercial:
                            type: boolean
                            example: true
                          rent:
                            type: integer
                            example: 360000
                          valuation:
                            type: integer
                            example: 10000000
                      classification:
                        type: object
                        properties:
                          category:
                            type: string
                            example: s254
                          class:
                            type: string
                            example: flat
                      plannings:
                        type: array
                        example: []
                      agency:
                        type: object
                        properties:
                          office_ids:
                            type: array
                            example:
                              - OXF
                              - SOL
                            items:
                              type: string
                          kamma_id:
                            type: string
                            example: 'kamma:agency:01j1a7rt72ftmgj3at8mcy35yx'
                          roles:
                            type: array
                            example: []
                          instructions:
                            type: array
                            example:
                              - letting
                            items:
                              type: string
                          statuses:
                            type: array
                            example:
                              - toLet
                            items:
                              type: string
                          dates:
                            type: object
                            properties:
                              created:
                                type: string
                                example: null
                              updated:
                                type: string
                                example: null
                      compliancy:
                        type: object
                        properties:
                          compliant:
                            type: boolean
                            example: false
                          action_texts:
                            type: array
                            example:
                              -
                                key: licence_upload
                                description: 'Upload a valid licence.'
                                action: 'Review licence'
                              -
                                key: licence_occupants
                                description: 'Please verify the number of occupants for the granted licence.'
                                action: 'Review licence'
                              -
                                key: licence_households
                                description: 'Please verify the number of households for the granted licence.'
                                action: 'Review licence'
                            items:
                              type: object
                              properties:
                                key:
                                  type: string
                                  example: licence_upload
                                description:
                                  type: string
                                  example: 'Upload a valid licence.'
                                action:
                                  type: string
                                  example: 'Review licence'
                      dates:
                        type: object
                        properties:
                          created:
                            type: string
                            example: '2024-02-27 10:25:38'
                          updated:
                            type: string
                            example: '2024-02-27 10:43:44'
                      licences:
                        type: array
                        example:
                          -
                            scheme_id: 12345
                            external_ref: ext-O2ZMqcouP2sTsJc6gRCBD
                            document_ref: doc-00lsbzlnwi3KARBX475EQ6H172
                            application_ref: application-00001
                            status: granted
                            type: mandatory
                            occupants: 5
                            bedrooms: 4
                            households: 3
                            submitted_by: 'Mr John Doe'
                            notes: 'notes on this licence'
                            state: in_breach
                            kamma_id: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                            dates:
                              applied: null
                              start: '2020-01-25'
                              end: '2025-01-25'
                            file: null
                        items:
                          type: object
                          properties:
                            scheme_id:
                              type: integer
                              example: 12345
                            external_ref:
                              type: string
                              example: ext-O2ZMqcouP2sTsJc6gRCBD
                            document_ref:
                              type: string
                              example: doc-00lsbzlnwi3KARBX475EQ6H172
                            application_ref:
                              type: string
                              example: application-00001
                            status:
                              type: string
                              example: granted
                            type:
                              type: string
                              example: mandatory
                            occupants:
                              type: integer
                              example: 5
                            bedrooms:
                              type: integer
                              example: 4
                            households:
                              type: integer
                              example: 3
                            submitted_by:
                              type: string
                              example: 'Mr John Doe'
                            notes:
                              type: string
                              example: 'notes on this licence'
                            state:
                              type: string
                              example: in_breach
                            kamma_id:
                              type: string
                              example: 'kamma:licence:01hqn1sm2h0fvttywqyrq1943z'
                            dates:
                              type: object
                              properties:
                                applied:
                                  type: string
                                  example: null
                                start:
                                  type: string
                                  example: '2020-01-25'
                                end:
                                  type: string
                                  example: '2025-01-25'
                            file:
                              type: string
                              example: null
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This property has been updated successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        400:
          description: 'malformed request syntax'
          content:
            application/json:
              schema:
                type: object
                example:
                  status:
                    http: 400
                    code: 400
                    message: 'Bad Request'
                    description: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
                properties:
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 400
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Bad Request'
                      description:
                        type: string
                        example: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbxfzqqnz6h3ewj3hvxqcpx7
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    friendly_name: floofy
                    notes: 'These are my notes!'
                    addressing:
                      uprn: '1'
                      address: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                      postcode: 'SW1A 2Az'
                    details:
                      occupants: test
                      bedrooms: 1
                      households: 1
                      storeys:
                        internal: 1
                        external: 1
                      is_above_commercial: true
                      rent: 10000
                      valuation: 100000
                    classification:
                      category: single
                      class: flat
                    property_id: 01hbxdxmr0d1hw4427wwe93dzx
                    kamma_id: 'kamma:property:01hbxdxmr0d1hw4427wwe93dzx'
                    sso_group_id: 1
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This property could not be updated.'
                      has_errors: true
                      error_count: 1
                      errors:
                        details:
                          occupants:
                            - 'The details.occupants must be an integer.'
                properties:
                  api_id:
                    type: string
                    example: 01hbxfzqqnz6h3ewj3hvxqcpx7
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      friendly_name:
                        type: string
                        example: floofy
                      notes:
                        type: string
                        example: 'These are my notes!'
                      addressing:
                        type: object
                        properties:
                          uprn:
                            type: string
                            example: '1'
                          address:
                            type: string
                            example: 'Prime Minister & First Lord Of The Treasury, 10 Downing Street, London'
                          postcode:
                            type: string
                            example: 'SW1A 2Az'
                      details:
                        type: object
                        properties:
                          occupants:
                            type: string
                            example: test
                          bedrooms:
                            type: integer
                            example: 1
                          households:
                            type: integer
                            example: 1
                          storeys:
                            type: object
                            properties:
                              internal:
                                type: integer
                                example: 1
                              external:
                                type: integer
                                example: 1
                          is_above_commercial:
                            type: boolean
                            example: true
                          rent:
                            type: integer
                            example: 10000
                          valuation:
                            type: integer
                            example: 100000
                      classification:
                        type: object
                        properties:
                          category:
                            type: string
                            example: single
                          class:
                            type: string
                            example: flat
                      property_id:
                        type: string
                        example: 01hbxdxmr0d1hw4427wwe93dzx
                      kamma_id:
                        type: string
                        example: 'kamma:property:01hbxdxmr0d1hw4427wwe93dzx'
                      sso_group_id:
                        type: integer
                        example: 1
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This property could not be updated.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              details:
                                type: object
                                properties:
                                  occupants:
                                    type: array
                                    example:
                                      - 'The details.occupants must be an integer.'
                                    items:
                                      type: string
      tags:
        - 'Property Endpoints'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                external_id:
                  type: string
                  description: 'Your own internal identifier or reference to bind to this property, which is external to us.'
                  example: ext-12345
                notes:
                  type: string
                  description: 'Any other notes that you wish to be stored for the property. Must not be greater than 2048 characters.'
                  example: 'A very nice house'
                friendly_name:
                  type: string
                  description: 'A consumer defined name to give context to this property.'
                  example: "The Prime Minister's house"
                addressing:
                  type: object
                  description: ''
                  example: []
                  properties:
                    uprn:
                      type: string
                      description: 'Must be between 1 and 12 digits.'
                      example: '100023336956'
                    address:
                      type: string
                      description: ''
                      example: 'Prime Minister, 10 Downing Street, London, SW1A 2AA'
                    postcode:
                      type: string
                      description: ''
                      example: 'SW1A 2AA'
                    lat:
                      type: number
                      description: Latitude
                      example: 51.503541
                    lon:
                      type: number
                      description: Longitude
                      example: -0.12767
                details:
                  type: object
                  description: ''
                  example: []
                  properties:
                    occupants:
                      type: integer
                      description: 'Must be at least 0. Must not be greater than 99.'
                      example: 9
                    bedrooms:
                      type: integer
                      description: 'Must be at least 0. Must not be greater than 99.'
                      example: 10
                    households:
                      type: integer
                      description: 'Must be at least 0. Must not be greater than 99.'
                      example: 24
                    rent:
                      type: integer
                      description: 'Amount of rent paid. Weekly. In pence'
                      example: 360000
                    valuation:
                      type: integer
                      description: 'The valuation for this property. In pence.'
                      example: 10000000
                    storeys:
                      type: object
                      description: ''
                      example: []
                      properties:
                        internal:
                          type: integer
                          description: 'Must be at least 0. Must not be greater than 99.'
                          example: 11
                        external:
                          type: integer
                          description: 'Must be at least 0. Must not be greater than 99.'
                          example: 8
                    is_above_commercial:
                      type: boolean
                      description: ''
                      example: true
                    value:
                      type: integer
                      description: 'How much was paid for this property. In pence.'
                      example: 12000000
                classification:
                  type: object
                  description: ''
                  example: []
                  properties:
                    category:
                      type: string
                      description: ''
                      example: pbsa
                      enum:
                        - single
                        - s254
                        - s257
                        - licensable
                        - pbsa
                        - btr
                    class:
                      type: string
                      description: ''
                      example: null
                agency:
                  type: object
                  description: ''
                  example: []
                  properties:
                    roles:
                      type: array
                      description: ''
                      example:
                        - culpa
                      items:
                        type: string
                    instructions:
                      type: array
                      description: ''
                      example:
                        - culpa
                      items:
                        type: string
                    statuses:
                      type: array
                      description: ''
                      example:
                        - culpa
                      items:
                        type: string
                    office_ids:
                      type: array
                      description: ''
                      example:
                        - culpa
                      items:
                        type: string
                    property_manager:
                      type: string
                      description: 'Must not be greater than 255 characters.'
                      example: fowtzmixkolowyu
                    dates:
                      type: object
                      description: ''
                      example: []
                      properties:
                        created:
                          type: string
                          description: 'Must be a valid date in the format <code>Y-m-d H:i:s</code>. Must be a date before or equal to <code>agency.dates.updated</code>.'
                          example: '2013-04-20'
                        updated:
                          type: string
                          description: 'Must be a valid date in the format <code>Y-m-d H:i:s</code>. Must be a date after or equal to <code>agency.dates.created</code>.'
                          example: '2083-11-11'
                extra:
                  type: object
                  description: 'Additional custom data as JSON object.'
                  example:
                    custom_field: value
                    another_field: 123
                  properties: {  }
    delete:
      summary: 'Delete Property.'
      operationId: deleteProperty
      description: 'Remove the specified resource from storage.'
      parameters:
        -
          in: query
          name: cleanup
          description: 'If true, the property will be deleted and all associated data will be removed.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'If true, the property will be deleted and all associated data will be removed.'
            example: true
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01jtnnsx2ayf18dkmz412zj094
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    kamma_id: 'kamma:property:01hb8a2kgtfq35516ygtdnhbax'
                    licences:
                      -
                        id: 'kamma:licence:01hb8a2kgtfq35516ygtdnhbax'
                        file:
                          id: 'kamma:file:01hb8a2kgtfq35516ygtdnhbax'
                    permissions: []
                    tenancies: []
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This property has been deleted successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01jtnnsx2ayf18dkmz412zj094
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kamma:property:01hb8a2kgtfq35516ygtdnhbax'
                      licences:
                        type: array
                        example:
                          -
                            id: 'kamma:licence:01hb8a2kgtfq35516ygtdnhbax'
                            file:
                              id: 'kamma:file:01hb8a2kgtfq35516ygtdnhbax'
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: 'kamma:licence:01hb8a2kgtfq35516ygtdnhbax'
                            file:
                              type: object
                              properties:
                                id:
                                  type: string
                                  example: 'kamma:file:01hb8a2kgtfq35516ygtdnhbax'
                      permissions:
                        type: array
                        example: []
                      tenancies:
                        type: array
                        example: []
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This property has been deleted successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        400:
          description: 'malformed request syntax'
          content:
            application/json:
              schema:
                type: object
                example:
                  status:
                    http: 400
                    code: 400
                    message: 'Bad Request'
                    description: 'Cannot delete property as there are associated objects linked to it'
                properties:
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 400
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Bad Request'
                      description:
                        type: string
                        example: 'Cannot delete property as there are associated objects linked to it'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbxh510khdmg19xccxzc5zgs
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 'xkamma:property:asdasdassdas'
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This property could not be deleted.'
                      has_errors: true
                      error_count: 2
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:property:.'
                          - 'The kamma id format is invalid.'
                properties:
                  api_id:
                    type: string
                    example: 01hbxh510khdmg19xccxzc5zgs
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'xkamma:property:asdasdassdas'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This property could not be deleted.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:property:.'
                                  - 'The kamma id format is invalid.'
                                items:
                                  type: string
      tags:
        - 'Property Endpoints'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                cleanup:
                  type: string
                  description: ''
                  example: null
    parameters:
      -
        in: path
        name: property_id
        description: 'The ULID for the API request.'
        example: 'kamma:property:01hb8a2kgtfq35516ygtdnhbax'
        required: true
        schema:
          type: string
  '/api/v1/properties/restore/{property_id}':
    put:
      summary: 'Restore Property.'
      operationId: restoreProperty
      description: 'Restore the specified resource in storage.'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbxjacb3se7fhcz6rff7grza
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    kamma_id: 'kamma:property:01hbxja5971yf4cpr0mwdpbnhd'
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This property has been restored successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hbxjacb3se7fhcz6rff7grza
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 'kamma:property:01hbxja5971yf4cpr0mwdpbnhd'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This property has been restored successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        400:
          description: 'malformed request syntax'
          content:
            application/json:
              schema:
                type: object
                example:
                  status:
                    http: 400
                    code: 400
                    message: 'Bad Request'
                    description: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
                properties:
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 400
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Bad Request'
                      description:
                        type: string
                        example: 'The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).'
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbxjbz4gyrx94qvxzdq3jrh1
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    kamma_id: 01hbxja5971yf4cpr0mwdpbnhd
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This property could not be restored.'
                      has_errors: true
                      error_count: 2
                      errors:
                        kamma_id:
                          - 'The kamma id must start with one of the following: kamma:property:.'
                          - 'The kamma id format is invalid.'
                properties:
                  api_id:
                    type: string
                    example: 01hbxjbz4gyrx94qvxzdq3jrh1
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      kamma_id:
                        type: string
                        example: 01hbxja5971yf4cpr0mwdpbnhd
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This property could not be restored.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              kamma_id:
                                type: array
                                example:
                                  - 'The kamma id must start with one of the following: kamma:property:.'
                                  - 'The kamma id format is invalid.'
                                items:
                                  type: string
      tags:
        - 'Property Endpoints'
    parameters:
      -
        in: path
        name: property_id
        description: 'The ULID for the API request.'
        example: 'kamma:property:01hb8a2kgtfq35516ygtdnhbax'
        required: true
        schema:
          type: string
  /api/v1/properties/export:
    get:
      summary: 'Export properties.'
      operationId: exportProperties
      description: 'Returns all properties belonging to an sso group id as a CSV file. Supports the same filters as the index endpoint.'
      parameters:
        -
          in: query
          name: 'filter[address]'
          description: 'Optional. Filter by address or postcode. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example:
            - culpa
          required: false
          schema:
            type: array
            description: 'Optional. Filter by address or postcode. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example:
              - culpa
            items:
              type: string
        -
          in: query
          name: 'filter[action_text][]'
          description: 'Optional. Filter by action text. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example:
            - culpa
          required: false
          schema:
            type: array
            description: 'Optional. Filter by action text. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example:
              - culpa
            items:
              type: string
        -
          in: query
          name: 'filter[authority_code]'
          description: 'Optional. Filter by authority code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example: culpa
          required: false
          schema:
            type: string
            description: 'Optional. Filter by authority code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example: culpa
        -
          in: query
          name: 'filter[scheme_type][]'
          description: 'Optional. Filter by scheme type. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
          example:
            - culpa
          required: false
          schema:
            type: array
            description: 'Optional. Filter by scheme type. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL.'
            example:
              - culpa
            items:
              type: string
        -
          in: query
          name: 'filter[compliance_status][]'
          description: 'Optional. Filter by compliance status. Use format OPERATOR:value, where OPERATOR is EQUAL.'
          example:
            - culpa
          required: false
          schema:
            type: array
            description: 'Optional. Filter by compliance status. Use format OPERATOR:value, where OPERATOR is EQUAL.'
            example:
              - culpa
            items:
              type: string
        -
          in: query
          name: 'filter[property_manager]'
          description: 'Optional. Filter by manager code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. Use NULL as value to filter for properties without manager codes.'
          example: 'filter[property_manager]=EQUAL:MGR001 or filter[property_manager]=EQUAL:NULL'
          required: false
          schema:
            type: string
            description: 'Optional. Filter by manager code. Use format OPERATOR:value, where OPERATOR is EQUAL or NOT_EQUAL. Use NULL as value to filter for properties without manager codes.'
            example: 'filter[property_manager]=EQUAL:MGR001 or filter[property_manager]=EQUAL:NULL'
        -
          in: query
          name: exclude_associated
          description: ''
          example: null
          required: false
          schema:
            type: string
            description: ''
            example: null
        -
          in: query
          name: cursor
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter
          description: ''
          example: []
          required: false
          schema:
            type: object
            description: ''
            example: []
            properties: {  }
        -
          in: query
          name: filter.id
          description: 'Must start with one of <code>kamma:property:</code>.'
          example: 'kamma:property:pasy'
          required: false
          schema:
            type: string
            description: 'Must start with one of <code>kamma:property:</code>.'
            example: 'kamma:property:pasy'
        -
          in: query
          name: filter.has_future_scheme
          description: ''
          example: false
          required: false
          schema:
            type: boolean
            description: ''
            example: false
        -
          in: query
          name: filter.action_text
          description: ''
          example: null
          required: false
          schema:
            type: object
            description: ''
            example: null
            properties: {  }
        -
          in: query
          name: filter.future_scheme
          description: ''
          example:
            - REQUIRED
          required: true
          schema:
            type: array
            description: ''
            example:
              - REQUIRED
            items:
              type: string
        -
          in: query
          name: filter.address
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.compliance_status
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.authority_code
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.scheme_type
          description: ''
          example: null
          required: false
          schema:
            type: object
            description: ''
            example: null
            properties: {  }
        -
          in: query
          name: filter.future_scheme_type
          description: ''
          example: null
          required: false
          schema:
            type: object
            description: ''
            example: null
            properties: {  }
        -
          in: query
          name: filter.external_id
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: query
          name: filter.property_manager
          description: ''
          example: culpa
          required: false
          schema:
            type: string
            description: ''
            example: culpa
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        202:
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  job_id: d6ed0850-ab66-4339-b9fd-ad9998540d6a
                  status: pending
                  status_url: /api/v1/properties/export/d6ed0850-ab66-4339-b9fd-ad9998540d6a/status
                properties:
                  job_id:
                    type: string
                    example: d6ed0850-ab66-4339-b9fd-ad9998540d6a
                  status:
                    type: string
                    example: pending
                  status_url:
                    type: string
                    example: /api/v1/properties/export/d6ed0850-ab66-4339-b9fd-ad9998540d6a/status
        403:
          description: 'when trying to access properties belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no properties found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The sso group id field is required. (and 2 more errors)'
                  errors:
                    sso_group_id:
                      - 'The sso group id field is required.'
                    external_id:
                      - 'The external id must be a string.'
                      - 'The external id must be at least 1 characters.'
                properties:
                  message:
                    type: string
                    example: 'The sso group id field is required. (and 2 more errors)'
                  errors:
                    type: object
                    properties:
                      sso_group_id:
                        type: array
                        example:
                          - 'The sso group id field is required.'
                        items:
                          type: string
                      external_id:
                        type: array
                        example:
                          - 'The external id must be a string.'
                          - 'The external id must be at least 1 characters.'
                        items:
                          type: string
      tags:
        - 'Property Export'
  '/api/v1/properties/export/{jobId}/status':
    get:
      summary: 'Check export job status.'
      operationId: checkExportJobStatus
      description: ''
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: 'job completed'
          content:
            application/json:
              schema:
                type: object
                example:
                  job_id: 550e8400-e29b-41d4-a716-446655440000
                  status: completed
                  processed: 1500
                  total: 1500
                  download_url: /api/v1/properties/export/550e8400-e29b-41d4-a716-446655440000/download
                properties:
                  job_id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
                  status:
                    type: string
                    example: completed
                  processed:
                    type: integer
                    example: 1500
                  total:
                    type: integer
                    example: 1500
                  download_url:
                    type: string
                    example: /api/v1/properties/export/550e8400-e29b-41d4-a716-446655440000/download
        404:
          description: 'job not found'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Export job not found'
                properties:
                  message:
                    type: string
                    example: 'Export job not found'
      tags:
        - 'Property Export'
    parameters:
      -
        in: path
        name: jobId
        description: 'The job ID returned from the export request.'
        example: 550e8400-e29b-41d4-a716-446655440000
        required: true
        schema:
          type: string
  '/api/v1/properties/export/{jobId}/download':
    get:
      summary: 'Download completed export.'
      operationId: downloadCompletedExport
      description: ''
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: success
          content:
            text/plain:
              schema:
                type: string
                example: "\"reference id\",address,postcode,lat,lon,authority,country,people,households,bedrooms,\"current licencing requirements\",\"future licencing requirements\",\"licence required\",\"start date\",\"end date\",\"action required\",\"licence type\",\"licence status\",\"compliance status\",\"property created\",\"property updated\"\nBGL250306,\"Flat C, 18 Denbigh Street, London, SW1V 2ER\",\"SW1V 2ER\",51.491579,-0.139493,Westminster,England,1,0,1,\"mandatory, additional (consultation), additional\",selective,unknown,,,\"Add occupancy information.\",,,\"not compliant\",\"2025-09-09 08:13:47\",\"2025-10-23 16:24:05\""
        404:
          description: 'job not found or not completed'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Export not found or not ready'
                properties:
                  message:
                    type: string
                    example: 'Export not found or not ready'
      tags:
        - 'Property Export'
    parameters:
      -
        in: path
        name: jobId
        description: 'The job ID returned from the export request.'
        example: 550e8400-e29b-41d4-a716-446655440000
        required: true
        schema:
          type: string
  /api/v1/spotchecks:
    get:
      summary: 'Get spotchecks.'
      operationId: getSpotchecks
      description: 'Retrieves spotchecks for retrieval later'
      parameters:
        -
          in: query
          name: cursor
          description: 'Used to navigate to a specific position in the result set. Generated by the API in links.next and links.prev.'
          example: eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
          required: false
          schema:
            type: string
            description: 'Used to navigate to a specific position in the result set. Generated by the API in links.next and links.prev.'
            example: eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
        -
          in: query
          name: page
          description: 'The page number for offset pagination. Cannot be used with cursor.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'The page number for offset pagination. Cannot be used with cursor.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of items per page. Defaults to 10.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of items per page. Defaults to 10.'
            example: 20
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01k42x62xpyks3vzc81mngznm9
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  meta:
                    per_page: 10
                    path: 'https://property-service.kamma.localhost/api/v1/spotchecks'
                    total: 1
                  links:
                    before: null
                    after: null
                  data:
                    -
                      address: '10, Charles Street, OX4 3AS'
                      postcode: 'OX4 3AS'
                      uprn: null
                      category: null
                      class: null
                      is_above_commercial: false
                      storeys: null
                      households: 1
                      occupants: 1
                      determination_date: null
                      spot_check_response:
                        id: '1'
                        links:
                          -
                            rel: self
                            href: 'https://apiv3.kamma.localhost/v3/determinations/check'
                        status:
                          code: 200
                          message: OK
                        schemes:
                          -
                            link: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                            type: mandatory
                            date_end: null
                            required: not_required
                            occupants: 5
                            scheme_id: 'kamma:scheme:418'
                            date_start: '2006-04-01'
                            households: 2
                            is_advised: false
                            consultation: false
                            required_future: not_applicable
                          -
                            link: 'https://www.oxford.gov.uk/houses-multiple-occupation-hmos/hmo-licensing-2021-public-notice'
                            type: additional
                            date_end: '2026-06-09'
                            required: not_required
                            occupants: 3
                            scheme_id: 'kamma:scheme:730'
                            date_start: '2021-06-10'
                            households: 2
                            is_advised: false
                            consultation: false
                            required_future: not_applicable
                          -
                            link: 'https://www.oxford.gov.uk/info/20010/housing/1520/selective_licensing/2'
                            type: selective
                            date_end: '2027-08-31'
                            required: required
                            occupants: 1
                            scheme_id: 'kamma:scheme:808'
                            date_start: '2022-09-01'
                            households: 1
                            is_advised: true
                            consultation: false
                            required_future: not_applicable
                        planning:
                          -
                            link: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                            type: article4
                            date_end: null
                            required: not_required
                            date_start: '2012-02-25'
                            is_advised: false
                            planning_id: 'kamma:planning:78'
                            consultation: false
                            required_future: not_applicable
                        advice_text:
                          scheme:
                            future: 'There is currently no confirmed scheme with a future start date affecting this property.'
                            current: 'Selective licence is required.'
                            mandatory: 'A Mandatory licensing scheme covers the whole of Oxford. This scheme is permanent and includes all HMOs with at least 5 people since October 1st 2018.'
                            selective: 'A Selective licensing scheme covers the whole of Oxford. This scheme ends on August 31st 2027 and includes all rented properties no matter how many people live there.'
                            additional: 'An Additional licensing scheme covers the whole of Oxford. This scheme ends on June 9th 2026 and includes all types of HMOs with at least 3 people on 1 storey.'
                          planning:
                            future: ''
                            current: ''
                            article4: 'An Article 4 direction covers the whole of Oxford. This direction began on February 25th 2012 requiring planning permission development rights when converting land and buildings from a C3 class to a C4 class.'
                        saved_status: null
                      kamma_id: 'kamma:check:01k42tjap7m2t18cpd2m4krwk6'
                properties:
                  api_id:
                    type: string
                    example: 01k42x62xpyks3vzc81mngznm9
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  meta:
                    type: object
                    properties:
                      per_page:
                        type: integer
                        example: 10
                      path:
                        type: string
                        example: 'https://property-service.kamma.localhost/api/v1/spotchecks'
                      total:
                        type: integer
                        example: 1
                  links:
                    type: object
                    properties:
                      before:
                        type: string
                        example: null
                      after:
                        type: string
                        example: null
                  data:
                    type: array
                    example:
                      -
                        address: '10, Charles Street, OX4 3AS'
                        postcode: 'OX4 3AS'
                        uprn: null
                        category: null
                        class: null
                        is_above_commercial: false
                        storeys: null
                        households: 1
                        occupants: 1
                        determination_date: null
                        spot_check_response:
                          id: '1'
                          links:
                            -
                              rel: self
                              href: 'https://apiv3.kamma.localhost/v3/determinations/check'
                          status:
                            code: 200
                            message: OK
                          schemes:
                            -
                              link: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                              type: mandatory
                              date_end: null
                              required: not_required
                              occupants: 5
                              scheme_id: 'kamma:scheme:418'
                              date_start: '2006-04-01'
                              households: 2
                              is_advised: false
                              consultation: false
                              required_future: not_applicable
                            -
                              link: 'https://www.oxford.gov.uk/houses-multiple-occupation-hmos/hmo-licensing-2021-public-notice'
                              type: additional
                              date_end: '2026-06-09'
                              required: not_required
                              occupants: 3
                              scheme_id: 'kamma:scheme:730'
                              date_start: '2021-06-10'
                              households: 2
                              is_advised: false
                              consultation: false
                              required_future: not_applicable
                            -
                              link: 'https://www.oxford.gov.uk/info/20010/housing/1520/selective_licensing/2'
                              type: selective
                              date_end: '2027-08-31'
                              required: required
                              occupants: 1
                              scheme_id: 'kamma:scheme:808'
                              date_start: '2022-09-01'
                              households: 1
                              is_advised: true
                              consultation: false
                              required_future: not_applicable
                          planning:
                            -
                              link: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                              type: article4
                              date_end: null
                              required: not_required
                              date_start: '2012-02-25'
                              is_advised: false
                              planning_id: 'kamma:planning:78'
                              consultation: false
                              required_future: not_applicable
                          advice_text:
                            scheme:
                              future: 'There is currently no confirmed scheme with a future start date affecting this property.'
                              current: 'Selective licence is required.'
                              mandatory: 'A Mandatory licensing scheme covers the whole of Oxford. This scheme is permanent and includes all HMOs with at least 5 people since October 1st 2018.'
                              selective: 'A Selective licensing scheme covers the whole of Oxford. This scheme ends on August 31st 2027 and includes all rented properties no matter how many people live there.'
                              additional: 'An Additional licensing scheme covers the whole of Oxford. This scheme ends on June 9th 2026 and includes all types of HMOs with at least 3 people on 1 storey.'
                            planning:
                              future: ''
                              current: ''
                              article4: 'An Article 4 direction covers the whole of Oxford. This direction began on February 25th 2012 requiring planning permission development rights when converting land and buildings from a C3 class to a C4 class.'
                          saved_status: null
                        kamma_id: 'kamma:check:01k42tjap7m2t18cpd2m4krwk6'
                    items:
                      type: object
                      properties:
                        address:
                          type: string
                          example: '10, Charles Street, OX4 3AS'
                        postcode:
                          type: string
                          example: 'OX4 3AS'
                        uprn:
                          type: string
                          example: null
                        category:
                          type: string
                          example: null
                        class:
                          type: string
                          example: null
                        is_above_commercial:
                          type: boolean
                          example: false
                        storeys:
                          type: string
                          example: null
                        households:
                          type: integer
                          example: 1
                        occupants:
                          type: integer
                          example: 1
                        determination_date:
                          type: string
                          example: null
                        spot_check_response:
                          type: object
                          properties:
                            id:
                              type: string
                              example: '1'
                            links:
                              type: array
                              example:
                                -
                                  rel: self
                                  href: 'https://apiv3.kamma.localhost/v3/determinations/check'
                              items:
                                type: object
                                properties:
                                  rel:
                                    type: string
                                    example: self
                                  href:
                                    type: string
                                    example: 'https://apiv3.kamma.localhost/v3/determinations/check'
                            status:
                              type: object
                              properties:
                                code:
                                  type: integer
                                  example: 200
                                message:
                                  type: string
                                  example: OK
                            schemes:
                              type: array
                              example:
                                -
                                  link: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                                  type: mandatory
                                  date_end: null
                                  required: not_required
                                  occupants: 5
                                  scheme_id: 'kamma:scheme:418'
                                  date_start: '2006-04-01'
                                  households: 2
                                  is_advised: false
                                  consultation: false
                                  required_future: not_applicable
                                -
                                  link: 'https://www.oxford.gov.uk/houses-multiple-occupation-hmos/hmo-licensing-2021-public-notice'
                                  type: additional
                                  date_end: '2026-06-09'
                                  required: not_required
                                  occupants: 3
                                  scheme_id: 'kamma:scheme:730'
                                  date_start: '2021-06-10'
                                  households: 2
                                  is_advised: false
                                  consultation: false
                                  required_future: not_applicable
                                -
                                  link: 'https://www.oxford.gov.uk/info/20010/housing/1520/selective_licensing/2'
                                  type: selective
                                  date_end: '2027-08-31'
                                  required: required
                                  occupants: 1
                                  scheme_id: 'kamma:scheme:808'
                                  date_start: '2022-09-01'
                                  households: 1
                                  is_advised: true
                                  consultation: false
                                  required_future: not_applicable
                              items:
                                type: object
                                properties:
                                  link:
                                    type: string
                                    example: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                                  type:
                                    type: string
                                    example: mandatory
                                  date_end:
                                    type: string
                                    example: null
                                  required:
                                    type: string
                                    example: not_required
                                  occupants:
                                    type: integer
                                    example: 5
                                  scheme_id:
                                    type: string
                                    example: 'kamma:scheme:418'
                                  date_start:
                                    type: string
                                    example: '2006-04-01'
                                  households:
                                    type: integer
                                    example: 2
                                  is_advised:
                                    type: boolean
                                    example: false
                                  consultation:
                                    type: boolean
                                    example: false
                                  required_future:
                                    type: string
                                    example: not_applicable
                            planning:
                              type: array
                              example:
                                -
                                  link: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                                  type: article4
                                  date_end: null
                                  required: not_required
                                  date_start: '2012-02-25'
                                  is_advised: false
                                  planning_id: 'kamma:planning:78'
                                  consultation: false
                                  required_future: not_applicable
                              items:
                                type: object
                                properties:
                                  link:
                                    type: string
                                    example: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                                  type:
                                    type: string
                                    example: article4
                                  date_end:
                                    type: string
                                    example: null
                                  required:
                                    type: string
                                    example: not_required
                                  date_start:
                                    type: string
                                    example: '2012-02-25'
                                  is_advised:
                                    type: boolean
                                    example: false
                                  planning_id:
                                    type: string
                                    example: 'kamma:planning:78'
                                  consultation:
                                    type: boolean
                                    example: false
                                  required_future:
                                    type: string
                                    example: not_applicable
                            advice_text:
                              type: object
                              properties:
                                scheme:
                                  type: object
                                  properties:
                                    future:
                                      type: string
                                      example: 'There is currently no confirmed scheme with a future start date affecting this property.'
                                    current:
                                      type: string
                                      example: 'Selective licence is required.'
                                    mandatory:
                                      type: string
                                      example: 'A Mandatory licensing scheme covers the whole of Oxford. This scheme is permanent and includes all HMOs with at least 5 people since October 1st 2018.'
                                    selective:
                                      type: string
                                      example: 'A Selective licensing scheme covers the whole of Oxford. This scheme ends on August 31st 2027 and includes all rented properties no matter how many people live there.'
                                    additional:
                                      type: string
                                      example: 'An Additional licensing scheme covers the whole of Oxford. This scheme ends on June 9th 2026 and includes all types of HMOs with at least 3 people on 1 storey.'
                                planning:
                                  type: object
                                  properties:
                                    future:
                                      type: string
                                      example: ''
                                    current:
                                      type: string
                                      example: ''
                                    article4:
                                      type: string
                                      example: 'An Article 4 direction covers the whole of Oxford. This direction began on February 25th 2012 requiring planning permission development rights when converting land and buildings from a C3 class to a C4 class.'
                            saved_status:
                              type: string
                              example: null
                        kamma_id:
                          type: string
                          example: 'kamma:check:01k42tjap7m2t18cpd2m4krwk6'
      tags:
        - 'Spot Check Endpoints'
  '/api/v1/spotchecks/{spotcheck_id}':
    get:
      summary: 'Get single spot check.'
      operationId: getSingleSpotCheck
      description: 'Retrieves a single spot check by its kamma ID'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01k42ws6zsz2rc1shy0hay1gqc
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    address: '10, Charles Street, OX4 3AS'
                    postcode: 'OX4 3AS'
                    uprn: null
                    category: null
                    class: null
                    is_above_commercial: false
                    storeys: null
                    households: 1
                    occupants: 1
                    determination_date: null
                    spot_check_response:
                      id: '1'
                      links:
                        -
                          rel: self
                          href: 'https://apiv3.kamma.localhost/v3/determinations/check'
                      status:
                        code: 200
                        message: OK
                      schemes:
                        -
                          link: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                          type: mandatory
                          date_end: null
                          required: not_required
                          occupants: 5
                          scheme_id: 'kamma:scheme:418'
                          date_start: '2006-04-01'
                          households: 2
                          is_advised: false
                          consultation: false
                          required_future: not_applicable
                        -
                          link: 'https://www.oxford.gov.uk/houses-multiple-occupation-hmos/hmo-licensing-2021-public-notice'
                          type: additional
                          date_end: '2026-06-09'
                          required: not_required
                          occupants: 3
                          scheme_id: 'kamma:scheme:730'
                          date_start: '2021-06-10'
                          households: 2
                          is_advised: false
                          consultation: false
                          required_future: not_applicable
                        -
                          link: 'https://www.oxford.gov.uk/info/20010/housing/1520/selective_licensing/2'
                          type: selective
                          date_end: '2027-08-31'
                          required: required
                          occupants: 1
                          scheme_id: 'kamma:scheme:808'
                          date_start: '2022-09-01'
                          households: 1
                          is_advised: true
                          consultation: false
                          required_future: not_applicable
                      planning:
                        -
                          link: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                          type: article4
                          date_end: null
                          required: not_required
                          date_start: '2012-02-25'
                          is_advised: false
                          planning_id: 'kamma:planning:78'
                          consultation: false
                          required_future: not_applicable
                      advice_text:
                        scheme:
                          future: 'There is currently no confirmed scheme with a future start date affecting this property.'
                          current: 'Selective licence is required.'
                          mandatory: 'A Mandatory licensing scheme covers the whole of Oxford. This scheme is permanent and includes all HMOs with at least 5 people since October 1st 2018.'
                          selective: 'A Selective licensing scheme covers the whole of Oxford. This scheme ends on August 31st 2027 and includes all rented properties no matter how many people live there.'
                          additional: 'An Additional licensing scheme covers the whole of Oxford. This scheme ends on June 9th 2026 and includes all types of HMOs with at least 3 people on 1 storey.'
                        planning:
                          future: ''
                          current: ''
                          article4: 'An Article 4 direction covers the whole of Oxford. This direction began on February 25th 2012 requiring planning permission development rights when converting land and buildings from a C3 class to a C4 class.'
                      saved_status: null
                    kamma_id: 'kamma:check:01k42tjap7m2t18cpd2m4krwk6'
                    data_status:
                      http: 200
                      code: 200
                      message: OK
                      description: 'This spot check has been shown successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01k42ws6zsz2rc1shy0hay1gqc
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      address:
                        type: string
                        example: '10, Charles Street, OX4 3AS'
                      postcode:
                        type: string
                        example: 'OX4 3AS'
                      uprn:
                        type: string
                        example: null
                      category:
                        type: string
                        example: null
                      class:
                        type: string
                        example: null
                      is_above_commercial:
                        type: boolean
                        example: false
                      storeys:
                        type: string
                        example: null
                      households:
                        type: integer
                        example: 1
                      occupants:
                        type: integer
                        example: 1
                      determination_date:
                        type: string
                        example: null
                      spot_check_response:
                        type: object
                        properties:
                          id:
                            type: string
                            example: '1'
                          links:
                            type: array
                            example:
                              -
                                rel: self
                                href: 'https://apiv3.kamma.localhost/v3/determinations/check'
                            items:
                              type: object
                              properties:
                                rel:
                                  type: string
                                  example: self
                                href:
                                  type: string
                                  example: 'https://apiv3.kamma.localhost/v3/determinations/check'
                          status:
                            type: object
                            properties:
                              code:
                                type: integer
                                example: 200
                              message:
                                type: string
                                example: OK
                          schemes:
                            type: array
                            example:
                              -
                                link: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                                type: mandatory
                                date_end: null
                                required: not_required
                                occupants: 5
                                scheme_id: 'kamma:scheme:418'
                                date_start: '2006-04-01'
                                households: 2
                                is_advised: false
                                consultation: false
                                required_future: not_applicable
                              -
                                link: 'https://www.oxford.gov.uk/houses-multiple-occupation-hmos/hmo-licensing-2021-public-notice'
                                type: additional
                                date_end: '2026-06-09'
                                required: not_required
                                occupants: 3
                                scheme_id: 'kamma:scheme:730'
                                date_start: '2021-06-10'
                                households: 2
                                is_advised: false
                                consultation: false
                                required_future: not_applicable
                              -
                                link: 'https://www.oxford.gov.uk/info/20010/housing/1520/selective_licensing/2'
                                type: selective
                                date_end: '2027-08-31'
                                required: required
                                occupants: 1
                                scheme_id: 'kamma:scheme:808'
                                date_start: '2022-09-01'
                                households: 1
                                is_advised: true
                                consultation: false
                                required_future: not_applicable
                            items:
                              type: object
                              properties:
                                link:
                                  type: string
                                  example: 'https://www.oxford.gov.uk/info/20237/properties_that_need_an_hmo_licence/926/houses_or_flats_that_need_an_hmo_licence'
                                type:
                                  type: string
                                  example: mandatory
                                date_end:
                                  type: string
                                  example: null
                                required:
                                  type: string
                                  example: not_required
                                occupants:
                                  type: integer
                                  example: 5
                                scheme_id:
                                  type: string
                                  example: 'kamma:scheme:418'
                                date_start:
                                  type: string
                                  example: '2006-04-01'
                                households:
                                  type: integer
                                  example: 2
                                is_advised:
                                  type: boolean
                                  example: false
                                consultation:
                                  type: boolean
                                  example: false
                                required_future:
                                  type: string
                                  example: not_applicable
                          planning:
                            type: array
                            example:
                              -
                                link: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                                type: article4
                                date_end: null
                                required: not_required
                                date_start: '2012-02-25'
                                is_advised: false
                                planning_id: 'kamma:planning:78'
                                consultation: false
                                required_future: not_applicable
                            items:
                              type: object
                              properties:
                                link:
                                  type: string
                                  example: 'https://www.oxford.gov.uk/planning-policy/planning-control-houses-multiple-occupation'
                                type:
                                  type: string
                                  example: article4
                                date_end:
                                  type: string
                                  example: null
                                required:
                                  type: string
                                  example: not_required
                                date_start:
                                  type: string
                                  example: '2012-02-25'
                                is_advised:
                                  type: boolean
                                  example: false
                                planning_id:
                                  type: string
                                  example: 'kamma:planning:78'
                                consultation:
                                  type: boolean
                                  example: false
                                required_future:
                                  type: string
                                  example: not_applicable
                          advice_text:
                            type: object
                            properties:
                              scheme:
                                type: object
                                properties:
                                  future:
                                    type: string
                                    example: 'There is currently no confirmed scheme with a future start date affecting this property.'
                                  current:
                                    type: string
                                    example: 'Selective licence is required.'
                                  mandatory:
                                    type: string
                                    example: 'A Mandatory licensing scheme covers the whole of Oxford. This scheme is permanent and includes all HMOs with at least 5 people since October 1st 2018.'
                                  selective:
                                    type: string
                                    example: 'A Selective licensing scheme covers the whole of Oxford. This scheme ends on August 31st 2027 and includes all rented properties no matter how many people live there.'
                                  additional:
                                    type: string
                                    example: 'An Additional licensing scheme covers the whole of Oxford. This scheme ends on June 9th 2026 and includes all types of HMOs with at least 3 people on 1 storey.'
                              planning:
                                type: object
                                properties:
                                  future:
                                    type: string
                                    example: ''
                                  current:
                                    type: string
                                    example: ''
                                  article4:
                                    type: string
                                    example: 'An Article 4 direction covers the whole of Oxford. This direction began on February 25th 2012 requiring planning permission development rights when converting land and buildings from a C3 class to a C4 class.'
                          saved_status:
                            type: string
                            example: null
                      kamma_id:
                        type: string
                        example: 'kamma:check:01k42tjap7m2t18cpd2m4krwk6'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 200
                          code:
                            type: integer
                            example: 200
                          message:
                            type: string
                            example: OK
                          description:
                            type: string
                            example: 'This spot check has been shown successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: 'when trying to access a spot check belonging to another company'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        404:
          description: 'no spot check found'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    http: 404
                    code: 404
                    message: 'Not Found'
                    description: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqqrmhsjgfpgnttsnc2jneq
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 404
                      code:
                        type: integer
                        example: 404
                      message:
                        type: string
                        example: 'Not Found'
                      description:
                        type: string
                        example: 'The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01k42xm8e2gpc72pseabk4v2hs
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This spot check could not be shown.'
                      has_errors: true
                      error_count: 2
                      errors:
                        spotcheck_id:
                          - 'The spotcheck id must start with one of the following: kamma:check:.'
                          - 'The spotcheck id format is invalid.'
                properties:
                  api_id:
                    type: string
                    example: 01k42xm8e2gpc72pseabk4v2hs
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This spot check could not be shown.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 2
                          errors:
                            type: object
                            properties:
                              spotcheck_id:
                                type: array
                                example:
                                  - 'The spotcheck id must start with one of the following: kamma:check:.'
                                  - 'The spotcheck id format is invalid.'
                                items:
                                  type: string
      tags:
        - 'Spot Check Endpoints'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spotcheck_id:
                  type: string
                  description: 'Must start with one of <code>kamma:check:</code> Must match the regex /^kamma:check:[0-7][0-9A-HJKMNP-TV-Z]{25}$/i.'
                  example: 'kamma:check:7ZVPZVRXK5KMACXEVDAAG6HWRZ$/i'
              required:
                - spotcheck_id
    parameters:
      -
        in: path
        name: spotcheck_id
        description: 'The kamma ID for the spot check.'
        example: 'kamma:check:01hb8a2kgtfq35516ygtdnhbax'
        required: true
        schema:
          type: string
  /api/v1/spotchecks/save:
    post:
      summary: 'Save spot check.'
      operationId: saveSpotCheck
      description: 'Saves spot checks for retrieval later'
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01k42xh18bxpb2wm2nwbtkxx0j
                  status:
                    http: 201
                    code: 201
                    message: Created
                    description: 'The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests, or some PUT requests.'
                    has_errors: false
                    error_count: 0
                  data:
                    address: '10, Charles Street, OX4 3AS'
                    postcode: 'OX4 3AS'
                    uprn: null
                    category: null
                    class: null
                    is_above_commercial: false
                    storeys: null
                    determination_date: null
                    households: 1
                    occupants: 1
                    spot_check_response:
                      hey: true
                    kamma_id: 'kamma:check:01k42xh1ng5123gsrkh2ag2k09'
                    data_status:
                      http: 201
                      code: 201
                      message: Created
                      description: 'This spot check has been created successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01k42xh18bxpb2wm2nwbtkxx0j
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 201
                      code:
                        type: integer
                        example: 201
                      message:
                        type: string
                        example: Created
                      description:
                        type: string
                        example: 'The request succeeded, and a new resource was created as a result. This is typically the response sent after POST requests, or some PUT requests.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      address:
                        type: string
                        example: '10, Charles Street, OX4 3AS'
                      postcode:
                        type: string
                        example: 'OX4 3AS'
                      uprn:
                        type: string
                        example: null
                      category:
                        type: string
                        example: null
                      class:
                        type: string
                        example: null
                      is_above_commercial:
                        type: boolean
                        example: false
                      storeys:
                        type: string
                        example: null
                      determination_date:
                        type: string
                        example: null
                      households:
                        type: integer
                        example: 1
                      occupants:
                        type: integer
                        example: 1
                      spot_check_response:
                        type: object
                        properties:
                          hey:
                            type: boolean
                            example: true
                      kamma_id:
                        type: string
                        example: 'kamma:check:01k42xh1ng5123gsrkh2ag2k09'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 201
                          code:
                            type: integer
                            example: 201
                          message:
                            type: string
                            example: Created
                          description:
                            type: string
                            example: 'This spot check has been created successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The addressing.uprn must be between 1 and 12 digits. (and 3 more errors)'
                  errors:
                    addressing.uprn:
                      - 'The addressing.uprn must be between 1 and 12 digits.'
                      - 'It looks like the uprn is incorrect. Please check both the uprn and the postcode.'
                    category:
                      - 'The selected category is invalid.'
                    class:
                      - 'The selected class is invalid.'
                properties:
                  message:
                    type: string
                    example: 'The addressing.uprn must be between 1 and 12 digits. (and 3 more errors)'
                  errors:
                    type: object
                    properties:
                      addressing.uprn:
                        type: array
                        example:
                          - 'The addressing.uprn must be between 1 and 12 digits.'
                          - 'It looks like the uprn is incorrect. Please check both the uprn and the postcode.'
                        items:
                          type: string
                      category:
                        type: array
                        example:
                          - 'The selected category is invalid.'
                        items:
                          type: string
                      class:
                        type: array
                        example:
                          - 'The selected class is invalid.'
                        items:
                          type: string
      tags:
        - 'Spot Check Endpoints'
  /api/v1/properties/stats:
    get:
      summary: 'Get property statistics.'
      operationId: getPropertyStatistics
      description: 'Returns statistics about properties including total count, compliance status, and other metrics.'
      parameters:
        -
          in: query
          name: exclude_determinations
          description: 'Whether to exclude determination statistics. Defaults to false.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Whether to exclude determination statistics. Defaults to false.'
            example: true
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  $schema: 'https://apiv3.kamma.localhost/schemas/PortfolioStatsBody.json'
                  total_properties: 285
                  info_needed_count: 218
                  licence_required_count: 10
                  compliant_count: 9
                  compliance_percentage: 3
                  action_texts:
                    error: 46
                    licence_additional_scheme: 0
                    licence_applied_date: 0
                    licence_expired: 2
                    licence_households: 0
                    licence_mandatory_scheme: 0
                    licence_occupants: 0
                    licence_rejected: 0
                    licence_requested: 3
                    licence_start_date: 0
                    licence_upload: 0
                    mismatch_coordinates: 92
                    missing_coordinates: 28
                    missing_licence: 10
                    none: 2
                    occupancy: 190
                    verify_address: 155
                  determinations:
                    additional:
                      licenced: 1
                      maybe: 1
                      required: 2
                      unlicenced: 2
                    mandatory:
                      licenced: 1
                      maybe: 0
                      required: 6
                      unlicenced: 5
                    selective:
                      licenced: 0
                      maybe: 0
                      required: 9
                      unlicenced: 9
                    unknown:
                      licenced: 0
                      unknown: 0
                      unlicenced: 0
                  future_determinations:
                    additional:
                      licenced: 0
                      maybe: 0
                      required: 0
                      unlicenced: 0
                    mandatory:
                      licenced: 0
                      maybe: 0
                      required: 0
                      unlicenced: 0
                    selective:
                      licenced: 0
                      maybe: 0
                      required: 0
                      unlicenced: 0
                    unknown:
                      licenced: 0
                      unknown: 85
                      unlicenced: 85
                  status:
                    code: 200
                    message: OK
                properties:
                  $schema:
                    type: string
                    example: 'https://apiv3.kamma.localhost/schemas/PortfolioStatsBody.json'
                  total_properties:
                    type: integer
                    example: 285
                  info_needed_count:
                    type: integer
                    example: 218
                  licence_required_count:
                    type: integer
                    example: 10
                  compliant_count:
                    type: integer
                    example: 9
                  compliance_percentage:
                    type: integer
                    example: 3
                  action_texts:
                    type: object
                    properties:
                      error:
                        type: integer
                        example: 46
                      licence_additional_scheme:
                        type: integer
                        example: 0
                      licence_applied_date:
                        type: integer
                        example: 0
                      licence_expired:
                        type: integer
                        example: 2
                      licence_households:
                        type: integer
                        example: 0
                      licence_mandatory_scheme:
                        type: integer
                        example: 0
                      licence_occupants:
                        type: integer
                        example: 0
                      licence_rejected:
                        type: integer
                        example: 0
                      licence_requested:
                        type: integer
                        example: 3
                      licence_start_date:
                        type: integer
                        example: 0
                      licence_upload:
                        type: integer
                        example: 0
                      mismatch_coordinates:
                        type: integer
                        example: 92
                      missing_coordinates:
                        type: integer
                        example: 28
                      missing_licence:
                        type: integer
                        example: 10
                      none:
                        type: integer
                        example: 2
                      occupancy:
                        type: integer
                        example: 190
                      verify_address:
                        type: integer
                        example: 155
                  determinations:
                    type: object
                    properties:
                      additional:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 1
                          maybe:
                            type: integer
                            example: 1
                          required:
                            type: integer
                            example: 2
                          unlicenced:
                            type: integer
                            example: 2
                      mandatory:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 1
                          maybe:
                            type: integer
                            example: 0
                          required:
                            type: integer
                            example: 6
                          unlicenced:
                            type: integer
                            example: 5
                      selective:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 0
                          maybe:
                            type: integer
                            example: 0
                          required:
                            type: integer
                            example: 9
                          unlicenced:
                            type: integer
                            example: 9
                      unknown:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 0
                          unknown:
                            type: integer
                            example: 0
                          unlicenced:
                            type: integer
                            example: 0
                  future_determinations:
                    type: object
                    properties:
                      additional:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 0
                          maybe:
                            type: integer
                            example: 0
                          required:
                            type: integer
                            example: 0
                          unlicenced:
                            type: integer
                            example: 0
                      mandatory:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 0
                          maybe:
                            type: integer
                            example: 0
                          required:
                            type: integer
                            example: 0
                          unlicenced:
                            type: integer
                            example: 0
                      selective:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 0
                          maybe:
                            type: integer
                            example: 0
                          required:
                            type: integer
                            example: 0
                          unlicenced:
                            type: integer
                            example: 0
                      unknown:
                        type: object
                        properties:
                          licenced:
                            type: integer
                            example: 0
                          unknown:
                            type: integer
                            example: 85
                          unlicenced:
                            type: integer
                            example: 85
                  status:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
      tags:
        - 'Statistics Endpoints'
  /api/v1/users:
    post:
      summary: 'Create user.'
      operationId: createUser
      description: "This endpoint creates a new user. It's a tempororary solution which we plan to replace with an SSO endpoint."
      parameters:
        -
          in: header
          name: X-SSO-API-Key
          description: ''
          example: '{YOUR_AUTH_KEY}'
          schema:
            type: string
        -
          in: header
          name: X-SSO-Group-ID
          description: ''
          example: 5
          schema:
            type: string
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hg86yr3bvbqtd99a8ydnxsx7
                  status:
                    http: 200
                    code: 200
                    message: OK
                    description: 'The request succeeded.'
                    has_errors: false
                    error_count: 0
                  data:
                    id: 14
                    sso_group_id: 139
                    name: 'Joe Biden'
                    email: joe.biden@whitehouse.org
                    origin: reapit
                    created_at: '2023-11-27T10:59:43.000000Z'
                    updated_at: '2023-11-27T10:59:43.000000Z'
                    data_status:
                      http: 201
                      code: 201
                      message: Created
                      description: 'This user has been created successfully.'
                      has_errors: false
                      error_count: 0
                      errors: []
                properties:
                  api_id:
                    type: string
                    example: 01hg86yr3bvbqtd99a8ydnxsx7
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 200
                      code:
                        type: integer
                        example: 200
                      message:
                        type: string
                        example: OK
                      description:
                        type: string
                        example: 'The request succeeded.'
                      has_errors:
                        type: boolean
                        example: false
                      error_count:
                        type: integer
                        example: 0
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 14
                      sso_group_id:
                        type: integer
                        example: 139
                      name:
                        type: string
                        example: 'Joe Biden'
                      email:
                        type: string
                        example: joe.biden@whitehouse.org
                      origin:
                        type: string
                        example: reapit
                      created_at:
                        type: string
                        example: '2023-11-27T10:59:43.000000Z'
                      updated_at:
                        type: string
                        example: '2023-11-27T10:59:43.000000Z'
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 201
                          code:
                            type: integer
                            example: 201
                          message:
                            type: string
                            example: Created
                          description:
                            type: string
                            example: 'This user has been created successfully.'
                          has_errors:
                            type: boolean
                            example: false
                          error_count:
                            type: integer
                            example: 0
                          errors:
                            type: array
                            example: []
        401:
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    http: 401
                    code: 401
                    message: Unauthorized
                    description: 'Missing or invalid Kamma SSO API key.'
                properties:
                  api_id:
                    type: string
                    example: 01hbx1y74q1c63fgvkcyg6d4te
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 401
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Unauthorized
                      description:
                        type: string
                        example: 'Missing or invalid Kamma SSO API key.'
        403:
          description: forbidden
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    http: 403
                    code: 403
                    message: Forbidden
                    description: 'You are not permitted to access the specified resource.'
                properties:
                  api_id:
                    type: string
                    example: 01hbqr0x9cfbe31grhpvaz99fe
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 403
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: Forbidden
                      description:
                        type: string
                        example: 'You are not permitted to access the specified resource.'
        422:
          description: 'invalid params'
          content:
            application/json:
              schema:
                type: object
                example:
                  api_id: 01hg87desyf7zgzw9bjsgxfwf8
                  status:
                    http: 422
                    code: 422
                    message: 'Unprocessable Content'
                    description: 'The request was well-formed but was unable to be followed due to semantic errors.'
                    has_errors: true
                    error_count: 1
                  data:
                    data_status:
                      http: 422
                      code: 422
                      message: 'Unprocessable Content'
                      description: 'This user could not be created.'
                      has_errors: true
                      error_count: 1
                      errors:
                        email:
                          - 'The email field is required.'
                properties:
                  api_id:
                    type: string
                    example: 01hg87desyf7zgzw9bjsgxfwf8
                  status:
                    type: object
                    properties:
                      http:
                        type: integer
                        example: 422
                      code:
                        type: integer
                        example: 422
                      message:
                        type: string
                        example: 'Unprocessable Content'
                      description:
                        type: string
                        example: 'The request was well-formed but was unable to be followed due to semantic errors.'
                      has_errors:
                        type: boolean
                        example: true
                      error_count:
                        type: integer
                        example: 1
                  data:
                    type: object
                    properties:
                      data_status:
                        type: object
                        properties:
                          http:
                            type: integer
                            example: 422
                          code:
                            type: integer
                            example: 422
                          message:
                            type: string
                            example: 'Unprocessable Content'
                          description:
                            type: string
                            example: 'This user could not be created.'
                          has_errors:
                            type: boolean
                            example: true
                          error_count:
                            type: integer
                            example: 1
                          errors:
                            type: object
                            properties:
                              email:
                                type: array
                                example:
                                  - 'The email field is required.'
                                items:
                                  type: string
      tags:
        - 'User Endpoints'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Must be at least 1 character. Must not be greater than 255 characters.'
                  example: pasyzwszwtxpeqq
                email:
                  type: string
                  description: 'Must be a valid email address.'
                  example: tremayne.kohler@example.net
                origin:
                  type: string
                  description: ''
                  example: null
              required:
                - name
                - email
tags:
  -
    name: 'Compliance Endpoints'
    description: "\nAPI endpoint for managing property compliance"
  -
    name: Endpoints
    description: ''
  -
    name: 'Licence Endpoints'
    description: ''
  -
    name: 'Manager Endpoints'
    description: "\nAPI endpoint for managers"
  -
    name: 'Property Endpoints'
    description: "\nAPI endpoint for properties CRUD"
  -
    name: 'Property Export'
    description: ''
  -
    name: 'Spot Check Endpoints'
    description: "\nAPI endpoint for spotcheck CRUD"
  -
    name: 'Statistics Endpoints'
    description: "\nAPI endpoints for property statistics"
  -
    name: 'User Endpoints'
    description: "\nAPI endpoint for users CRUD"
components:
  securitySchemes:
    default:
      type: apiKey
      name: X-SSO-API-Key
      in: header
      description: 'You can request a token from the Kamma team.'
security:
  -
    default: []
