openapi: 3.0.3
info:
  title: intermediary fraud checker for multiple telcom
  version: 1.0.0
servers:
- url: http://localhost:8080/v1

paths:
  /verification/match:
    post:
      tags:
        - verification

      summary: corroborate customer data

      operationId: match

      requestBody:
        required: true
        content:
          application/json:

            schema:
              $ref: '#/components/schemas/MatchRequestBody'

            examples:
              MatchRequestBodyExample:
                value:
                  phoneNumber: '+34629255833'
                  idDocument: 66666666q
                  name: Federica Sanchez Arjona
                  giventName: Federica
                  familyName: Sanchez Arjona
                  nameKanaHankaku: federica
                  nameKanaZenkaku: Ｆｅｄｅｒｉｃａ
                  middleNames: Sanchez
                  familyNameAtBirth: YYYY
                  address: Tokyo-to Chiyoda-ku Iidabashi 3-10-10
                  streetName: Nicolas Salmeron
                  streetNumber: 4
                  postalCode: 1028460
                  region: Tokyo
                  locality: ZZZZ
                  country: Japan
                  houseNumberExtension: VVVV
                  birthdate: '1978-08-22'
                  email: abc@example.com
                  gender: male

      responses:

        '200':
          description: OK

          content:
            application/json:

              schema:
                $ref: '#/components/schemas/MatchResponse'
              example:
                Match200Example:
                  value:
                    phoneNumberMatch: true
                    idDocumentMatch: true
                    nameMatch: true
                    giventNameMatch: null
                    familyNameMatch: null
                    nameKanaHankakuMatch: true
                    nameKanaZenkakuMatch: false
                    middleNamesMatch: true
                    familyNameAtBirthMatch: false
                    addressMatch: true
                    streetNameMatch: true
                    streetNumberMatch: true
                    postalCodeMatch: true
                    regionMatch: true
                    localityMatch: null
                    countryMatch: true
                    houseNumberExtensionMatch: null
                    birthdateMatch: false
                    emailMatch: false
                    genderMatch: false


components:

  schemas:

    MatchRequestBody:
      type: object
      required:
        - idDocument
      description: Payload to validate the customer data.

      properties:

        phoneNumber:
          type: string
          example: +34611739296
          pattern: '^[+][0-9]{1,4}?[0-9]{9}$'
          description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.

        idDocument:
          type: string
          example: 32712107J
          description: Id number associated to the id_document. The value may also contain letters.
          required: true

        name:
          type: string
          description: Full name of the customer.

        givenName:
          type: string
          description: First name/given name of the customer. It may include a compound first name or a second/middle name.

        familyName:
          type: string
          description: Surname/family name of the customer. It may include a compound last name or an additional last name.

        nameKanaHankaku:
          type: string
          description: Reading of the full name of the customer in full-width Kana format.

        nameKanaZenkaku:
          type: string
          example: Ｆｅｄｅｒｉｃａ
          description: Reading of the full name of the customer in half-width Kana format.

        middleNames:
          type: string
          description: Middle names of the customer

        familyNameAtBirth:
          type: string
          description: Family name at birth of the customer

        address:
          type: string
          description: Address of the customer

        streetName:
          type: string
          description: Name of the street or other street type. It should not include street type

        streetNumber:
          type: integer
          minimum: 0
          example: 4
          description: Generally a number identifying a specific property on the `street_name`, but it may be a range of numbers (10-12) or include some letter (10b)

        postalCode:
          type: integer
          minimum: 0
          description: Zip code or postal code

        region:
          type: string
          description: Regin/prefecture of the customer's address

        locality:
          type: string
          description: Locality of the customer's address

        country:
          type: string
          description: Country of the customer's address

        houseNumberExtension:
          type: string
          description: House number extension of the customer's address

        birthdate:
          type: string
          pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'
          example: '1978-08-22'
          description: The birthdate of the customer, in ISO 8601 calendar date format.

        email:
          type: string
          pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+[.][a-zA-Z]{2,}$'
          example: abc@example.com
          description: Email address of the customer.

        gender:
          type: string
          example: female
          description: Gender of the customer.

    MatchResponse:
      type: object
      required:
        - idDocument
      properties:

        phoneNumber:
          type: boolean
          nullable: true
          example: true

        idDocument:
          type: boolean
          nullable: true
          example: true

        name:
          type: boolean
          nullable: true
          example: false

        givenName:
          type: boolean
          nullable: true
          example: null

        familyName:
          type: boolean
          nullable: true

        nameKanaHankaku:
          type: boolean
          nullable: true

        nameKanaZenkaku:
          type: boolean
          nullable: true

        middleNames:
          type: boolean
          nullable: true

        familyNameAtBirth:
          type: boolean
          nullable: true

        address:
          type: boolean
          nullable: true

        streetName:
          type: boolean
          nullable: true

        streetNumber:
          type: boolean
          nullable: true

        postalCode:
          type: boolean
          nullable: true

        region:
          type: boolean
          nullable: true

        locality:
          type: boolean
          nullable: true

        country:
          type: boolean
          nullable: true

        houseNumberExtension:
          type: boolean
          nullable: true

        birthdate:
          type: boolean
          nullable: true

        email:
          type: boolean
          nullable: true

        gender:
          type: boolean
          nullable: true

    Error:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description


    ErrorInfo:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: integer
          description: HTTP response status code
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description

  responses:
    Generic400:
      description: Problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 400
            code: INVALID_ARGUMENT
            message: Client specified an invalid argument, request body or query param

    Generic401:
      description: Authentication problem with the client request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 401
            code: UNAUTHENTICATED
            message: Request not authenticated due to missing, invalid, or expired credentials

    Generic403:
      description: Client does not have sufficient permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            PermissionDenied:
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action
            InvalidTokenContext:
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: Phone number cannot be deducted from access token context

    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 404
            code: SIM_SWAP.UNKNOWN_PHONE_NUMBER
            message: SIM Swap can't be checked because the phone number is unknown

    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 409
            code: CONFLICT
            message: Another request is created for the same MSISDN

    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 500
            code: INTERNAL
            message: Server error

    Generic503:
      description: Service unavailable. Typically the server is down
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 503
            code: UNAVAILABLE
            message: Service unavailable

    Generic504:
      description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          example:
            status: 504
            code: TIMEOUT
            message: Request timeout exceeded. Try later