portalAPI.yaml

openapi: "3.0.0"
info:
  version: "1"
  title: Worbli API
  description: Worbli Portal API
  termsOfService: http://worbli.io/terms/
  contact:
    name: Worbli API Team
    email: info@worbli.io
    url: http://worbli.io
  license:
    name: Apache 2.0
    url: https://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/B289/API/1
  - url: '{Protocol}://{Environment}/api/{Version}'
    variables:
      Protocol:
        enum:
          - http
          - https
        default: https
      Environment:
          enum:
            - dev-api.worbli.io
            - uat-api.worbli.io
            - localhost:9000
          default: dev-api.worbli.io
      Version:
          enum:
            - v1
            - v2
            - v3
          default: v3
paths:
  /visitor/signin:
    post:
      tags:
        - Visitors
      requestBody:
        description: Login credentials
        required: true
        content:
          application/json:
            schema:
              required:
                - email
                - password
              properties:
                email: 
                  type: string
                password:
                  type: string
            example:
              email: test@worbli.io
              password: password1234!

      responses:
        '200':
          description: login success
          content:
            application/json:
              schema:
                required:
                  - data
                  - jwt
                  - worbliAccountName
                properties:
                  data: 
                    type: boolean
                  jwt:
                    type: string
                  worbliAccountName:
                    type: string
              example:
                data: true
                jwt: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                worbliAccountName: myWorbliNetworkName
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - status
                  - statusText
                  - errors
                properties:
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                status: 400
                statusText: "Bad Request"
                errors: [{"field":["email"],"location":"body","messages":["\"email\" must be a valid email"],"types":["string.email"]}]
        '409':
          description: user not verified
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: "Please verify your email first"
        '401':
          description: login failed
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: "Authentication error!"
  /visitor/join:
    post:
      tags:
        - Visitors
      requestBody:
        description: Join credentials
        required: true
        content:
          application/json:
            schema:
              required:
                - email
                - password
                - terms
              properties:
                email: 
                  type: string
                password:
                  type: string
                terms:
                  type: boolean
                marketing:
                  type: boolean
            example:
              email: test@worbli.io
              password: password1234!
              terms: true
              marketing: false
      responses:
        '200':
          description: join successful
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: "Bad Request"
                errors: [{"field":["agreedTerms"],"location":"body","messages":["\"agreedTerms\" must be one of [true]"],"types":["any.allowOnly"]}]
        '409':
          description: user joined but not verified
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: "You have already created your account - check your mailbox for activation instructions."
        '412':
          description: user already joined and verified
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: "You have already created your account."
        '500':
          description: internal server failure
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Failed to send a verify email to test@worbli.io
  /visitor/forgot:
    post:
      tags:
        - Visitors
      requestBody:
        description: Visitor forgot password
        required: true
        content:
          application/json:
            schema:
              required:
                - email
              properties:
                email: 
                  type: string
            example:
              email: test@worbli.io
      responses:
        '200':
          description: password reset process initiated
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: [{"field":["agreedTerms"],"location":"body","messages":["\"agreedTerms\" must be one of [true]"],"types":["any.allowOnly"]}]
        '500':
          description: internal server failure
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Failed to send a password reset email to test@worbli.io
  /user/password:
    put:
      tags:
        - User
      requestBody:
        description: User resets the password
        required: true
        content:
          application/json:
            schema:
              required:
                - password
                - token
              properties:
                password: 
                  type: string
                token:
                  type: string
            example:
              password: password1234!
              token: cc2b039697793f4f38aa908f07fd2974
      responses:
        '200':
          description: password successfully changed response
          content:
            application/json:
              schema:
                required:
                  - data
                  - token
                properties:
                  data: 
                    type: boolean
                  token:
                    type: string
              example:
                data: true
                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["token"],"location":"body","messages":["Invalid token"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong token provided)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Wrong token provided
        '500':
          description: internal server failure
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Internal error, please try again later
  /user/profile/{id}:
    get:
      tags:
        - User
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
        - in: path
          name: id
          description: The ID of the user for whom to retrieve the profile
          schema:
            type: string
          example:
            id: 443z43jkgvgl670
          required: true

      responses:
        '200':
          description: Profile retrieved successfully
          content:
            application/json:
              schema:
                required:
                  - email
                properties:
                  email: 
                    type: string
              example:
                email: test@worbli.io

        '400':
          description: request failed
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false
  /user/profile:
    post:
      tags:
        - User
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      requestBody:
        description: User saves their profile
        required: true
        content:
          application/json:
            schema:
              required:
                - password
                - newPassword
              properties:
                email: 
                  type: string
                password:
                  type: string
                newPassword:
                  type: boolean
            example:
              email: test@worbli.io
              password: password1234!
              newPassword: newPassword1234!

      responses:
        '200':
          description: Profile saved successfully
          content:
            application/json:
              schema:
                required:
                  - data
                  - jwt
                properties:
                  data: 
                    type: boolean
                  jwt:
                    type: string
              example:
                data: true
                jwt: veklhr93849f033ff.ggo39ut3to9bjh389g3.gg095ug90vv390f
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["password"],"location":"body","messages":["\"password\" is required"],"types":["any.required"]}]}
        '409':
          description: user not verified
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: "Please verify your email first"
  /user/state:
    post:
      summary: User gets the state of their KYC application
      tags:
        - User
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true

      responses:
        '200':
          description: Profile saved successfully
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - errored
                  - worbliAccountName
                properties:
                  data: 
                    type: boolean
                  status:
                    type: string
                  errored:
                    type: boolean
                  worbliAccountName:
                    type: string
              example:
                data: true
                status: pending
                errored: false
                worbliAccountName: myWorbliNetworkName
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["authorization"],"location":"headers","messages":["Invalid token"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong credentials)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: "Authentication failed: credentials wrong or missing."
  /user/verify:
    post:
      tags:
        - User
      requestBody:
        description: Visitor verifies email address
        required: true
        content:
          application/json:
            schema:
              required:
                - email
                - token
              properties:
                email: 
                  type: string
                token:
                  type: string
            example:
              email: test@worbli.io
              token: cc2b039697793f4f38aa908f07fd2974

      responses:
        '200':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                  - token
                properties:
                  data: 
                    type: boolean
                  token:
                    type: string
              example:
                data: true
                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        '400':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false
  /user/resendverify:
    post:
      tags:
        - User
      requestBody:
        description: Resends the verification email
        required: true
        content:
          application/json:
            schema:
              required:
                - email
              properties:
                email: 
                  type: string
            example:
              email: test@worbli.io
      responses:
        '200':
          description: verify email sent
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
                  token:
                    type: string
              example:
                data: true
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"email\" is required"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong email provided)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Please check the email address
        '412':
          description: email address already verified
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: The email address has already been verified
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: An internal error has occurred. Please try again later.
  /identity/image:
    post:
      summary: Accepts the user's verification images
      tags:
        - Identity
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      requestBody:
        required: true
        description: Contains the files to be uploadded
        content:
          application/json:
            schema:
              required:
                - file1
              properties:
                file1: 
                  type: object
            example:
              file1: some file
      responses:
        '200':
          description: file uploaded successfully
          content:
            application/json:
              schema:
                required:
                  - data
                  - completed
                  - missingDocuments
                  - rejectedDocuments
                properties:
                  data: 
                    type: boolean
                  completed:
                    type: boolean
                  missingDocuments:
                    type: array
                  rejectedDocuments:
                    type: array
              example:
                data: true
                completed: false
                missingDocuments: ['identity']
                rejectedDocuments: ['selfie']
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong token provided)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Authentication failed: credentials wrong or missing.'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false
    delete:
      summary: Deletes an uploaded image
      tags:
        - Identity
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
        - in: path
          name: doctype
          description: The document type to be deleted, as in /identity/image/{US_passport}
          schema:
            type: string
          example:
            /identity/image/{US_passport}
          required: true
      responses:
        '200':
          description: The document was successfully deleted
          content:
            application/json:
              schema:
                required:
                  - data
                  - completed
                  - missingDocuments
                properties:
                  data: 
                    type: boolean
                  completed:
                    type: boolean
                  missingDocuments:
                    type: array
              example:
                data: true
                completed: false
                missingDocuments: ['identity']
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong token provided)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Authentication failed: credentials wrong or missing.'
  /identity/identityimages:
    delete:
      summary: Deletes the uploaded identity images
      tags:
        - Identity
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      responses:
        '200':
          description: The document was successfully deleted
          content:
            application/json:
              schema:
                required:
                  - data
                  - completed
                  - missingDocuments
                properties:
                  data: 
                    type: boolean
                  completed:
                    type: boolean
                  missingDocuments:
                    type: array
              example:
                data: true
                completed: false
                missingDocuments: ['identity']
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong token provided)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Authentication failed: credentials wrong or missing.'
  /identity/missingimages:
    post:
      summary: Checks the completeness of the user's verification process
      tags:
        - Identity
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      requestBody:
        required: true
        description: Contains the files to be uploaded
        content:
          application/json:
            schema:
              required:
                - file1
              properties:
                file1: 
                  type: object
            example:
              file1: some file
      responses:
        '200':
          description: The check was successful
          content:
            application/json:
              schema:
                required:
                  - data
                  - completed
                  - missingDocuments
                properties:
                  data: 
                    type: boolean
                  completed:
                    type: boolean
                  missingDocuments:
                    type: array
              example:
                data: true
                completed: false
                missingDocuments: ['identity']
        '400':
          description: bad request
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '401':
          description: unauthorized request (wrong token provided)
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Authentication failed: credentials wrong or missing.'
  /identity/application:
    # todo: add json in requestBody
    post:
      tags:
        - Identity
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true

      responses:
        '200':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true

        '400':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false
  /identity/documents:
    # todo: add country paremeter in header
    get:
      tags:
        - Identity
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true

      responses:
        '200':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true

        '400':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false
  /network/account:
    post:
      summary: Reserves a network name for the user and starts the approval process
      tags:
        - Network
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      requestBody:
        description: Resends the verification email
        required: true
        content:
          application/json:
            schema:
              required:
                - accountName
                - publicKeyActive
                - publicKeyOwner
              properties:
                accountName: 
                  type: string
                publicKeyActive:
                  type: string
                publicKeyOwner:
                  type: string
            example:
              accountName: myFunkyName
              publicKeyActive: lifrxwiefmowe
              publicKeyOwner: erlijxfeiowrrxw
      responses:
        '200':
          description: Network account name reserved, approval process started
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: true

        '400':
          description: The account name is occupied or the user is not yet KYCed
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: The requested account name is not available. Please choose another one.
        '500':
          description: Internal server error - the user must retry the operation at a later time
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Creating the network account failed, please try again later
  /network/check/{accountName}:
    get:
      summary: Checks whether the network name is available
      tags:
        - Network
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
        - in: path
          name: accountName
          schema:
            type: string
          required: true
          description: The network name to be checked
          example:
            email: myFunkyName
      responses:
        '200':
          description: The check succeeded - the 'data' property specifies if the name was found
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data: 
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: Internal error, please try again later
  /mobile/sms:
    post:
      summary: Sends an SMS to a mobile number
      tags:
        - Mobile
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      requestBody:
        description: contains the number to send to
        required: true
        content:
          application/json:
            schema:
              required:
                - number
              properties:
                number: 
                  type: string
            example:
              number: '+15551234567'
      responses:
        '200':
          description: SMS successfully sent
          content:
            application/json:
              schema:
                required:
                  - data
                  - shortcode
                properties:
                  data: 
                    type: boolean
                  shortcode:
                    type: integer
              example:
                data: true
                shortcode: 123456
        '400':
          description: bad request - input data missing
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["token"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '500':
          description: One of the internal services failed
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data:
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Failed to send out the SMS, please try again later'
  /mobile/files:
    post:
      summary: Requests files from a mobile device
      tags:
        - Mobile
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      requestBody:
        description: contains the documents to upload and the country
        required: true
        content:
          application/json:
            schema:
              required:
                - country
                - fields
              properties:
                country:
                  type: string
                fields:
                  type: array
            example:
              country: GBR
              fields: ['drivers_licence', 'selfie']
      responses:
        '200':
          description: data successfully received
          content:
            application/json:
              schema:
                required:
                  - data
                  - shortcode
                properties:
                  data: 
                    type: boolean
                  shortcode:
                    type: integer
              example:
                data: true
                shortcode: 123456
        '400':
          description: bad request - input data missing
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '500':
          description: One of the internal services failed
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data:
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Failed to send out the SMS, please try again later'
  /mobile/shortcode:
    get:
      summary: Obtains a short code
      tags:
        - Mobile
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true
      responses:
        '200':
          description: get shortcode
          content:
            application/json:
              schema:
                required:
                  - data
                  - shortcode
                properties:
                  data: 
                    type: boolean
                  shortcode:
                    type: integer
              example:
                data: true
                shortcode: 123456
        '400':
          description: bad request - input data missing
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["email"],"location":"body","messages":["\"token\" is required"],"types":["any.required"]}]}
        '500':
          description: One of the internal services failed
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data:
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Failed to generate the short code, please try again later'
    post:
      summary: Authenticates with a short code
      tags:
        - Mobile
      requestBody:
        description: Contains the shortcode
        required: true
        content:
          application/json:
            schema:
              required:
                - shortcode
              properties:
                shortcode: 
                  type: integer
                country:
                  type: string
                fields:
                  type: array
            example:
              shortcode: 123456
              country: GBR
              fields: ['drivers_licence', 'selfie']
      responses:
        '200':
          description: Successful authentication
          content:
            application/json:
              schema:
                required:
                  - data
                  - jwt
                  - country
                  - files
                properties:
                  data: 
                    type: boolean
                  jwt:
                    type: string
                  country:
                    type: string
                  files:
                    type: string
              example:
                data: true
                jwt: veklhr93849f033ff.ggo39ut3to9bjh389g3.gg095ug90vv390f
                country: GBR
                files: '[{"value":"national_identity_card_reverse","label":"national identity card reverse","uploaded":true, "deviceId": "123456"}]'
        '400':
          description: bad request - input data missing or invalid
          content:
            application/json:
              schema:
                required:
                  - data
                  - status
                  - statusText
                  - errors
                properties:
                  data: 
                    type: boolean
                  status:
                    type: integer
                  statusText:
                    type: string
                  errors:
                    type: array
              example:
                data: false
                status: 400
                statusText: Bad Request
                errors: {"status":400,"statusText":"Bad Request","errors":[{"field":["shortcode"],"location":"body","messages":["\"shortcode\" is required"],"types":["any.required"]}]}
        '500':
          description: One of the internal services failed
          content:
            application/json:
              schema:
                required:
                  - data
                  - error
                properties:
                  data:
                    type: boolean
                  error:
                    type: string
              example:
                data: false
                error: 'Failed to authenticate the short code, please try again later'
  /health/ready:
    get:
      tags:
        - Health
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true

      responses:
        '200':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true

        '400':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false
  /health/live:
    # todo: fix this up
    get:
      tags:
        - Health
      parameters:
        - in: header
          name: Authorization
          description: Bearer jwtToken
          schema:
            type: string
          example:
            Authorization: Bearer jwttoken.sdfsdf.sdfsdf
          required: true

      responses:
        '200':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: true

        '400':
          description: verify email response
          content:
            application/json:
              schema:
                required:
                  - data
                properties:
                  data: 
                    type: boolean
              example:
                data: false