openapi: 3.0.0
info:
  title: Jumio Platform API - Credentials
  version: 1.0.2
  description: >-
    The Credentials resources let you upload credentials and execute workflows.
    <br> Note that each Credential request requires a token that you generate
    through an <a href =
    "https://documentation.jumio.ai/docs/developer-resources/API/authorization">Authorization
    call</a> before starting the session. 
servers:
  - url: https://api.amer-1.jumio.ai
    description: Root URL for the US datacenter
  - url: https://api.emea-1.jumio.ai
    description: Root URL for the EU datacenter
  - url: https://api.apac-1.jumio.ai
    description: Root URL for the SGP datacenter
tags:
  - name: Credentials
    description: Manage credentials.
  - name: Workflow Execution
    description: Execute workflow.
  - name: Deletion
    description: Delete sensitive information from workflow records.
paths:
  /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts/{classifier}:
    put:
      summary: Update part of a credential
      description: Updates a specified part of a credential for a given account.
      tags:
        - Credentials
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: OTP token received in response to account create / update.
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique account identifier.
        - name: workflowExecutionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique workflow identifier.
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique identifier for the credential.
        - name: classifier
          in: path
          required: true
          schema:
            type: string
          description: FRONT, BACK, FACE
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    JPEG, PNG (max. size 15 MB and max resolution of 8000 x
                    8000)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete a part from a credential
      description: >-
        Deletes a specified part of a credential for a given
        account.<br><br>IMPORTANT: Deleted data is not retrievable. Contact
        support for more details on data retention configuration options.
      tags:
        - Deletion
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: OTP token returned by account create / update
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique account identifier.
        - name: workflowExecutionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique identifier of a particular instance of workflow execution.
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: >-
              Unique identifier of the credential containing the part to be
              deleted.
        - name: classifier
          in: path
          required: true
          schema:
            type: string
          description: 'Classifier of the part to be deleted.<br> VALUES: FRONT, BACK, FACE'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      summary: Add part to a credential
      description: Adds a part to the specified account credential.
      tags:
        - Credentials
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: OTP token returned by the account create / update request.
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique account identifier.
        - name: workflowExecutionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: >-
              Unique identifier of the workflow associated with the target
              credential.
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique identifier of the credential the part will be added to.
        - name: classifier
          in: path
          required: true
          schema:
            type: string
          description: |-
            The part classifier. <br>VALUES: FRONT, BACK, FACE
            .
          example: BACK
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    JPEG, PNG (max. size 15 MB and max resolution of 8000 x
                    8000. Longest side must be > 300px.)
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts/PREPARED_DATA:
    parameters:
      - name: User-Agent
        in: header
        required: true
        schema:
          type: string
          description: Value for the User-Agent header
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          description: OTP token returned by the account create / update request.
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: bbf3a261-9bf9-400c-b218-cd275596d8d9
          description: Unique account identifier.
      - name: workflowExecutionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: Unique workflow identifier.
      - name: credentialId
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: Unique ID of the credential
    post:
      tags:
        - Credentials
      summary: Upload prepared data
      requestBody:
        $ref: '#/components/schemas/preparedData'
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}/credentials/{credentialId}/parts:
    post:
      summary: Upload a document
      description: Uploads a specified document (image(s)/single pdf).
      tags:
        - Credentials
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: OTP token returned by the account create / update request.
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique account identifier.
        - name: workflowExecutionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique workflow identifier.
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique credential identifier
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: CREATED
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete all pages
      description: >-
        Delete all pages.<br><br>IMPORTANT: Deleted data is not retrievable.
        Contact support for more details on data retention configuration
        options.
      tags:
        - Deletion
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: OTP token returned by the account create / update request.
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique account identifier.
        - name: workflowExecutionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique workflow identifier.
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique credential identifier.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/accounts/{accountId}/workflow-executions/{workflowExecutionId}:
    put:
      summary: Finalize acquisition process
      description: Finalize the acquisition process and start the workflow.
      tags:
        - Workflow Execution
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            description: OTP token which has been received on the account create update
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique account identifier.
        - name: workflowExecutionId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Unique workflow identifier.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    metadataRequest:
      type: object
      properties:
        classifier:
          type: string
          minLength: 1
          maxLength: 100
          description: >-
            Part classifier of the binary to upload (FACE, FRONT, BACK). See the
            <a href =
            "https://documentation.jumio.ai/docs/references/credentials/#id">ID
            page</a> for more information.
          example: FRONT
    response:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the response.
        account:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: |
                ID of the account used for the API call.
              example: bbf3a261-9bf9-400c-b218-cd275596d8d9
        workflowExecution:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: |
                Unique ID of the workflow-execution used for the API call.
        credential:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: |
                Unique ID of the credential used for the API call.
        part:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: |
                Unique ID of the currently uploaded part.
        api:
          $ref: '#/components/schemas/apiActions'
    apiActionsParts:
      type: object
      properties:
        front:
          type: string
          format: uri
          description: >-
            href to manage  <a href =
            "https://documentation.jumio.ai/docs/references/credentials/#id">FRONT</a>
            part for the ID credential.
          example: >-
            https://api.amer-1.jumio.ai/api/v1/accounts/bbf3a261-9bf9-400c-b218-cd275596d8d9/workflow-executions/be493071-3ffe-4c7f-9bb9-8733a614b627/credentials/ff0a45e1-9f85-470e-8cfb-e478ef1a3ff2/parts/FRONT
        back:
          type: string
          format: uri
          description: >-
            href to manage <a href =
            "https://documentation.jumio.ai/docs/references/credentials/#id">BACK</a>
            part for the account credential.
          example: >-
            https://api.amer-1.jumio.ai/api/v1/accounts/bbf3a261-9bf9-400c-b218-cd275596d8d9/workflow-executions/be493071-3ffe-4c7f-9bb9-8733a614b627/credentials/ff0a45e1-9f85-470e-8cfb-e478ef1a3ff2/parts/BACK
        face:
          type: string
          format: uri
          description: href to manage FACE part for the account credential.
          example: >-
            https://api.amer-1.jumio.ai/api/v1/accounts/bbf3a261-9bf9-400c-b218-cd275596d8d9/workflow-executions/be493071-3ffe-4c7f-9bb9-8733a614b627/credentials/ff0a45e1-9f85-470e-8cfb-e478ef1a3ff2/parts/FACE
        facemap:
          type: string
          format: uri
          description: >-
            href to manage <a href =
            "https://documentation.jumio.ai/docs/references/credentials/#facemap">FACEMAP</a>
            part for the account credential.
          example: >-
            https://api.amer-1.jumio.ai/api/v1/accounts/bbf3a261-9bf9-400c-b218-cd275596d8d9/workflow-executions/be493071-3ffe-4c7f-9bb9-8733a614b627/credentials/ff0a45e1-9f85-470e-8cfb-e478ef1a3ff2/parts/FACEMAP
        prepared_data:
          type: string
          format: uri
          description: >-
            href to manage <a href =
            "https://documentation.jumio.ai/docs/references/credentials/#data">PREPARED_DATA</a>
            part for the account credential.
          example: >-
            https://api.amer-1.jumio.ai/api/v1/accounts/bbf3a261-9bf9-400c-b218-cd275596d8d9/workflow-executions/be493071-3ffe-4c7f-9bb9-8733a614b627/credentials/ff0a45e1-9f85-470e-8cfb-e478ef1a3ff2/parts/PREPAREDDATA
      additionalProperties:
        type: string
        format: uri
        description: One-to-one map of URI for each ORIGIN, 1, 2, ...
        example:
          '1': href
          '2': href
    apiActions:
      type: object
      description: Available actions for the API calls.
      properties:
        token:
          type: string
          description: |
            JWT token for current session. 
        parts:
          $ref: '#/components/schemas/apiActionsParts'
        workflowExecution:
          type: string
          format: uri
          description: |
            href to manage the acquisition and workflow processing.
    preparedData:
      type: object
      description: >-
        See the <a href =
        "https://documentation.jumio.ai/docs/references/credentials/#data">Prepared
        Data</a> page for more information.
      properties:
        suffix:
          type: string
          example: Mr, Mrs, Ms
          description: Title for the subject.
        firstName:
          type: string
          description: First name of the subject.
          example: Elroy
        middleName:
          type: string
          description: Middle name of the subject.
          example: Percival
        lastName:
          type: string
          description: Last name of the subject.
          example: Jetson
        sex:
          type: string
          description: Gender of ID subject. M for male and F for female.
          example: M
        dateOfBirth:
          type: string
          format: date
          description: >-
            Date of birth in <a
            href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO
            8601</a> date format.
          example: '2021-12-23'
        socialSecurityNumber:
          type: string
          description: SSN of the subject.
          example: '3387462834'
        nationality:
          description: Nationality of the subject.
          type: string
          example: FRA
        email:
          type: string
          format: email
          description: Primary email address of the subject.
          example: elroy.jetson@spacely.com
        phoneNumber:
          type: string
          description: Primary phone number of the subject.
          example: '2134445678'
        phoneNumber2:
          type: string
          description: Alternate phone number of the subject.
          example: '3109992939'
        personalNumber:
          type: string
          description: Personal identification number of the subject.
        address:
          $ref: '#/components/schemas/address'
        id:
          $ref: '#/components/schemas/idDetails'
        kyc:
          $ref: '#/components/schemas/kycDetails'
        bank:
          $ref: '#/components/schemas/bankDetails'
        business:
          $ref: '#/components/schemas/businessInformation'
    idDetails:
      type: object
      description: >-
        Personal details as they appear on the <a href =
        "https://documentation.jumio.ai/docs/references/credentials/#id">identifying
        document or ID card</a>.
      properties:
        issuingDate:
          type: string
          format: date
          description: >-
            Date identity document was issued in <a
            href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO
            8601</a> date format only.
          example: '2021-12-23'
        expiryDate:
          type: string
          format: date
          description: >-
            Date identity document expired in <a
            href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO
            8601</a> Date format only.
          example: '2021-12-23'
        idNumber:
          type: string
          description: Primary ID number on the identity document.
        type:
          type: string
          description: 'Type of identity document.<br> VALUES: PASSPORT, DRIVING_LICENSE'
          example: PASSPORT
        subType:
          type: string
          description: >-
            Sub-type of identity document.<br>VALUES: TAX_ID, ELECTORAL_ID,
            NATIONAL_ID
          example: TAX_ID
    address:
      type: object
      properties:
        line1:
          type: string
          description: >-
            First line of the address, typically the street address or care-of
            identifier.
        line2:
          type: string
          description: Second line of the address.
        line3:
          type: string
          description: Third line of the address.
        line4:
          type: string
          description: Fourth line of the address.
        line5:
          type: string
          description: Fifth line of the address.
        postalCode:
          type: string
          description: Postal or zip code.
          example: '90275'
        city:
          type: string
          description: City of residence as it appears on the ID.
        subdivision:
          type: string
          description: City subdivision of residence as it appears on the ID.
        country:
          type: string
          description: >-
            Country in ISO-3166-1 Alpha-3 Code or ISO-3166-1 Alpha-2 Code
            format.
    bankDetails:
      type: object
      properties:
        paymentMethod:
          type: string
          description: Payment method type (CC for BIN; EC for bank account).
          enum:
            - EC
            - CC
        binNumber:
          type: string
          description: Bank Identification Number.
        lastDigits:
          type: string
          description: Last digits of credit/debit card.
        accountNumber:
          type: string
          description: Bank account number.
          example: '2738278278'
        routingNumber:
          type: string
          description: Identity number for bank specified account is held in.
          example: '49582934898'
        amount:
          type: number
          format: double
          description: >-
            Numeric transaction amount in the currency specified in the
            'currency' attribute.
        currency:
          type: string
          pattern: ^\w{3}$
          description: Currency Code in ISO 4217 alphabetic format.
          example: USD
        transactionTime:
          type: string
          format: date-time
          description: >-
            Time of transaction in <a
            href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO
            8601</a> format.
          example: '2022-03-22T08:04:36.000Z'
        transactionId:
          type: string
          description: Transaction identifier.
        ipAddress:
          type: string
          format: ip-address
          description: IP address for the transaction in IPv4 format only.
          example: 127.0.8.81
    kycDetails:
      type: object
      properties:
        registrationDate:
          type: string
          format: date
          description: >-
            Registration date of customer for KYC purposes in <a
            href="https://www.iso.org/iso-8601-date-and-time-format.html">ISO
            8601</a> Date format only.
          example: 2021-9-17
        registrationIpAddress:
          type: string
          format: ip-address
          description: >-
            IP address of customer when it was registered for KYC purposes in
            IPv4 format only.
          example: 8.8.8.8
    businessInformation:
      type: object
      properties:
        name:
          type: string
          description: Name of business to search for.
        city:
          type: string
          description: City where business is located.
        address:
          type: string
          description: Business street address.
        state:
          type: string
          description: State where business is located.
          example: California
        country:
          type: string
          description: >-
            Country where business is located. In ISO-3166-1 Alpha-3 Code
            format.
          example: BRA
        registrationNumber:
          type: string
          description: Business registration number.
          example: '060704780'
        searchId:
          type: string
          description: Search ID received from kyb search primitive.
        kybCapabilities:
          type: array
          description: >-
            Array of which KYB <a href =
            "https://documentation.jumio.ai/docs/references/capabilities/">capability</a>
            to run on this business.
          items:
            type: enum
            description: >-
              Value of KYB <a href =
              "https://documentation.jumio.ai/docs/references/capabilities/">capability</a>.
              VALUES: ADVERSE_MEDIA, WEB_MONITORING, CREDIT,
              BUSINESS_COMPLIANCE, LIVE_BUSINESS_IDENTITY, COMPLIANCE_WATCHLIST,
              BUSINESS_IDENTITY_USA
            enum:
              - ADVERSE_MEDIA
              - WEB_MONITORING
              - CREDIT
              - BUSINESS_COMPLIANCE
              - LIVE_BUSINESS_IDENTITY
              - COMPLIANCE_WATCHLIST
              - BUSINESS_IDENTITY_USA
    problem:
      type: object
      description: https://tools.ietf.org/html/rfc7807
      properties:
        type:
          type: string
          format: uri
          description: >
            An absolute URI that identifies the problem type.  When
            dereferenced,

            it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).
          default: about:blank
          example: https://jumio.github.io/problems/constraint-violation
        title:
          type: string
          description: >
            A short, summary of the problem type. Written in english and
            readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable
        status:
          type: integer
          format: int32
          description: >
            The HTTP status code generated by the origin server for this
            occurrence

            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: >
            An absolute URI that identifies the specific occurrence of the
            problem.

            It may or may not yield further information if dereferenced.
  responses:
    BadRequest:
      description: BadRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://jumio.github.io/problems/unauthorized
            title: Bad Request
            status: 400
            detail: Required data is missing or invalid.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://jumio.github.io/problems/unauthorized
            title: Unauthorized
            status: 401
            detail: The provided credentials are invalid
    Forbidden:
      description: unexpected error happened during processing request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://jumio.github.io/problems/forbidden
            title: Forbidden
            status: 403
            detail: >-
              The provided credentials are not allowed to access the request
              resource
    NotFound:
      description: resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/problem'
          example:
            type: https://jumio.github.io/problems/not-found
            title: Not found
            status: 404
            detail: The requested resource could not be found
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []
