openapi: 3.0.1
info:
  title: SERV Verify EAPI
  description: >
    SERV Verify Experience API


    Exposes functionality relating to checking particular data elements against
    the Registries.


    - Check and verify ownership of an individual or organisation
  version: v1
servers:
  - url: https://api.servictoria.io/vicland/verify/v1
    description: Production
  - url: https://test.api.servictoria.io/vicland/verify/v1
    description: UAT
security:
  - oauth2ClientCredentials: []
paths:
  /ownership-check:
    post:
      summary: Check ownership
      description: >-
        Check and verify ownership of an individual or organisation against
        property records
      operationId: checkOwnership
      parameters:
        - name: x-correlation-id
          in: header
          description: A unique transaction id used to correlate api requests end to end.
          schema:
            type: string
        - name: x-source-system
          in: header
          description: A unique identification string for the source system.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OwnershipCheckRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnershipCheckResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /health:
    get:
      summary: Health Check
      description: Health check endpoint for the API
      operationId: healthCheck
      parameters:
        - name: x-correlation-id
          in: header
          description: A unique transaction id used to correlate api requests end to end.
          schema:
            type: string
        - name: x-source-system
          in: header
          description: A unique identification string for the source system.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    OwnershipCheckRequest:
      type: object
      required:
        - identifier
        - searchNames
      properties:
        identifier:
          type: object
          description: >-
            The distinguishing marker for various request types. Must be only 1
            from the list.
          additionalProperties: true
        searchNames:
          type: array
          description: >-
            The names to be checked against the proprietor name(s) against a
            Title.
          items:
            type: object
            additionalProperties: true
      example:
        identifier:
          propertyAddress:
            unitFlatNumber: '7273'
            streetNumber: '788'
            streetName: Park Street
            streetType: Avenue
            streetSuffix: AV
            suburbTownLocality: Pakenham
            postcode: 3810
        searchNames:
          - searchNameId: 1
            individual:
              surname: Dawson
              givenNames: James
    OwnershipCheckResponse:
      type: object
      required:
        - applicantsMatchResults
      properties:
        applicantsMatchResults:
          type: array
          description: Container for all supplied Applicants' matching results.
          items:
            type: object
            additionalProperties: true
        proprietorCompleteness:
          type: string
          description: Supplied the completeness of proprietor
          enum:
            - 'Y'
            - 'N'
        moreThanOneTitle:
          type: string
          description: Are there more than one title for the given identifier?
          enum:
            - 'Y'
            - 'N'
      example:
        applicantsMatchResults:
          - searchNameId: 1
            individual:
              surname: Dawson
              givenNames: James
              individualMatchType: FullName
              individualMatchResult: Exact
            organisation:
              orgName: ABC Pty
              organisationMatchResult: Exact
        proprietorCompleteness: 'Y'
        moreThanOneTitle: 'N'
    ErrorResponse:
      type: object
      required:
        - code
        - correlationId
        - description
        - errorType
        - timestamp
      properties:
        code:
          type: string
          description: The HTTP Status code of the response.
        errorType:
          type: string
          description: Error Type
        description:
          type: string
          description: Error Description
        timestamp:
          type: string
          format: date-time
          description: The time at which the API was invoked
        correlationId:
          type: string
          description: Unique ID for API request
      example:
        code: '400'
        errorType: ESB:BAD_REQUEST
        description: Bad Request
        timestamp: '2022-01-17T03:31:09.691Z'
        correlationId: 2aa11828-1243-4026-8ee3-7b5c77cef796
    HealthCheckResponse:
      type: object
      required:
        - applicationName
        - applicationVersion
        - apiName
        - environment
        - status
      properties:
        applicationName:
          type: string
          description: Application Name
        applicationVersion:
          type: string
          description: Application Version
        apiName:
          type: string
          description: API Name
        environment:
          type: string
          description: Environment
        status:
          type: string
          description: Status
      example:
        applicationName: SERV Verify EAPI
        applicationVersion: 1.0.0
        apiName: serv-verify-eapi
        environment: PROD
        status: running
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials authentication
      flows:
        clientCredentials:
          tokenUrl: https://auth.servictoria.io/oauth/token
          scopes: {}
