openapi: 3.0.3
info:
  title: Core V2 Audit HostedURL API
  version: 2.0.0
  description: This is the APIs for V2 Core. It allows you to do common operations, such as read audit entries or get workflow lists.
  contact:
    name: FrankieOne
    url: https://www.frankieone.com/
    email: help@frankieone.com
servers:
- url: https://api.uat.frankie.one
security:
- Api-Key: []
tags:
- name: HostedURL
  description: Manage hosted URLs for an individual
paths:
  /v2/individuals/hostedurl:
    post:
      summary: Provide hosted url for a hosted version of onesdk.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IDV-HostedUrl-Request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IDV-HostedUrl-Response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid EntityId:
                  value:
                    errorCode: API-0400,
                    errorMsg: 'Multiple Errors: See Issues list'
                    details:
                    - issue: 'entityId in path must be of type uuid: "test"'
                      issueLocation: VALIDATE-entityId
                    requestId: 01HM5XJ7VASZ3EJMB1VQGTBFJ4
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Invalid authentication:
                  value:
                    errorCode: AUTH-0002,
                    errorMsg: Unauthorized
                    details:
                    - issue: Invalid Authentication provided. Access denied.
                      issueLocation: request
                    requestId: 00000000S6MNG7624K2TDXT1E3
                No Api-Key:
                  value:
                    errorCode: AUTH-0401
                    errorMsg: Unauthorized
                    details:
                    - issue: No api key provided. Access denied.
                      issueLocation: request
                    requestId: 00000001S6MNG7624K2TDXT1E3
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getHostedUrl
      description: Hosted OneSDK URL Generation, used to request a hosted OneSDK URL with entity specific token for a customer to use a hosted OneSDK session to do an action. Examples of actions that may be done is to complete their onboarding process or to re-attempt IDV checks.  If sendSMS is true and a phone number is supplied, an SMS will be sent to the phone number with the generated URL.
      parameters:
      - $ref: '#/components/parameters/Api-Key'
      - $ref: '#/components/parameters/X-Frankie-CustomerID'
      - $ref: '#/components/parameters/X-Frankie-CustomerChildID'
      - $ref: '#/components/parameters/X-Frankie-Channel'
      tags:
      - HostedURL
      security:
      - Api-Key: []
      - jwt:
        - kyc:api
components:
  schemas:
    Error-Base:
      type: object
      properties:
        errorCode:
          type: string
        errorMsg:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
    Request-ID:
      type: string
      example: 01HN9XHZN6MGXM9JXG50K59Q85
      description: The unique request identifier for the API call made.
    Issue:
      type: object
      properties:
        issue:
          type: string
          description: Description of the issue.
        issueLocation:
          type: string
          description: The location or context where the issue was identified.
        issueType:
          type: string
          description: The type or category of the issue.
    IDV-HostedUrl-Response:
      type: object
      description: Onboarding URL Response, contains the url for onboarding as well as the expiry. Each call to this endpoint will generate a new URL with a new expiry.
      properties:
        status:
          type: string
          description: Status of the response for generating the onboarding URL and optionally sending via SMS.
        url:
          type: string
          description: URL to redirect the user to for onboarding, will point to a page where the user can complete their onboarding or IDV check.
        urlExpiry:
          type: string
          format: date-time
          example: '2020-01-01T00:00:00.000Z'
          description: The time at which the provided URL will expire according to configuration. Can not be set longer than 7 days
        requestId:
          $ref: '#/components/schemas/Request-ID'
        entityId:
          $ref: '#/components/schemas/Entity-ID'
    IDV-HostedUrl-Request:
      type: object
      description: Hosted OneSDK URL Request, used to request a hosted OneSDK URL with entity specific token for a customer to use a hosted OneSDK session to do an action. Examples of actions that may be done is to complete their onboarding process or to re-attempt IDV checks.  If sendSMS is true and a phone number is supplied, an SMS will be sent to the phone number with the generated URL.
      properties:
        applicationRef:
          type: string
          description: Reference or name of the application running this IDV check. Specify this if running this check embedded in a application rather than a web page.
        channelRef:
          type: string
          description: channel this application is being submitted through, eg WEB, MOBILE
        consent:
          type: boolean
          description: Has user consented for IDV check. If not supplied or is false, consent will need to be submitted via provider SDK.
        customerRef:
          description: external customer reference for this entity. If supplied and an entity id not, we will search for an entity with this customer ref. If not found, a new entity will be created with this customer ref.
          type: string
        entityId:
          type: string
          description: Unique FrankieOne identifier for an entity if already created
        errorRedirectURL:
          description: if provider sdk fails, redirect to this url
          type: string
        oneSDKFlowId:
          type: string
          description: Flow id to use for OneSDK, to determine what data needs to be captured from the user, for example :"idv" or "ocr_only"
        phoneCode:
          description: country phone code
          type: string
        phoneNumber:
          description: phone code can be included with phone number or split out
          example: '+6140000000'
          type: string
        recipientName:
          description: if supplied will be used as the recipient name for the SMS
          type: string
        sendSMS:
          description: if true, will send an SMS to the phone number supplied
          type: boolean
        successRedirectURL:
          description: url to redirect to on success
          type: string
        comment:
          $ref: '#/components/schemas/Comment'
    Error:
      type: object
      x-examples:
        '400':
          requestId: 0123456789ABCDEFGHIJKLMNOP
          errorCode: API-0400
          errorMsg: Parsing credentials from "<invalid>" failed, because invalid.
          httpStatusCode: 400
        '401':
          requestId: 0123456789ABCDEFGHIJKLMNOP
          errorCode: API-0401
          errorMsg: Unauthenticated due to invalid credentials.
          httpStatusCode: 401
        '409':
          requestId: 0123456789ABCDEFGHIJKLMNOP
          errorCode: API-0409
          errorMsg: Conflict.
          httpStatusCode: 409
      allOf:
      - $ref: '#/components/schemas/Error-Base'
      - type: object
        properties:
          requestId:
            $ref: '#/components/schemas/Request-ID'
    Comment:
      type: object
      properties:
        commentId:
          type: string
          description: Unique identifier for the comment.
          example: 55fc5d54-46f7-49c8-bf78-e07ec79cd6e7
          readOnly: true
        text:
          type: string
          description: The text content of the comment.
          example: Update after speaking to customer over the phone directly.
    Entity-ID:
      type: string
      description: 'Entities are assigned an auto-generated UUID to ensure global uniqueness, represented as entityId. The entityId allows for precise modification when required.

        To modify an entity, set the entityId of the entity you wish to update in an update request.'
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      readOnly: true
  parameters:
    X-Frankie-Channel:
      name: X-Frankie-Channel
      in: header
      required: false
      schema:
        type: string
      description: 'Open string that can be used to define the "channel" the request comes in from. It can potentially be used in routing and risk calculations upon request. Default values that can be used are:  api portal smartui Any alphanumeric string is supported though. Anything over 64 characters will be truncated.'
    Api-Key:
      name: api_key
      in: header
      schema:
        type: string
        example: 245c765b124a098d09ef8765....
      description: Your API key provided by FrankieOne
      required: true
    X-Frankie-CustomerID:
      name: X-Frankie-CustomerID
      in: header
      required: true
      schema:
        type: string
        example: 12345678-1234-1234-1234-123456789012
      description: Your Customer ID provided by FrankieOne
    X-Frankie-CustomerChildID:
      name: X-Frankie-CustomerChildID
      in: header
      required: false
      schema:
        type: string
        example: 87654321-4321-4321-4321-210987654321
      description: Your Customer Child ID provided by FrankieOne
  securitySchemes:
    Api-Key:
      type: apiKey
      in: header
      name: api_key
      description: ''
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT