---
swagger: "2.0"
info:
  title: User verification API
  description: "API used to verify a user."
  version: "0.1"
host: api.chenosis.io
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: "https://staging.api.chenosis.io/client-credentials/accesstoken?grant_type=client_credentials"
    scopes:
      CREATE-VERIFICATION: Grants access to send a verification to an end-user.
security:
  - OAuth2: []
paths:
  /v1/identity/verification:
    post:
      tags:
          - "Verifications"
      summary: "This operation is used to send a verification to the end-user"
      description: "This interface is used to send a verification to the end-user by specifying the communication details of the end-ser."
      parameters:
      - in: "body"
        name: "body"
        description: "Request body"
        required: true
        schema:
          $ref: "#/definitions/Verification"
      responses:
        201:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/verificationResponse"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error500"
          description: "Internal Server Error"
  
  /v1/identity/verification/{verificationId}:
    get:
      tags:
          - "Verifications"
      summary: "Get verification"
      description: "This interface is used to get the verification status of a verification that was previosly sent using the 'verificationId' to identify it.Please note that if the verification is 'approved', it will not be possible to get the status of the verification."
      parameters:
      - name: verificationId
        in: path
        description: "Unique identifier for the verification"
        required: true
        type: string
        x-example: "VEcc998fb320f254b00efaba9ddb0a533b"
      responses:
        200:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/verificationResponse"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error500"
          description: "Internal Server Error"
    
    patch:
      tags:
          - "Verifications"
      summary: "Verify a verification"
      description: "This interface is used to verify a verification that was previosly sent. The 'code' is sent in order to verify that the correct user received the code. Please note that if the verification is 'approved', it will not be possible to get the status of the verification. The response in this request will be the only time the 'status' will be returned as 'approved' if the code is correct."
      parameters:
      - name: verificationId
        in: path
        description: "Unique identifier for the verification"
        required: true
        type: string
        x-example: "VEcc998fb320f254b00efaba9ddb0a533b"
      - in: "body"
        name: "body"
        description: "Request body"
        required: true
        schema:
          $ref: "#/definitions/VerifyVerification"
      responses:
        200:
          description: "Outbound SMS created"
          schema:
            $ref: "#/definitions/verificationResponse"
        401:
          schema:
            $ref: "#/definitions/Error"
          description: "Not authenticated"
        404:
          schema:
            $ref: "#/definitions/Error"
          description: "Not found"
        407:
          schema:
            $ref: "#/definitions/Error"
          description: "Proxy system not authenticated"
        500:
          schema:
            $ref: "#/definitions/Error500"
          description: "Internal Server Error"

definitions:
  Verification:
    type: object
    required:
      - to
      - channel
    properties:
      to:
        type: string
        description: "Address of the end-user. If the 'channel' used is 'sms' or 'call' the value is the MSISDN/phone number of the end-user represented as International  ITU-T E.164. If the 'channel' is email, the value would be the email address of the end-user."
        example: "27123456789"
      channel:
        $ref: "#/definitions/Channel"
      locale:
        $ref: "#/definitions/Locale"
  
  Status:
    type: "string"
    title: "Verification status"
    description: "This field is used to indicate the verification status of the verification created.\n The value 'pending' means the verification code has been sent and has not been verified by the end-user.\n The value 'approved' means the end-user has verified that they have received the code and it was verified.\n The value 'expired' means the verification was sent and has expired because ten (10) minutes has elapsed since the verification was sent to the end-user, at this state, this verification cannot be verified and another verification has to be sent. Please note that this value may not be returned and rather an error will be returned stating that the verification does not exist anymore as it gets removed for verification after ten (10) minutes.\n The value 'cancelled' means the verification has been cancelled by the initiator and cannot be verified, this can also prompt an error that the verification does not exist anymore."
    example: "pending"
    enum:
      - "approved"
      - "pending"
      - "expired"
      - "cancelled"
      
  Channel:
    type: "string"
    title: "Verification Channel"
    description: "This field is used to set/indicate the channel used to send the verification code to the end-user.\n The value 'sms' means the verification is sent to the user using an SMS message.\n The value 'call' means the verification is sent to the user via a phone call made to the end-ser.\n The value 'email' means the verification is sent to the user using an email message."
    example: "sms"
    enum:
      - "sms"
      - "call"
      - "email"
      
  Locale:
    type: "string"
    title: "Language used to send the verification message"
    description: "This field is used to set/indicate the the language/locale used when sending the verification code to the end-user. Default is English (en)"
    example: "en"
    enum:
      - "af"
      - "ar"
      - "ca"
      - "cs"
      - "da"
      - "de"
      - "el"
      - "en"
      - "en-GB"
      - "es"
      - "fi"
      - "fr"
      - "he"
      - "hi"
      - "hr"
      - "hu"
      - "id"
      - "it"
      - "ja"
      - "ko"
      - "ms"
      - "nb"
      - "nl"
      - "pl"
      - "pt"
      - "pr-BR"
      - "ro"
      - "ru"
      - "sv"
      - "th"
      - "tl"
      - "tr"
      - "vi"
      - "zh"
      - "zh-CN"
      - "zh-HK"

  VerifyVerification:
    type: object
    title: "Verify a verification"
    required:
      - code
    properties:
      code:
        type: string
        description: "This is the verification code that was sent to the end-user."
        example: "123456"
        
  verificationResponse:
    type: object
    required:
      - statusCode
      - statusMessage
      - data
      - transactionId
    properties:
      statusCode:
        type: string
        description: "HTTP error code extension"
        example: "0000"
      statusMessage:
        type: string
        description: Message.
        example: "Successful"
      data:
        $ref: "#/definitions/verificationData"
      transactionId:
        type: string
        description: "transaction ID for tracing."
        example: "fdsf4545-sdfd5-sds"

  verificationData:
    type: object
    required:
      - to
      - channel
      - verificationId
      - status
    properties:
      to:
        type: string
        description: "Address of the end-user. If the 'channel' used is 'sms' or 'call' the value is the MSISDN/phone number of the end-user represented as International  ITU-T E.164. If the 'channel' is email, the value would be the email address of the end-user."
        example: "27123456789"
      channel:
        $ref: "#/definitions/Channel"
      verificationId:
        type: string
        description: "Unique identifier for the verification, this value will be used to query the status of the verification."
      status:
        $ref: "#/definitions/Status"

  Error:
    type: object
    properties:
      statusCode:
        type: string
        description: "HTTP error code extension"
      statusMessage:
        type: string
        description: "More details and corrective actions related to the error which can be shown to a client."
      SupportMessage:
        type: string
        description: "Support Message"
        
  Error500:
    type: object
    properties:
      timestamp:
        type: string
        description: "Timestamp"
        example: "2020-10-14T22:57:24.519+0000"
      status:
        type: string
        description: "HTTP error code extension"
        example: "500"
      error:
        type: string
        description: "Support Message"
        example: "Internal Server Error"
      message:
        type: string
        description: "Support Message"
        example: "value"
      path:
        type: string
        description: "Path accessed"
        example: "/v1/identity/verification"