openapi: 3.2.0
info:
  title: Digital Onboarding Document requests 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: Document requests
  description: View details of requests for documents.
paths:
  /document-requests:
    get:
      parameters:
      - $ref: '#/components/parameters/TokenInHeader'
      - $ref: '#/components/parameters/ClientIdQuery'
      - $ref: '#/components/parameters/PartyIdQuery'
      tags:
      - Document requests
      summary: List document requests
      description: 'Get a list of document requests.

        '
      operationId: smbdo-listDocumentRequests
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestListResponse'
              examples:
                DocumentRequestListResponse:
                  $ref: '#/components/examples/DocumentRequestListResponse'
        '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'
  /document-requests/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/TokenInHeader'
      - name: id
        in: path
        description: Unique identifier for a document request.
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/DocumentRequestId'
        example: '50040'
      tags:
      - Document requests
      summary: Get document request
      description: Returns details for a document request using its unique identifier.
      operationId: smbdo-getDocumentRequest
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentRequestResponse'
              examples:
                DocumentRequestDriversLicenseUs:
                  $ref: '#/components/examples/DocumentRequestDriversLicenseUs'
        '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'
  /document-requests/{id}/submit:
    post:
      parameters:
      - $ref: '#/components/parameters/TokenInHeader'
      - $ref: '#/components/parameters/IdempotencyKey'
      - name: id
        in: path
        description: Unique identifier for a document request.
        required: true
        style: simple
        schema:
          $ref: '#/components/schemas/DocumentRequestId'
        example: '50040'
      tags:
      - Document requests
      summary: Submit a document request
      description: Submit a document request after documents that fulfill the request have been submitted.
      operationId: smbdo-submitDocumentRequest
      responses:
        '202':
          $ref: '#/components/responses/202'
        '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:
    DocumentTypeSmbdo:
      type: string
      description: Supported document types
      enum:
      - ANNUAL_FILINGS
      - ARTICLES_OF_ASSOCIATION
      - ARTICLES_OF_INCORPORATION
      - BANK_STATEMENT
      - BANKING_LICENSE
      - BEARER_SHARES_ATTESTATION
      - BENEFICIAL_OWNER_INFORMATION
      - BRAND_LOGO
      - BULK_MIGRATION
      - BUSINESS_LICENSE
      - BUSINESS_REGISTRATION_CERT
      - CERTIFICATE_OF_GOOD_STANDING
      - CERTIFICATE_OF_STATUS
      - COMMERCIAL_REGISTRY
      - CONSTITUTIONAL_DOCUMENT
      - CREDIT_CARD_STATEMENT
      - DETAILS_OF_DIRECTORS
      - DISCLOSURE_AND_CONSENT
      - DRIVERS_LICENSE
      - EIN
      - EVIDENCE
      - FILING_RECEIPT
      - GOV_ISSUED_ID_CARD
      - GOVERNMENT_REGISTERED_DOCUMENT
      - IDENTIFICATION_DOCUMENT
      - INCUMBENCY_CERTIFICATE
      - INSURANCE_DOCUMENT
      - IRS_DOCUMENT_TIN
      - JPMC_DISCLOSURE
      - LEGAL_DOCUMENTS
      - LLC_AGREEMENT
      - LOAN_ACCOUNT_STATEMENT
      - MAA
      - MOA
      - OFFERING_MEMO
      - OPERATING_AGREEMENT
      - OTHER_GOV_REGISTRATION_DOCS
      - OWNERSHIP_ATTESTATION
      - PARTNERSHIP_AGREEMENT
      - PASSPORT
      - SEC_FILINGS_10K
      - SIGNATURE_CARD
      - SSN_CARD
      - STANDARD_OPERATING_PROCEDURE
      - SUPPORT_CONTACT
      - TAX_DOCUMENT
      - TERMS_CONDITIONS
      - TRUST_AGREEMENT
      - TRUST_DEED
      - UTILITY_BILL
    DocumentRequestRequirement:
      type: object
      properties:
        documentTypes:
          type: array
          items:
            $ref: '#/components/schemas/DocumentTypeSmbdo'
          minItems: 1
          maxItems: 100
        level:
          type: string
          enum:
          - PRIMARY
          - SECONDARY
        minRequired:
          type: integer
          default: 0
          maximum: 10
          minimum: 0
      required:
      - documentTypes
    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.
    DocumentRequestId:
      description: Unique Document Request identifier.
      type: string
      maxLength: 30
    DocumentRequestResponse:
      type: object
      properties:
        clientId:
          $ref: '#/components/schemas/ClientId'
        country:
          deprecated: true
          type: string
          example: US
          description: Country code in ISO alpha-2 format. Deprecated for document requests.
          minLength: 2
          maxLength: 2
        createdAt:
          type: string
          format: date-time
          example: '2017-07-21T17:32:28.000Z'
        documentType:
          deprecated: true
          $ref: '#/components/schemas/DocumentTypeSmbdo'
        id:
          $ref: '#/components/schemas/DocumentRequestId'
        partyId:
          $ref: '#/components/schemas/PartyId'
        description:
          type: string
          description: Provides an accurate detailing of which documents and how many are being requested. A plain English description that will fulfill the document-request.
          example: "Please provide documents:\n - Signature Card"
        outstanding:
          $ref: '#/components/schemas/DocumentRequestOutstanding'
        requirements:
          description: All requirements must be fulfilled.
          type: array
          items:
            $ref: '#/components/schemas/DocumentRequestRequirement'
          minItems: 1
          maxItems: 10
        status:
          $ref: '#/components/schemas/DocumentRequestStatus'
        updatedAt:
          deprecated: true
          type: string
          format: date-time
          example: '2017-07-21T17:32:28.000Z'
        validForDays:
          $ref: '#/components/schemas/ValidForDays'
    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
    ClientId:
      description: A client's unique ID
      example: '9000000333'
      type: string
      maxLength: 10
    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
    DocumentRequestListResponse:
      type: object
      properties:
        documentRequests:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRequestResponse'
          minItems: 0
          maxItems: 100
        metadata:
          $ref: '#/components/schemas/PageMetaData'
      required:
      - documentRequests
      - metadata
    ValidForDays:
      type: integer
      description: Number of days from the day of its creation that this request will expire.
      example: 5
      minimum: 1
      maximum: 180
    DocumentRequestOutstanding:
      description: Outstanding items on the document request.
      type: object
      properties:
        documentTypes:
          description: List of document types that should be uploaded to meet the requirements.
          type: array
          items:
            $ref: '#/components/schemas/DocumentTypeSmbdo'
          maxItems: 100
          minItems: 0
      required:
      - documentTypes
    PartyId:
      type: string
      maxLength: 10
      example: '2000005555'
      pattern: ^[0-9]{10}$
      description: 'Organization/Individual party id, that uniquely identifies the party.

        '
    DocumentRequestStatus:
      type: string
      enum:
      - ACTIVE
      - CLOSED
      - EXPIRED
  parameters:
    ClientIdQuery:
      name: clientId
      in: query
      description: Unique Client identifier.
      required: false
      example: '3000000001'
      schema:
        $ref: '#/components/schemas/ClientId'
    PartyIdQuery:
      name: partyId
      in: query
      description: Unique Party identifier.
      required: false
      example: '2000000555'
      schema:
        type: string
        maxLength: 10
    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
  examples:
    DocumentRequestListResponse:
      summary: List of document requests
      description: A list of document requests
      value:
        documentRequests:
        - id: '50006'
          country: US
          createdAt: '2022-11-18T12:28:11.232Z'
          description: "Please provide documents:\n - Signature Card"
          requirements:
          - documentTypes:
            - SIGNATURE_CARD
            level: PRIMARY
            minRequired: 1
          outstanding:
            documentTypes:
            - SIGNATURE_CARD
          partyId: '2000000555'
          status: ACTIVE
          updatedAt: '2022-11-18T12:28:11.232Z'
          validForDays: 120
        metadata:
          page: 0
          limit: 25
          total: 1
    DocumentRequestDriversLicenseUs:
      summary: Get document request - US driver's license
      description: Get document request - US driver's license
      value:
        id: '3000011675'
        country: US
        createdAt: '2022-11-18T12:28:11.232Z'
        description: "Please provide documents:\n - US driver's license"
        requirements:
        - documentTypes:
          - DRIVERS_LICENSE
          level: PRIMARY
          minRequired: 1
        outstanding:
          documentTypes:
          - DRIVERS_LICENSE
        partyId: '2000000111'
        status: ACTIVE
        updatedAt: '2022-11-18T12:28:11.232Z'
        validForDays: 5
  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
    '202':
      description: Request was accepted
      content:
        application/json:
          schema:
            type: object
            properties:
              acceptedAt:
                type: string
                format: date-time
            required:
            - acceptedAt
          examples:
            Accepted:
              description: Request Accepted
              summary: Request Accepted
              value:
                acceptedAt: '2024-07-21T17:32:28.000Z'
    '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.
  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