openapi: 3.2.0
info:
  title: Digital Onboarding Session API
  version: 1.0.18
  description: Streamline your client onboarding process to create, update, and manage clients, parties, documents, and due diligence requirements in a fully digital workflow so you can automate Know Your Customer (KYC), document collection, and compliance tasks directly from your own platform.
  contact:
    name: JPMC Technical Services Support
servers:
- url: https://api.payments.jpmorgan.com/onboarding/v1
  description: PRODUCTION-MTLS
- url: https://api-sandbox.payments.jpmorgan.com/onboarding/v1
  description: CLIENT TESTING-MTLS
- url: https://api-mock.payments.jpmorgan.com/onboarding/v1
  description: MOCK
security:
- Certs: []
  Token: []
- Certs: []
- BearerAuth: []
tags:
- name: Session
  description: Create session for clients or parties.
paths:
  /sessions:
    get:
      parameters:
      - $ref: '#/components/parameters/TokenInHeader'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageNumber'
      - name: targetId
        in: query
        required: true
        description: Id of the party or client
        example: '2000000001'
        schema:
          type: string
          maxLength: 10
      summary: List sessions
      description: Returns a list of sessions for a client.
      operationId: smbdo-listSessions
      tags:
      - Session
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionResponse'
              examples:
                ListSessionResponse:
                  $ref: '#/components/examples/ListSessionResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    post:
      parameters:
      - $ref: '#/components/parameters/TokenInHeader'
      - $ref: '#/components/parameters/IdempotencyKey'
      tags:
      - Session
      summary: Create session.
      description: Create session.
      operationId: smbdo-postSessions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
            examples:
              CreateSessionRequest:
                $ref: '#/components/examples/CreateSessionRequest'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
              examples:
                SessionResponse:
                  $ref: '#/components/examples/SessionResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  schemas:
    ListSessionResponse:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetaData'
        sessions:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/SessionResponse'
    SessionTargetType:
      description: 'Client or party type.

        '
      type: string
      enum:
      - CLIENT
      - PARTY
    SessionTargetId:
      type: string
      maxLength: 10
      example: '3000005555'
      pattern: ^[0-9]*$
      description: 'The ID of the client or party.

        '
    ApiErrorContext:
      description: Context of the API error.
      type: object
      required:
      - message
      properties:
        code:
          type: string
          description: Short code that identifies the error - publicly cataloged and documented
          example: '11000'
        location:
          type: string
          enum:
          - BODY
          - QUERY
          - PATH
          - HEADER
          example: BODY
          description: Part of the request which is responsible for the reason
        field:
          type: string
          description: The location of the property or parameter in error
        message:
          type: string
          example: The server can not find the requested resource.
          description: Message describing the reason.
    SessionResponse:
      description: List of sessions.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/SessionId'
        type:
          $ref: '#/components/schemas/SessionsType'
        target:
          $ref: '#/components/schemas/SessionTarget'
        url:
          type: string
          description: The URL to redirect to for the embedded UI session transfer.
        token:
          type: string
          description: The token to be used for the session transfer.
    SessionTarget:
      type: object
      required:
      - id
      - type
      properties:
        id:
          $ref: '#/components/schemas/SessionTargetId'
        type:
          $ref: '#/components/schemas/SessionTargetType'
    schemas-ApiError:
      description: An API error.
      type: object
      required:
      - title
      - httpStatus
      properties:
        title:
          type: string
          description: Short humanly-readable title of the error
          example: BAD_REQUEST
        httpStatus:
          type: integer
          description: HTTP status code
          example: 422
        traceId:
          type: string
          description: Internal assigned traced identifier
        requestId:
          type: string
          description: Client provided request identifier
        context:
          type: array
          items:
            $ref: '#/components/schemas/ApiErrorContext'
          description: Provides additional context and detail on the errors
          minItems: 0
          maxItems: 100
    SessionsType:
      type: string
      enum:
      - EMBEDDED_UI
    PageMetaData:
      description: Page metadata.
      type: object
      properties:
        page:
          type: integer
          format: int32
          example: 0
          description: 'Page number.

            '
          minimum: 0
          maximum: 2147483647
        limit:
          type: integer
          format: int32
          example: 25
          description: 'Number of records per page.

            '
          minimum: 1
          maximum: 25
        total:
          type: integer
          format: int64
          example: 340
          description: 'Total number of items.

            '
          minimum: 0
          maximum: 9999999999
    SessionId:
      type: string
      maxLength: 10
      example: '9000005555'
      pattern: ^[0-9]*$
      description: 'ID to uniquely identify the session

        '
    CreateSessionRequest:
      type: object
      required:
      - type
      - target
      properties:
        type:
          $ref: '#/components/schemas/SessionsType'
        target:
          $ref: '#/components/schemas/SessionTarget'
  responses:
    '403':
      description: Forbidden - Unauthorized Access
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Forbidden
            httpStatus: 403
            context:
            - message: Platform is not authorized to access client.
    '500':
      description: Internal Server Error - Generic Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Internal Server Error
            httpStatus: 500
            context:
            - message: Something went wrong. Please try again later.
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Invalid Data
            httpStatus: 400
            context:
            - code: '10104'
              message: Client with ID [3000005555] does not exist.
              location: BODY
              field: clientId
    '401':
      description: Unauthenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Unauthorized
            httpStatus: 401
            context:
            - message: Provided token does not follow required JWT format. It may also be missing mandatory parts
    '409':
      description: Conflict - Concurrent request detected
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Conflict
            httpStatus: 409
            context:
            - message: Concurrent request detected for clientId [3000005555]. Please try again later.
    '503':
      description: Service Unavailable - API Processing Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Service Unavailable
            httpStatus: 503
            context:
            - message: Service unavailable.
    '404':
      description: No data found for the criteria specified
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Not Found
            httpStatus: 404
            context:
            - message: Party with ID [2000000555] not found.
    '422':
      description: Request could not be processed due to semantic errors. Check error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/schemas-ApiError'
          example:
            title: Unprocessable Entity
            httpStatus: 422
            context:
            - message: Unable to perform Client Verification for clientId [3000005555] due to its Status.
  examples:
    ListSessionResponse:
      summary: List of sessions
      description: Retrieve list of sessions.
      value:
        metadata:
          page: 0
          limit: 25
          total: 2
        sessions:
        - id: '9000005555'
          type: EMBEDDED_UI
          target:
            id: '3000000001'
            type: CLIENT
          url: https://url.jpmorgan.com/t/17465629080405AI41
          token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ2aXJ0dWFsY2FyZF9xYTAxX
        - id: '9000005556'
          type: EMBEDDED_UI
          target:
            id: '3000000001'
            type: CLIENT
          url: https://url.jpmorgan.com/t/22465629080405AI41
          token: eyJfgGciOiJIUzUxMiJ9.eyJzdWIiOiJ2aXJ0dWFsY2FyZF9xrtDFG
    CreateSessionRequest:
      summary: Create Session Request
      description: Create session.
      value:
        type: EMBEDDED_UI
        target:
          id: '3000000001'
          type: CLIENT
    SessionResponse:
      summary: Create Session
      description: Create session response.
      value:
        id: '9000005555'
        type: EMBEDDED_UI
        target:
          id: '3000000001'
          type: CLIENT
        url: https://url.jpmorgan.com/t/17465629080405AI41
        token: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ2aXJ0dWFsY2FyZF9xYTAxX
  parameters:
    PageSize:
      name: limit
      in: query
      description: Number of records per page.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 25
        default: 25
    PageNumber:
      name: page
      in: query
      description: Page number.
      required: false
      schema:
        type: integer
        format: int32
        default: 0
        minimum: 0
        maximum: 2147483647
    TokenInHeader:
      name: token
      in: header
      description: JWT Client token
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 8192
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: 'Client generated unique idempotency key used in recognizing consecutive retries of the same request

        **Usage of V4 UUIDs is recommended.**'
      required: false
      schema:
        title: Idempotency Key
        description: 'A unique string that enables the API support idempotency by safely retrying requests without accidentally

          performing the same operation twice.'
        type: string
        minLength: 1
        maxLength: 36
        example: 1b036f9c-8c84-4ce6-b1dd-5979472945a1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-jpmc-securityDefinitions:
  JPMC-OAuth2:
    jpmc-claims:
      jpmc-roles:
      - 111789_SMBDO_PAYFAC_ACCESS: API access role claim
x-jpmc-security:
- JPMC-OAuth2:
    jpmc-claims:
      jpmc-roles:
      - 111789_SMBDO_CLIENT_ACCESS: API access role claim