openapi: 3.0.1
info:
  title: Documents
  version: 2.10.0
  description: Documents REST API for documents management.
  contact:
    name: Tradevest GmbH
servers:
  - url: https://tvda-api.platform-test.tradevest.ai
    description: Test
security:
  - Bearer: []
tags:
  - name: New Documents
    description: New Documents domain
paths:
  /v2/documents:
    get:
      summary: Get Documents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Documents'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: get-documents
      x-operation-group: documents-query
      x-required-permissions: rs/documents/read
      parameters:
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/searchText'
        - $ref: '#/components/parameters/resourceType'
        - $ref: '#/components/parameters/resourceId'
        - $ref: '#/components/parameters/docType'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
      description: Get documents. By default, it returns last 20 documents. It is possible to send query parameters to adjust the result
      tags:
        - New Documents
    post:
      summary: Upload Document
      operationId: upload-document
      x-operation-group: documents-command
      x-required-permissions: rs/documents/write
      parameters:
        - $ref: '#/components/parameters/requestorId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadDocumentResult'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: |-
        | Document Group                | Document Type                                                                                                                                                        | Entities/Roles                                                                                       |
        |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
        | Company documents             | `CURRENT_REGISTRY_EXTRACT`<br/>`CHRONOLOGICAL_REGISTRY_EXTRACT`<br/>`SHAREHOLDER_LIST`<br/>`PARTNERSHIP_AGREEMENT`<br/>`TRANSPARENCY_REGISTER_EXTRACT`<br/>`STATUTE` | `LEGAL_ENTITY`                                                                                       |
        | Company documents             | `BUSINESS_REGISTRATION`                                                                                                                                              | `NATURAL_PERSON`<br/>`LEGAL_ENTITY`                                                                  |
        | Kyc documents                 | `IDENTIFICATION_CERTIFICATE`<br/>`PROOF_OF_RESIDENCE`<br/>`KYC`                                                                                                      | `NATURAL_PERSON`<br/>`PARTNER_USER`                                                                  |
        | Kyc documents                 | `BIRTH_CERTIFICATE`                                                                                                                                                  | `NATURAL_PERSON`  (Minor)                                                                            |
        | Kyc documents                 | `DEATH_CERTIFICATE`                                                                                                                                                  | `NATURAL_PERSON`                                                                                     |
        | Tax documents                 | `TIN_NA_CONFIRMATION`                                                                                                                                                | `NATURAL_PERSON`                                                                                     |
        | Tax documents                 | `W_8BEN_E`<br/>`W_8BEN`<br/>`W_8IMY`                                                                                                                                 | `LEGAL_ENTITY`                                                                                       |
        | Financial situation documents | `SOURCE_OF_INCOME`<br/>`SOURCE_OF_FUNDS`                                                                                                                             | `CUSTOMER`                                                                                           |
        | Proxy documents               | `PROOF_OF_SINGLE_CUSTODY`<br/>`PROOF_OF_CUSTODY`                                                                                                                     | `PROXY` (Guardian)                                                                                   |
        | Proxy documents               | `INSOLVENCY_ORDER`                                                                                                                                                   | `PROXY` (Liquidator)                                                                                 |
        | Proxy documents               | `INHERITANCE_LIGITIMATION`                                                                                                                                           | `PROXY` (Power of Attorney in case of death)                                                         |
        | General documents             | `OTHER`                                                                                                                                                              | `NATURAL_PERSON`<br/>`JOINT_PERSON`<br/>`LEGAL_ENTITY`<br/>`PARTNER_USER`<br/>`CUSTOMER`<br/>`PROXY` |
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                document:
                  $ref: '#/components/schemas/DocumentData'
                file:
                  type: string
                  format: binary
                  description: File data
              required:
                - document
                - file
      tags:
        - New Documents
  /v2/documents/{documentId}:
    get:
      summary: Get Document
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: get-document
      x-operation-group: documents-query
      x-required-permissions: rs/documents/read
      parameters: []
      description: Get document
      tags:
        - New Documents
    parameters:
      - $ref: '#/components/parameters/documentId'
  /v2/documents/{documentId}/file:
    get:
      summary: Get Document File
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      operationId: get-document-file
      x-operation-group: documents-query
      x-required-permissions: rs/documents/read
      parameters: []
      description: Get document file
      tags:
        - New Documents
    parameters:
      - $ref: '#/components/parameters/documentId'
  /v2/documents/upload:
    post:
      summary: Request Document Upload
      operationId: request-document-upload
      x-operation-group: documents-command
      x-required-permissions: rs/documents/write
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: |-
        Request a presigned S3 PUT URL to upload a document directly.

        **Flow:**
        1. Call this endpoint to get a presigned S3 PUT URL
        2. PUT the file directly to `uploadUrl` (valid 15 minutes, bypasses API Gateway)
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUploadRequest'
        required: true
      tags:
        - New Documents
  /v2/documents/sign:
    post:
      summary: Sign Document
      operationId: sign-document
      x-operation-group: documents-command
      x-required-permissions: rs/documents/write
      tags:
        - New Documents
      parameters:
        - $ref: '#/components/parameters/requestorId'
      responses:
        '202':
          description: Accepted
          content: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Create new natural person document signature
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentSignatureData'
components:
  schemas:
    Document:
      type: object
      properties:
        documentId:
          type: string
          format: uuid
          readOnly: true
        size:
          type: integer
          description: file size in kB
          readOnly: true
        status:
          $ref: '#/components/schemas/DocumentStatusEnum'
        validUntil:
          type: string
          format: date-time
          readOnly: true
        createdOn:
          type: string
          format: date-time
          readOnly: true
        modifiedOn:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 255
        resourceType:
          $ref: '#/components/schemas/DocumentResourceTypeEnum'
        type:
          $ref: '#/components/schemas/DocumentTypeEnum'
        description:
          type: string
          minLength: 1
          maxLength: 255
        resourceId:
          type: string
          format: uuid
          description: Identification number in UUID format of resource of type identified by the value of `resourceType` field
        externalId:
          type: string
          minLength: 1
          description: External Id in partner's system. This value has to be unique
      required:
        - createdOn
        - documentId
        - modifiedOn
        - name
        - resourceId
        - resourceType
        - size
        - status
        - type
      title: Document
    DocumentData:
      title: DocumentData
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        resourceType:
          $ref: '#/components/schemas/DocumentResourceTypeEnum'
        type:
          $ref: '#/components/schemas/DocumentUploadTypeEnum'
        description:
          type: string
          minLength: 1
          maxLength: 255
        resourceId:
          type: string
          format: uuid
          description: Identification number in UUID format of resource of type identified by the value of `resourceType` field
        externalId:
          type: string
          minLength: 1
          description: External Id in partner's system. This value has to be unique
      required:
        - name
        - type
        - resourceType
        - resourceId
      x-examples:
        Example 1:
          name: example.pdf
          type: ONBOARDING
          description: An example document
          proxyId: 09b04cfe-617d-4676-a98b-409851c9c93c
    DocumentUploadRequest:
      title: DocumentUploadRequest
      type: object
      properties:
        identificationId:
          type: string
          format: uuid
          description: Id of the identification which requires document upload
      required:
        - identificationId
    DocumentSignatureData:
      title: DocumentSignatureData
      type: object
      x-examples:
        Example 1:
          partnerDocumentId: 87d8e330-2878-4742-a86f-dbbb3bf522ac
          naturalPersonId: 77d8e330-2878-4742-a86f-dbbb3bf522ac
          customerId: 67d8e330-2878-4742-a86f-dbbb3bf522ac
      properties:
        partnerDocumentId:
          type: string
          format: uuid
          description: Id of the partner document which was signed
        naturalPersonId:
          type: string
          format: uuid
          description: Id of the natural person for which the document is signed
        customerId:
          type: string
          format: uuid
          description: Id of the customer in whose context the natural person is active. Required only for TERMS_AND_CONDITIONS document type.
      required:
        - partnerDocumentId
        - naturalPersonId
    UploadDocumentResult:
      title: UploadDocumentResult
      type: object
      properties:
        documentId:
          type: string
          format: uuid
          readOnly: true
      required:
        - documentId
    DocumentUploadResponse:
      title: DocumentUploadResponse
      type: object
      properties:
        uploadUrl:
          type: string
          description: Presigned S3 PUT URL. Valid for 15 minutes. Use it to PUT the document file directly to S3.
          readOnly: true
      required:
        - uploadUrl
    Documents:
      title: Documents
      type: object
      properties:
        data:
          type: array
          description: Array of documents
          items:
            $ref: '#/components/schemas/Document'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    DocumentResourceTypeEnum:
      title: DocumentResourceTypeEnum
      type: string
      enum:
        - NATURAL_PERSON
        - LEGAL_ENTITY
        - PARTNER_USER
        - CUSTOMER
        - PROXY
    DocumentTypeEnum:
      title: DocumentTypeEnum
      type: string
      description: This list may change in the future.
      enum:
        - KYC
        - OTHER
        - PROOF_OF_SINGLE_CUSTODY
        - PROOF_OF_CUSTODY
        - PROOF_OF_RESIDENCE
        - BIRTH_CERTIFICATE
        - IDENTIFICATION_CERTIFICATE
        - CURRENT_REGISTRY_EXTRACT
        - CHRONOLOGICAL_REGISTRY_EXTRACT
        - SHAREHOLDER_LIST
        - PARTNERSHIP_AGREEMENT
        - TRANSPARENCY_REGISTER_EXTRACT
        - BUSINESS_REGISTRATION
        - STATUTE
        - INHERITANCE_LEGITIMATION
        - INSOLVENCY_ORDER
        - TIN_NA_CONFIRMATION
        - SOURCE_OF_INCOME
        - SOURCE_OF_FUNDS
        - DEATH_CERTIFICATE
        - W_8BEN_E
        - W_8BEN
        - W_8IMY
        - CRYPTO_RECEIPT
        - TRADE_INVOICE
        - TOK_TRADE_INVOICE
        - EX_ANTE
        - TOK_EX_ANTE
        - CORPORATE_ACTION
        - TRANSFER_RECEIPT
        - WALLET_ACCOUNT_STATEMENT
        - TRADE_INVOICE_SAVINGS_PLAN
    DocumentStatusEnum:
      title: DocumentStatusEnum
      type: string
      enum:
        - RECEIVED
        - INVALID
        - CREATED
        - PENDING
        - APPROVED
        - REJECTED
        - ARCHIVED
        - DELETED
      readOnly: true
    Pagination:
      title: Pagination
      type: object
      properties:
        cursor:
          type: string
          description: String value used for pagination, which should be set in next page request.
        limit:
          type: integer
          description: Maximum number of returned items
      required:
        - cursor
        - limit
    ErrorDetailsExplanation:
      title: ErrorDetailsExplanation
      type: object
      properties:
        code:
          type: string
          maxLength: 255
        parameter:
          type: string
        message:
          type: string
      required:
        - code
        - message
    ErrorDetails:
      title: ErrorDetails
      type: object
      properties:
        field:
          type: string
          maxLength: 255
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetailsExplanation'
      required:
        - field
    ErrorMessage:
      title: ErrorMessage
      type: object
      properties:
        message:
          type: string
        responseType:
          type: string
        validationString:
          minLength: 1
          type: string
        requestId:
          type: string
        errorCode:
          type: string
          maxLength: 255
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
      required:
        - message
        - responseType
        - requestId
    DocumentUploadTypeEnum:
      title: DocumentUploadTypeEnum
      type: string
      enum:
        - KYC
        - OTHER
        - PROOF_OF_SINGLE_CUSTODY
        - PROOF_OF_CUSTODY
        - PROOF_OF_RESIDENCE
        - BIRTH_CERTIFICATE
        - IDENTIFICATION_CERTIFICATE
        - CURRENT_REGISTRY_EXTRACT
        - CHRONOLOGICAL_REGISTRY_EXTRACT
        - SHAREHOLDER_LIST
        - PARTNERSHIP_AGREEMENT
        - TRANSPARENCY_REGISTER_EXTRACT
        - BUSINESS_REGISTRATION
        - STATUTE
        - INHERITANCE_LEGITIMATION
        - INSOLVENCY_ORDER
        - TIN_NA_CONFIRMATION
        - SOURCE_OF_INCOME
        - SOURCE_OF_FUNDS
        - DEATH_CERTIFICATE
        - W_8BEN_E
        - W_8BEN
        - W_8IMY
  parameters:
    cursor:
      schema:
        type: string
      in: query
      name: cursor
      description: String value used for pagination
    limit:
      schema:
        type: integer
        default: 20
        minimum: 1
      in: query
      name: limit
      description: Maximum number of items to return
      required: true
    requestorId:
      schema:
        type: string
        format: uuid
      name: Requestor-ID
      in: header
      required: true
      description: Unique requestor identification in UUID format
      x-requestor-id: true
    startDate:
      schema:
        type: string
        format: date-time
      name: startDate
      in: query
      description: Beginning of the range
    endDate:
      schema:
        type: string
        format: date-time
      in: query
      name: endDate
      description: End of the range
    searchText:
      schema:
        type: string
      in: query
      name: searchText
      description: search string to filter through document names
    resourceType:
      schema:
        $ref: '#/components/schemas/DocumentResourceTypeEnum'
      in: query
      name: resourceType
      required: true
    resourceId:
      schema:
        type: string
        format: uuid
      in: query
      name: resourceId
      required: true
    docType:
      schema:
        $ref: '#/components/schemas/DocumentTypeEnum'
      in: query
      name: docType
      description: document type filter
    documentId:
      schema:
        type: string
        format: uuid
      name: documentId
      in: path
      required: true
      description: Unique document identification number in UUID format
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://tvdcustomauthdomain.auth.eu-central-1.amazoncognito.com/oauth2/token
          scopes: {}
x-tagGroups:
  - name: Documents
    tags:
      - New Documents
