openapi: 3.0.0
info:
  version: 1.2.1
  title: 'Customer Management API'
  description: 'This API is part of the OpenWealth APIs for the connectivity between custody banks and WealthTechs (e.g. Portfolio Management Systems). This API allows the user to receive data from custody banks regarding customer data and alter and create address and contact data.'
  contact:
    email: wealth@common-api.ch
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/OpenWealthAPI/CustomerManagement/1.2.1

paths:
    /customers:
        get:
            summary: Returns a list of customers.
            description: Returns a list of all customers. A customer is an object which holds a contract with a (custody-)bank. Paging is done based on the customer object, i.e. if limit is set to 1, then 1 customer will be returned per page.

            operationId: getCustomers
            tags:
             - customer
            parameters: 
              - $ref: '#/components/parameters/cursor'
              - $ref: '#/components/parameters/limit'
              - $ref: '#/components/parameters/correlation_in_header'
            responses:
                '200':
                    description: A customer object list.
                    headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                      nextCursor:
                        $ref: '#/components/headers/nextCursor'
                    content:
                        application/json:
                            schema:
                              type: array
                              items:  
                                $ref: '#/components/schemas/customer'
                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503' 
        
    /customers/{customerId}:
        parameters: 
            - $ref: '#/components/parameters/cursor'
            - $ref: '#/components/parameters/limit'
            - $ref: '#/components/parameters/customerId'
            - $ref: '#/components/parameters/correlation_in_header'
        get:
            summary: Returns a specific customer.
            description: Returns a full client record for a specific customer id.
            operationId: getCustomerByCustomerId
            tags:
              - customer
            responses:
                '200':
                    description: A specific customer object.
                    headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/customer'
                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503' 

    /customers/{customerId}/kyc:
        parameters: 
              - $ref: '#/components/parameters/cursor'
              - $ref: '#/components/parameters/limit'
              - $ref: '#/components/parameters/customerId'
              - $ref: '#/components/parameters/correlation_in_header'
        get:
            summary: Returns the kyc to a specific customer.
            description: Returns the know-your-client record for a specific customer.
            operationId: getKycByCustomerId
            tags:
              - kyc
            responses:
                '200':
                    description: A specific kyc object.
                    headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/customerAndKycResponse'

                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503' 
    
    /persons:
        parameters: 
          - $ref: '#/components/parameters/cursor'
          - $ref: '#/components/parameters/limit'
          - $ref: '#/components/parameters/correlation_in_header'
        get:
            summary: Returns a list with all person objects.
            description: Returns all person records. Paging is done based on the person object, i.e. if limit is set to 1, then 1 person will be returned per page.

            operationId: getPersons
            tags:
              - person
            responses:
                '200':
                    description: A person list.
                    headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                      nextCursor:
                        $ref: '#/components/headers/nextCursor'
                    content:
                        application/json:
                            schema:
                              type: array
                              items:
                                $ref: '#/components/schemas/person'
                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503'
    
    /persons/{personId}:
        parameters: 
          - $ref: '#/components/parameters/personId'
          - $ref: '#/components/parameters/cursor'
          - $ref: '#/components/parameters/limit'
          - $ref: '#/components/parameters/correlation_in_header'
        get:
            summary: Returns a specific person object.
            description: Returns a person record for a specific person id.
            operationId: getPersonByPersonId
            tags:
              - person
            responses:
                '200':
                    description: A specific person object.
                    headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                    content:
                        application/json:
                            schema:
                              $ref: '#/components/schemas/person'
                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503' 
    /persons/{personId}/contactdetails:
        parameters: 
          - $ref: '#/components/parameters/personId'
          - $ref: '#/components/parameters/cursor'
          - $ref: '#/components/parameters/limit'
          - $ref: '#/components/parameters/correlation_in_header'
        get:
            summary: Returns the contact details for a specific person.
            description: Returns a contact detail list for a specific person id.
            operationId: getContactDetailsByPersonId
            tags:
              - person
            responses:
                '200':
                    description: A contact detail list.
                    headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                    content:
                        application/json:
                            schema:
                              type: array
                              items:
                                $ref: '#/components/schemas/contactDetails'
                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503' 
        post:
            summary: Creates new contact details for a specific person.
            description: Creates new contact details for a specific person id.
            operationId: postContactDetailsByPersonId
            tags:
              - person
            requestBody:
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/contactDetails'
            responses:
                '201':
                  description: Contact details created.
                  headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/contactDetails'
                '400':
                  $ref: '#/components/responses/standard400'
                '401':
                  $ref: '#/components/responses/standard401'
                '403':
                  $ref: '#/components/responses/standard403'
                '404':
                  $ref: '#/components/responses/standard404'
                '405':
                  $ref: '#/components/responses/standard405'
                '500':
                  $ref: '#/components/responses/standard500'
                '501':
                  $ref: '#/components/responses/standard501'
                '503':
                  $ref: '#/components/responses/standard503' 
    /customers/{customerId}/addresses:
        parameters: 
          - $ref: '#/components/parameters/customerId'
          - $ref: '#/components/parameters/cursor'
          - $ref: '#/components/parameters/limit'
          - $ref: '#/components/parameters/correlation_in_header'
        post:
          summary: Creates a new address object for a specific customer.
          operationId: postAddressByCustomerId
          tags:
              - address
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/addressNew'
          responses: 
            '201':
              description: Successfully created a new address object.
              headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/addressIdentificationResponse'
            '400':
              $ref: '#/components/responses/standard400'
            '401':
              $ref: '#/components/responses/standard401'
            '403':
              $ref: '#/components/responses/standard403'
            '404':
              $ref: '#/components/responses/standard404'
            '405':
              $ref: '#/components/responses/standard405'
            '500':
              $ref: '#/components/responses/standard500'
            '501':
              $ref: '#/components/responses/standard501'
            '503':
              $ref: '#/components/responses/standard503'  
              
        get:
            summary: Returns the address of a specific customer.
            description: Returns a address record for a specific customer.
            operationId: getAddressByCustomerId
            tags:
              - address
            responses:
              '200':
                description: A specific address object.
                headers:
                  X-Correlation-ID:
                    $ref: '#/components/headers/X-Correlation-ID'
                content:
                  application/json:
                      schema:
                        $ref: '#/components/schemas/address'
              '400':
                $ref: '#/components/responses/standard400'
              '401':
                $ref: '#/components/responses/standard401'
              '403':
                $ref: '#/components/responses/standard403'
              '404':
                $ref: '#/components/responses/standard404'
              '405':
                $ref: '#/components/responses/standard405'
              '500':
                $ref: '#/components/responses/standard500'
              '501':
                $ref: '#/components/responses/standard501'
              '503':
                $ref: '#/components/responses/standard503'  
          
        put:
          summary: Updates an existing address object for a specific customer.
          operationId: putAddressByCustomerId
          tags:
              - address
          requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/address'
          responses: 
            '204':
              description: No content.
              headers:
                      X-Correlation-ID:
                        $ref: '#/components/headers/X-Correlation-ID'
            '400':
              $ref: '#/components/responses/standard400'
            '401':
              $ref: '#/components/responses/standard401'
            '403':
              $ref: '#/components/responses/standard403'
            '404':
              $ref: '#/components/responses/standard404'
            '405':
              $ref: '#/components/responses/standard405'
            '500':
              $ref: '#/components/responses/standard500'
            '501':
              $ref: '#/components/responses/standard501'
            '503':
              $ref: '#/components/responses/standard503' 
        
components:
  parameters:
    customerId:  
        name: customerId
        in: path
        required: true
        schema:
          type: string
          description: The customer's id
    personId:
        name: personId
        in: path
        required: true
        schema:
          type: string
          description: The persons's id
    limit: 
      name: limit
      in: query
      description: Maximum number of items to return.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
    cursor:
      name: cursor
      in: query
      description: An opaque string value used for pagination
      required: false
      schema:
        type: string
    correlation_in_header:
      in: header
      name: X-Correlation-ID
      description: Unique ID (defined by the caller) which will be reflected back in the response.
      required: true
      schema:
        type: string

  ###############
  # Headers     #
  ###############

  headers:
  
    X-Correlation-ID:
      description: Client defined ID from request to correlates HTTP requests between a client and server.
      schema:
        type: string
        example: f058ebd6-02f7-4d3f-942e-904344e8cde5
    nextCursor:
      description: An opaque string value, or an empty string if there are no more results. 
      required: false
      schema:
        type: string
        
        
######################
# Schemas
######################
  schemas:

    customer:
      type: object
      required: 
        - customerIdentification
        - status
      properties:
            customerIdentification:
                type: string
                minLength: 1
                maxLength: 35
                example: 987654321
                description: 'Customer ID of the bank'
            externalReference:
                type: string
                maxLength: 35
                example: 123-456-787
                description: 'External customer ID'
            name:
                type: string
                maxLength: 70
                example: Steve Rogers
                description: 'Name of the customer object'
            status:
                type: string
                example: active
                enum: 
                - active
                - inactive
                - closed
                description: Status of the customer
            referenceCurrency:
                $ref: '#/components/schemas/currency'
            openingDate:
                $ref: '#/components/schemas/date'
            personList:
                type: array
                items:
                  type: object
                  properties:
                    personRelation:
                      type: string
                      example: accountOwner
                      description: Indicates what relation this person has to the specified customer.
                      enum: 
                      - beneficialOwner
                      - authorisedRepresentative
                      - assetManager
                      - accountOwner
                      - authorisedSignatory
                      - other
                    personIdentification:
                      type: string
                      maxLength: 35
                      example: 876543219
                      description: 'Bank identification of the person'
            addressList:
                type: array
                description: List of addresses associated with the customer
                items:
                  type: object
                  properties:
                    addressIdentification:
                      type: number
                      example: 12345678
                      description: 'Bank ID of the address object'

    person:
      type: object
      required:
        - personIdentification
        - personType
        - personDetails
      properties:
        personIdentification:
          type: string
          minLength: 1
          maxLength: 35
          example: 876543219
          description: 'Bank identification of the person'
        externalReference:
          type: string
          maxLength: 35
          example: 987-654-321
          description: 'External person ID'
        customerList:
          type: array
          items:
            type: object
            properties:
              customerIdentification:
                type: string
                maxLength: 35
                example: 123123
        fullName:
          type: string
          maxLength: 70
          example: Tony Stark
          description: 'Name of the person object'
        countryOfDomicile:
          $ref: '#/components/schemas/country'
        language:
          type: string
          maxLength: 35
          example: German
          description: 'Language for all communication concerning the account'
        contactInformation:
          type: array
          items:
            $ref: '#/components/schemas/contactDetails'
        personDetails:
          description: Further details about the person. Schema depends on personType.
          $ref: '#/components/schemas/personDetails'
        taxDomicile:
          type: array
          description: 'Indicates the tax domiciles of the person'
          items:
            $ref: '#/components/schemas/country'

    personDetails:
      type: object
      description: 'Further details about the person. Schema depends on personType.'
      required:
        - personType
      properties:
        personType:
          type: string
          enum:
            - naturalPerson
            - legalPerson
            - personAssociation
            - trust
            - soleProprietorship
          example: naturalPerson
          description: 'Indicates the type of the person object'
      discriminator:
        propertyName: personType

    naturalPerson: # "naturalPerson" will be used as disciminator
      allOf:
        - $ref: '#/components/schemas/personDetails'
        - type: object
          properties:
            givenName:
              type: string
              maxLength: 35
              example: Anthony
              description: 'Given name of the person'
            middleName:
              type: string
              maxLength: 35
              example: Edward
              description: 'Middle name of the person'
            lastName:
              type: string
              maxLength: 35
              example: Stark
              description: 'Last name of the person'
            title:
              type: string
              maxLength: 35
              example: PhD
              description: 'Official title of the person'
            dates:
              type: array
              items:
                type: object
                properties:
                  date:
                    $ref: '#/components/schemas/date'
                  dateType:
                    description: Type of the date
                    type: string
                    enum:
                      - birthDate
                      - divorceDate
                      - deathDate
            gender:
              type: string
              enum:
                - male
                - female
                - other
              example: male
              description: 'Gender of the person'
            nationality:
              type: array
              description: 'Indicates the nationality of the person'
              items:
                $ref: '#/components/schemas/country'
            civilStatus:
              type: string
              enum:
                - unmarried
                - married
                - divorced
                - widowed
              example: married
              description: 'Civil status of the individual person'
            TIN:
              type: string
              maxLength: 35
              example: 123-12-1234

    legalPerson: # "legalPerson" will be used as disciminator
      allOf:
        - $ref: '#/components/schemas/personDetails'
        - type: object
          required:
            - organisationName
            - legalForm
            - domicilaryCompany
          properties:
            organisationName:
              type: string
              minLength: 1
              maxLength: 35
              description: 'Name by which the organisation is known and which is usually used to identify that organisation'
              example: Stark Industries
            legalForm:
              type: string
              maxLength: 35
              description: 'Legal status of the company'
              example: AG
            LEI:
              type: string
              pattern: '[A-Z0-9]{18,18}[0-9]{2,2}'
              example: 529900UVM8LC55IFAA52
              description: Legal entity identifier
            domicilaryCompany:
              type: boolean
              description: 'Indicates whether the company is a domiciliary company'
              example: FALSE

    personAssociation: # "personAssociation" will be used as disciminator
      allOf:
        - $ref: '#/components/schemas/personDetails'
        - type: object
          required:
            - personAssociationName
          properties:
            personAssociationName:
              type: string
              minLength: 1
              maxLength: 70
              description: 'Name of the association object'
              example: Anthony Stark a/o Piper Potts
            personAssociationType:
              type: string
              enum:
                - compteJoint
                - jointHeirs
                - unregisteredPartnership
                - limitedPartnership
                - collectiveProprietorship
              description: 'Type of association'
              example: compteJoint

    trust: # "trust" will be used as disciminator
      allOf:
        - $ref: '#/components/schemas/personDetails'
        - type: object
          required:
            - trustName
            - trustType
          properties:
            trustName:
              type: string
              minLength: 1
              maxLength: 70
              description: 'Name of the trust object'
              example: Spiderman Trust
            trustType:
              type: string
              enum:
                - simpleTrust
                - complexTrust
                - grantorTrust
              description: 'Type of trust'
              example: simpleTrust

    soleProprietorship: # "soleProprietorship" will be used as disciminator
      allOf:
        - $ref: '#/components/schemas/personDetails'
        - type: object
          required:
            - soleProprietorshipName
          properties:
            soleProprietorshipName:
              type: string
              minLength: 1
              maxLength: 70
              description: 'Name of the sole proprietorship object'
              example: Anthony Stark

    kyc:
      type: object
      properties:
        nonFinancialSituation:
          type: object
          properties:
            profession:
              type: string
              maxLength: 35
              description: 'Name of the occupation or job of the person'
              example: Philantropist
            employingCompany:
              type: string
              maxLength: 35
              description: 'Organisation represented by a person, or for which a person works'
              example: Stark Industries
            educationLevel:
              type: string
              maxLength: 70
              description: 'Highest level of education reached by the individual person'
              example: University
            function:
              type: string
              maxLength: 35
              description: 'Title of the job function'
              example: CEO
            typeOfEmployment:
              type: string
              description: 'Type of employment of the natural person'
              enum: 
              - selfEmployed
              - employed
              - unemployed
              - retired
              example: employed
            riskDomicile:
              $ref: '#/components/schemas/country'
            reasonForDomiciliaryCompany:
              type: string
              maxLength: 35
              description: 'Describes the reason for domiciliary company'
              example: Wealth management
            sector:
              type: string
              maxLength: 70
              description: 'Sector of econimic activity'
              example: Energy supply
            numberOfEmployees:
              type: integer
              description: 'Number of employees'
              example: 250
            dateOfIncorporation:
              $ref: '#/components/schemas/date'
            companyPurpose:
              type: string
              maxLength: 70
              description: 'Describes the purpose of the company'
              example: Provide sustainable energy
            structureControllingPerson:
              type: string
              maxLength: 70
              description: 'Structures of controlling persons'
              example: 'Anthony Stark (75%), Piper Potts (25%)'
            structureBeneficialOwners:
              type: string
              maxLength: 70
              description: 'Structure of beneficial owners'
              example: Anthony Stark (100%)
            reasonForTrust:
              type: string
              maxLength: 70
              description: 'Describes the reason for the trust'
              example: Succession Planning
            revocability:
              type: boolean
              description: 'Indicates wheter the trust is revocable or not'
              example: TRUE
            resettled:
              type: boolean
              description: 'Indicates if the trust is resettled'
              example: FALSE
            merged:
              type: boolean
              description: 'Indicates if the trust is merged'
              example: FALSE
            beneficialOwner:
              type: string
              maxLength: 70
              description: 'Ultimate party that is entitled to either receive the benefits of the ownership of a financial instrument, or to be paid/credited as a result of a transfer'
              example: Max Muster
            beneficiary:
              type: string
              maxLength: 70
              example: Peter Parker
            protector:
              type: string
              maxLength: 70
              description: 'Person appointed under the trust instrument to direct or restrain the trustees in relation to their administration of the trust. Typically, this is a controlling person of a trust.'
              example: Stark Industries
            dateOfTrustContract:
              $ref: '#/components/schemas/date'
        financialSituation:
          type: object
          properties:
            incomeCurrentPeriod:
              type: object
              description: 'Income received in the current income year'
              properties:
                currency:
                  $ref: '#/components/schemas/currency'
                amount:
                  type: string
                  pattern: "[0-9]{1,12}([.][0-9]{1,9})?"
                  maxLength: 22
                  example: "100000"
            sourceOfIncome:
              type: string
              description: 'Specifies the origin of the income'
              enum: 
              - income
              - savings
              - inheritance
              - lifeInsurance
              - pensionFunds
              - gift
              example: income
            annualTurnover:
              type: object
              description: 'Indicates the annual turnover'
              properties:
                currency:
                  $ref: '#/components/schemas/currency'
                amount:
                  type: string
                  pattern: "[0-9]{1,12}([.][0-9]{1,9})?"
                  maxLength: 22
                  example: "200000"
            monetaryWealth:
              type: object
              description: 'Annual wealth of the individual person or share capital value of the legal entity '
              properties:
                currency:
                  $ref: '#/components/schemas/currency'
                amount:
                  type: string
                  pattern: "[0-9]{1,12}([.][0-9]{1,9})?"
                  maxLength: 22
                  example: "1000000"
            sourceOfWealth:
              type: array
              description: Indicates the sources of wealth of the customer.
              items:
                type: object
                properties:
                  sourceOfWealth:
                    type: string
                    description: 'Indicates the type of the sources of wealth'
                    example: inheritance
                    enum: 
                    - retirementPolicy
                    - selfEmploymentIncome
                    - employeeIncome
                    - savings
                    - gift
                    - inheritance
                    - redemtion
                    - winnings
                    - insurancePremiumLiquidation
                    - saleOfGoods
                    - realEstateSale
                    - saleAquisitionCorporation
                    - cashProceeds
                    - alimony
                    - compensation
                    - other
                  currency:
                    $ref: '#/components/schemas/currency'
                  amount:
                    type: string
                    pattern: "[0-9]{1,12}([.][0-9]{1,9})?"
                    maxLength: 22
                    example: "25000000"
                  dateOfReceipt:
                    $ref: '#/components/schemas/date'
                  originator:
                    type: object
                    description: Information about the founder/donor/testator that left the money for the customer.
                    properties:
                      name:
                        type: string
                        maxLength: 70
                        description: Name of the originator, e.g. founder/donor/testator
                        example: Howard Stark
                      relationToCustomer:
                        type: string
                        maxLength: 35
                        description: Relation of the originator to the customer
                        example: Relatives
                      occupation:
                        type: string
                        maxLength: 35
                        description: Describes the (former) occupation of the originator (founder/donor/testator)
                        example: Technology Provider
            priorBank:
              type: object
              properties:
                namePriorBank:
                  type: string
                  maxLength: 70
                domicilePriorBank:
                  $ref: '#/components/schemas/country'

    customerAndKycResponse:
      type: object
      properties:
        customer:
         $ref: '#/components/schemas/customer'
        kyc:
         $ref: '#/components/schemas/kyc'
    
    contactDetails:
      type: object
      required:
        - medium
        - contactContent
      properties:
        contactIdentification:
          type: string
          maxLength: 35
          example: 123987
          readOnly: true
        medium:
          type: string
          description: Medium for contacting the client.
          example: phone
          enum: 
          - email
          - phone
          - fax
          - website
          - socialMediaProfile
        contactMediumType:
          type: string
          description: Specifies the type of contact details
          example: business
          enum: 
          - private
          - business
        contactContent:
          type: string
          minLength: 1
          maxLength: 70
          description: Content of the contact details, e.g. phone number, email-address, Website URL
          example: 0041998887766
        additionalContactInformation:
          type: string
          maxLength: 70
          description: Used for additional information regarding the contact details
          example: Prio 1 Phone Number

    addressNew:
      type: object
      properties:
        addressName:
          type: string
          maxLength: 70
          example: Stark Mansion
          description: 'Name of the address object'
        mailingInstruction:
          type: string
          maxLength: 35
          example: MainDispatch
          description: 'Mailing instruction'
        postalAddress:
          $ref: '#/components/schemas/postalAddress'

    address:
        type: object
        required: 
          - addressIdentification
          - dispatchType
        properties:
          addressIdentification:
            type: number
            example: 12345678
            description: 'Bank ID of the address object'
          addressName:
            type: string
            maxLength: 70
            example: Stark Mansion
            description: 'Name of the address object'
          isDomicile:
              type: boolean
              description: Indicates if this address is the domicile address
              example: TRUE
          isMailingAddress:
              type: boolean
              description: Indicates if this address is used for mailing purposes.
              example: TRUE
          mailingInstruction:
              type: string
              maxLength: 35
              example: MainDispatch
              description: 'Mailing instruction'
          dispatchType:
            type: string
            description: Indicates wether the correspondance is sent out digitally (e.g. to the e-banking) or physically.
            enum: 
            - postal
            - electronical
            - other
          language:
              type: string
              maxLength: 35
              example: German
              description: 'Language for all communication concerning this address'
          postalAddress:
              $ref: '#/components/schemas/postalAddress'

    postalAddress:
        type: object
        required: 
          - salutation
          - isDomicile
          - isMailingAddress
          - postCode
          - townName
          - country
        properties:
            salutation:
              type: object
              properties:
                receptionRestriction:
                    type: string
                    maxLength: 35
                    description: Reception restrictions of physical delivery of mail
                    example: confidential
                salutation:
                    type: string
                    maxLength: 35
                    description: Salutation of the person
                    example: Mr.
                title:
                    type: string
                    maxLength: 35
                    description: Additional information about the person that follows a person's name, for example, qualification such as Doctor of Philosophy (PhD).
                    example: PhD
                overrideSalutation:
                    type: string
                    maxLength: 35
                    example: Dear Ironman
                    description: Used to override the salutations in letters.
            name:
              type: object
              properties:
                organisationName:
                    type: string
                    maxLength: 70
                    description: Name by which the organisation is known and which is usually used to identify that organisation
                    example: Strak Industries
                givenName:
                    type: string
                    maxLength: 35
                    description: First name of the person
                    example: Anthony
                middleName:
                    type: string
                    maxLength: 35
                    description: Second- or middlename of the person
                    example: Edward
                lastName:
                    type: string
                    maxLength: 35
                    description: Last name of the person
                    example: Stark
                nameSuffix:
                    type: string
                    maxLength: 35
                    description: Additional information on a name of the person
                    example: jr.
            physicalAddress:
              type: object
              properties:
                careOf:
                    type: string
                    maxLength: 35
                    description: When the individual resides at another person's address, the name of the other person
                    example: Piper Potts
                toTheAttentionOf:
                    type: string
                    maxLength: 35
                    description: When the mail should be distributed to a specific person within a company
                    example: Jarvis
                streetName:
                    type: string
                    maxLength: 35
                    description: Name of the street or thoroughfare
                    example: Malibu Point
                buildingNumber:
                    type: string
                    maxLength: 35
                    description: Number that identifies the position of the building on a street
                    example: "10880"
                postBox:
                    type: string
                    maxLength: 35
                    description: Post box number of the addressee within the residential or company building
                    example: "12"
                addressSuffix:
                    type: string
                    maxLength: 35
                    description: Additional infromation
                    example: Appartment 1
                postCode:
                    type: string
                    maxLength: 35
                    description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail
                    example: 90265
                townName:
                    type: string
                    maxLength: 35
                    description: Name of the town or city
                    example: Malibu
                countrySubDivision:
                    type: string
                    maxLength: 35
                    description: Identifies a subdivision of a country such as state, region, county
                    example: CA
                country:
                    $ref: '#/components/schemas/country'

    addressIdentificationResponse:
      type: object
      properties:
        addressIdentification:
          type: string
          example: 7353
          description: ID of the newly created address object.
          
    country:
      type: string
      pattern: '[A-Z]{2}'
      example: CH
      description: 2-Letter ISO 3166-2 Country Code  
    
    currency:
      description: ISO 4217 code
      type: string
      pattern: '[A-Z]{3}'
      example: 'CHF'

    date:
      type: string
      format: date
      description: Date according to ISO 8601 i.e. YYYY-MM-DD format
      example: '2018-04-13'

    commonErrorResponse:
      title: Common Error Response
      type: object
      properties:
        type:
          $ref: '#/components/schemas/commonErrorType'
        title:
          type: string
          example:
            This is the general problem description
        detail:
          type: string
          example:
            Detailed problem description with respect to the current request
        instance:
          type: string
          example:
            path/to/corresponding/resource

    commonErrorType:
      type: string
      description: Error types for commonErrorResponse
      example: invalidPayload
      enum:
        - invalidPayload
        - malformedPayload
        - invalidToken
        - expiredToken
        - insufficientPrivileges
        - noAccessToResource
        - resourceDoesNotExist
        - resourceNotReady
        - resourceTooLarge
        - wrongMethod
        - operationNotAllowed
        - technicalError
        - notImplemented
        - serviceUnavailable

# ---- Responses - Standard Errors Common Data Model v1.2.2----
  responses:
    standard400:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard401:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json     
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard403:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Forbidden - The server understood the request but refuses to authorize it. 
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard404:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard405:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard500:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard501:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Not Implemented - The server does not support the functionality required to fulfill the request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard503:
      headers:
        Content-Type:
          schema:
            type: string
            description: 'application/problem+json; charset=utf-8 according to RFC7807'
            example: application/problem+json
        Content-Language:
          schema:
            type: string
            description: 'Response language - always en'
            example: en
        X-Correlation-ID:
          schema:
            type: string
            description: Client defined ID from request to correlates HTTP requests between a client and server.
            example: f058ebd6-02f7-4d3f-942e-904344e8cde5
      description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'
  # ---- End Responses - Standard Errors