openapi: 3.0.0
info:
  title: Jumio Platform API - Accounts
  version: 1.0.0
  description: >-
    Create a new account to onboard new end-users, or Update an existing account
    for returning end users. <br> <br>All other transactions in a given user
    journey are tied to the Account ID, so always start each customer journey
    with the appropriate account request.
  x-keywords:
    - Jumio
    - API
    - REST
    - Account API
    - Account management
    - Onboarding
    - Identity verification
    - Account creation
    - Account update
servers:
  - url: https://account.amer-1.jumio.ai
    description: Root URL for the US datacenter.
  - url: https://account.emea-1.jumio.ai
    description: Root URL for the EU datacenter.
  - url: https://account.apac-1.jumio.ai
    description: Root URL for the SGP datacenter.
tags:
  - name: Account
    description: Create and update end-user accounts.
paths:
  /api/v1/accounts:
    post:
      summary: Account Creation
      description: >-
        Creates a new account. Do this first when onboarding a new customer.
        <br>Use Account update for changes to existing accounts. <br><br>
        Related guide: <a href =
        "/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts">Account
        Creation and Updates</a> 
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
      tags:
        - Account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/accountRequest'
      responses:
        '201':
          description: Created Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/accounts/{accountId}:
    put:
      summary: Account Update
      description: >-

        Update an existing account.  <br><br> Related guide: <a href =
        "/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts">Account
        Creation and Updates</a> 
      tags:
        - Account
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
            description: Value for the User-Agent header
        - name: accountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: bbf3a261-9bf9-400c-b218-cd275596d8d9
            description: Unique Account Identifier.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/accountRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    predefinedType:
      type: string
      default: DEFINED
      description: >

        Used to specify a set of values for the <a href =
        "/docs/references/credentials/">credentials</a> that can be uploaded for
        the workflow:<br>  - DEFINED: End user is not able to select other
        options even if they are defined in the KYX Portal. 
    credentialCountry:
      type: object
      description: |2

         One or more Country Codes <a href="https://www.iban.com/country-codes">(ISO 3166-1 alpha-3)</a> for the workflow definition.
      properties:
        predefinedType:
          $ref: '#/components/schemas/predefinedType'
        values:
          type: array
          items:
            $ref: '#/components/schemas/countryCodeISO3166alpha3'
          example:
            - AUT
          description: Array of Country Codes.
      required:
        - values
    credentialType:
      type: object
      properties:
        predefinedType:
          $ref: '#/components/schemas/predefinedType'
        values:
          type: array
          items:
            type: string
          example:
            - DRIVING_LICENSE
          description: Array of Credential Codes.
      description: >

        Array of Credential Codes. You can find more information about possible
        values for particular <a
        href="https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#credentials">
        Credential categories </a> in the implementation guide.
      required:
        - values
    workflowDefinition:
      type: object
      properties:
        key:
          type: string
          minLength: 1
          maxLength: 100
          example: '10163'
          description: >
            Key of the <a
            href="https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#workflowdefinition">
            Account Creation and Updates</a> workflow definition.
        credentials:
          type: array
          definition: >-
            An array of the <a href =
            "/docs/references/credentials/">credentials</a> required for the
            workflow.
          items:
            $ref: '#/components/schemas/credentialRequest'
        capabilities:
          description: >

            The <a
            href="https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#capabilities">capabilities</a>
            to use in workflow execution.
          $ref: '#/components/schemas/capabilityOptions'
      required:
        - key
      description: >

        Definition of the specific documents necessary to execute for the
        particular capabilities on them.
    credentialRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
        category:
          $ref: '#/components/schemas/credentialCategory'
        country:
          $ref: '#/components/schemas/credentialCountry'
        type:
          $ref: '#/components/schemas/credentialType'
      required:
        - category
      description: >-
        Optional. <a href =
        "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#credentials">Credentials</a>
        required in the workflow.
    accountRequest:
      type: object
      properties:
        userReference:
          type: string
          minLength: 1
          maxLength: 100
          description: >
            Internal ID used by the customer for the end user (must not contain
            PII). <br> See also <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#optional-fields">Optional
            fields.</a>
        customerInternalReference:
          type: string
          minLength: 1
          maxLength: 100
          description: >

            Internal reference used in the customer backend to identify the
            request (must not contain PII).<br>Must not contain any of the
            following characters: <>"/;`%{}|
        reportingCriteria:
          type: string
          minLength: 1
          maxLength: 255
          description: >

            Additional information provided by the customer for searching and
            aggregation purposes.  <br> See also <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#optional-fields">Optional
            fields.</a>  
        callbackUrl:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            URL to override the default callback url for this particular
            request. <br> See also <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#optional-fields">Optional
            fields.</a> 
          example: https://mypreferredendpoint.com/callback
        tokenLifetime:
          type: string
          pattern: ^([+-]?\d+)([smhd]{1})$
          description: >-
            Override the default token lifespan with another duration (example
            '1d' or '30m' or '600s'):

            - s - seconds

            - m - minutes

            - h - hours

            - d - days

            <br> See also <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#optional-fields">Optional
            Fields.</a>
          example: 15m
        web:
          description: >-
            Used to override default values that are configured in the Portal.
            Only relevant for the WEB channel.
          $ref: '#/components/schemas/webSettings'
        workflowDefinition:
          description: >

            <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#workflowdefinition">Workflow
            definition</a> object.
          $ref: '#/components/schemas/workflowDefinition'
        userConsent:
          description: >-
            <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#userconsent">User
            Consent</a> is needed for services that use facial recognition
            technology or process biometric datail. 
          $ref: '#/components/schemas/userConsent'
        overrideSettings:
          type: object
          description: Allows overriding certain settings for the workflow execution.
          additionalProperties:
            type: string
      required:
        - customerInternalReference
        - workflowDefinition
    accountResponse:
      type: object
      description: >-
        The <a href =
        "/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#account-responses">response</a>
        contains data for use in subsequent transaction requests.
      properties:
        timestamp:
          type: string
          format: date-time
          description: |
            Timestamp of response.
        account:
          type: object
          properties:
            id:
              type: string
              format: uuid
        web:
          type: object
          properties:
            href:
              type: string
              format: uri
            successUrl:
              type: string
              format: uri
            errorUrl:
              type: string
              format: uri
        sdk:
          type: object
          properties:
            token:
              type: string
        workflowExecution:
          type: object
          properties:
            id:
              type: string
              format: uuid
            credentials:
              type: array
              description: >-
                Array of <a href =
                "/docs/references/credentials/">Credential</a> response
                objects. 
              items:
                $ref: '#/components/schemas/credentialResponse'
    credentialResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        label:
          type: string
          description: >-
            A label provided by the workflow designer to distinguish credentials
            of the same category.
        category:
          $ref: '#/components/schemas/credentialCategory'
        country:
          $ref: '#/components/schemas/credentialCountry'
        type:
          $ref: '#/components/schemas/credentialType'
        allowedChannels:
          type: array
          items:
            type: string
          description: >-
            Channels that can be used to upload a particular <a href =
            "/docs/references/credentials/">Credential</a> (SDK, API, WEB). 
        api:
          $ref: '#/components/schemas/apiActions'
    apiActions:
      type: object
      description: |

        Actions available for the API calls. Unavailable actions are omitted. 
      properties:
        token:
          type: string
          description: |

            JWT token used for all requests. 
        parts:
          type: object
          description: |

            'Parts' refers to distinct types of identifying materials. 
          properties:
            front:
              type: string
              format: uri
              description: |
                href to manage FRONT part for the account credential. 
            back:
              type: string
              format: uri
              description: |
                href to manage BACK part for the account credential. 
            face:
              type: string
              format: uri
              description: |
                href to manage FACE part for the account credential. 
            facemap:
              type: string
              format: uri
              description: |
                href to manage FACEMAP part for the account credential. 
            prepared_data:
              type: string
              format: uri
              description: |
                href to manage PREPARED_DATA part for the account credential. 
            device_risk:
              type: string
              format: uri
              description: |
                href to manage DEVICE_RISK part for the account credential
            document:
              type: string
              format: uri
              description: |
                href to manage document upload for the account credential. 
        workflowExecution:
          type: string
          format: uri
          description: >
            href to manage the acquisition and <a href =
            "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#workflowdefinition">workflow</a>
            processing. 
    webSettings:
      type: object
      description: |

        Web client settings. 
      properties:
        successUrl:
          type: string
          minLength: 1
          maxLength: 255
          description: >

            Customer-served endpoint to handle successful acquisition scenarios
            during end user journey. 
        errorUrl:
          type: string
          minLength: 1
          maxLength: 255
          description: >

            Customer-served endpoint to handle error acquisition scenarios
            during end user journey. 
        locale:
          type: string
          minLength: 1
          maxLength: 5
          description: >

            Hyphenated combination of <a
            href="https://datahub.io/core/language-codes">ISO 639-1:2002
            alpha-2</a> language code plus  <a
            href="https://datahub.io/core/country-list">ISO 3166-1 alpha-2</a>
            country. Example values:
              - 'en'
              - 'en-GB'
              - 'de'
              - 'es'
              - 'zh-CN'
    userConsent:
      type: object
      description: >-

        <a href =
        "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#userconsent">User
        Consent</a> information.
      properties:
        userIp:
          type: string
          maxLength: 100
          description: |
            The end-user's IP address. Must be ipv4 or ipv6.
        userLocation:
          $ref: '#/components/schemas/userLocation'
        consent:
          $ref: '#/components/schemas/consent'
      required:
        - userLocation
    userLocation:
      type: object
      description: |
        The end-user's location including country and state where applicable. 
      properties:
        country:
          type: string
          format: '#/components/schemas/countryCodeISO3166alpha3'
          description: >-

            The end-user's country code in <a
            href="https://www.iban.com/country-codes">ISO-3166-alpha-3</a>
            format.
        state:
          type: string
          maxLength: 100
          description: >

            The end-user's state of residence. State is mandatory when country
            is USA. For USA states, the format is alpha-2 code, for example:
            'IL', 'CA'. For all other countries, state is optional. 
    consent:
      type: object
      description: >

        Status of user <a href =
        "https://documentation.jumio.ai/docs/developer-resources/API/CreateUpdateAccounts/creating-and-updating-accounts#userconsent">Consent</a>.
      properties:
        obtained:
          type: string
          example: 'yes'
          description: |

            Values:
            'yes' - User's Consent was obtained. 
            'no' - User's Consent was not obtained. 
            'na' - not applicable to the current request. 
        obtainedAt:
          type: string
          format: date-time
          example: '2022-07-20T17:20:35.000Z'
          description: >

            The date and time in UTC when consent was obtained. Must be in the
            past relative to UTC time. 
    credentialCategory:
      type: string
      example: ID
      description: |

        Credential category. See the implementation guide for supported values. 
        Example values:
          - 'ID'
          - 'FACEMAP'
          - 'DOCUMENT'
          - 'SELFIE'
    problem:
      type: object
      description: >-
        Definition of the problem conforming to <a href=
        "https://tools.ietf.org/html/rfc7807">https://tools.ietf.org/html/rfc7807</a>
      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: |
            Short plain-English summary of the problem type 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 plain-English 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.
    capabilityOptions:
      type: object
      description: |
        Options to provide capability-specific fields as part of the request.
      properties:
        watchlistScreening:
          type: object
          description: Provide request options for the watchlistScreening capability.
        documentVerification:
          type: object
          description: Provide additional parameters for document verification.
          properties:
            enableExtraction:
              type: boolean
              description: >-
                Used to disable Extraction in cases where a Document is uploaded
                to be stored but extracting the data is not required.
        ekycCheck:
          type: object
          description: Specify a 1x1 or 2x2 search.
          properties:
            searchType:
              type: string
              description: Allowed values are one for 1x1 search, or two for 2x2 search.
        workflowDecision:
          type: object
          description: >-
            Specify a ruleset to override the default ruleset configured for
            your tenant for workflow decision
          properties:
            riskScoreRulesetId:
              type: string
              description: Ruleset ID.
            decisionLabelRulesetId:
              type: string
              description: Consult with Support before using.
        ruleset:
          type: object
          description: >-
            Deprecated, use workflowDecision instead. Provide an array of
            ruleset IDs to override default workflow rulesets.
          properties:
            ids:
              type: array
    countryCodeISO3166alpha3:
      type: string
      enum:
        - AND
        - ARE
        - AFG
        - ATG
        - AIA
        - ALB
        - ARM
        - ANT
        - AGO
        - ATA
        - ARG
        - ASM
        - AUT
        - AUS
        - ABW
        - ALA
        - AZE
        - BIH
        - BRB
        - BGD
        - BEL
        - BFA
        - BGR
        - BHR
        - BDI
        - BEN
        - BLM
        - BMU
        - BRN
        - BOL
        - BES
        - BRA
        - BHS
        - BTN
        - BVT
        - BWA
        - BLR
        - BLZ
        - CAN
        - CCK
        - COD
        - CAF
        - COG
        - CHE
        - CIV
        - COK
        - CHL
        - CMR
        - CHN
        - COL
        - CRI
        - SCG
        - CUB
        - CPV
        - CUW
        - CXR
        - CYP
        - CZE
        - DEU
        - DJI
        - DNK
        - DMA
        - DOM
        - DZA
        - ECU
        - EST
        - EGY
        - ESH
        - ERI
        - ESP
        - ETH
        - FIN
        - FJI
        - FLK
        - FSM
        - FRO
        - FRA
        - GAB
        - GBR
        - GRD
        - GEO
        - GUF
        - GGY
        - GHA
        - GIB
        - GRL
        - GMB
        - GIN
        - GLP
        - GNQ
        - GRC
        - SGS
        - GTM
        - GUM
        - GNB
        - GUY
        - HKG
        - HMD
        - HND
        - HRV
        - HTI
        - HUN
        - IDN
        - IRL
        - ISR
        - IMN
        - IND
        - IOT
        - IRQ
        - IRN
        - ISL
        - ITA
        - JEY
        - JAM
        - JOR
        - JPN
        - KEN
        - KGZ
        - KHM
        - KIR
        - COM
        - KNA
        - PRK
        - KOR
        - KWT
        - CYM
        - KAZ
        - LAO
        - LBN
        - LCA
        - LIE
        - LKA
        - LBR
        - LSO
        - LTU
        - LUX
        - LVA
        - LBY
        - MAR
        - MCO
        - MDA
        - MNE
        - MAF
        - MDG
        - MHL
        - MKD
        - MLI
        - MMR
        - MNG
        - MAC
        - MNP
        - MTQ
        - MRT
        - MSR
        - MLT
        - MUS
        - MDV
        - MWI
        - MEX
        - MYS
        - MOZ
        - NAM
        - NCL
        - NER
        - NFK
        - NGA
        - NIC
        - NLD
        - NOR
        - NPL
        - NRU
        - NIU
        - NZL
        - OMN
        - PAN
        - PER
        - PYF
        - PNG
        - PHL
        - PAK
        - POL
        - SPM
        - PCN
        - PRI
        - PSE
        - PRT
        - PLW
        - PRY
        - QAT
        - REU
        - ROU
        - SRB
        - RUS
        - RWA
        - SAU
        - SLB
        - SYC
        - SDN
        - SWE
        - SGP
        - SHN
        - SVN
        - SJM
        - SVK
        - SLE
        - SMR
        - SEN
        - SOM
        - SUR
        - SSD
        - STP
        - SLV
        - SXM
        - SYR
        - SWZ
        - TCA
        - TCD
        - ATF
        - TGO
        - THA
        - TJK
        - TKL
        - TLS
        - TKM
        - TUN
        - TON
        - TUR
        - TTO
        - TUV
        - TWN
        - TZA
        - UKR
        - UGA
        - UMI
        - USA
        - URY
        - UZB
        - VAT
        - VCT
        - VEN
        - VGB
        - VIR
        - VNM
        - VUT
        - WLF
        - WSM
        - XKX
        - YEM
        - MYT
        - ZAF
        - ZMB
        - ZWE
      description: >
        <a href="https://www.iban.com/country-codes">(ISO 3166-1 alpha-3)</a>
        country code.
    migrationRequest:
      type: object
      description: |
        INTERNAL USE ONLY. 
      properties:
        scanReferences:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            format: uuid
        callbackUrl:
          type: string
          minLength: 1
          maxLength: 255
          description: >
            URL to override the default callback URL for this particular
            request. 
      required:
        - scanReferences
    migrationResponse:
      type: object
      description: |
        INTERNAL USE ONLY. 
      properties:
        account:
          type: object
          properties:
            id:
              type: string
              format: uuid
  responses:
    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 occurred 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: []
