Deutsche Bank Loan Offers API

openapi: 3.2.0
info:
  title: dbapi-loanOffers-privatebanking Loan Offers API
  description: Easily request loan offers on behalf of your customer.
  termsOfService: https://developer.db.com/termsandconditions
  contact:
    url: https://developer.db.com/contact
    email: bank.api@db.com
  version: v1
servers:
- url: https://simulator-api.db.com:443/gw/dbapi/lending/consumerLoanOffers/v1
tags:
- name: Loan Offers
paths:
  /offers:
    post:
      tags:
      - Loan Offers
      summary: Request an offer for a loan
      description: By providing data about the prospect and needed loan one can request a loan offer. The result is a unique offer id which can be used with the other endpoints for status retrieval or additional processing.
      parameters:
      - name: idempotency-id
        in: header
        description: Unique id of the service call. Should be resent during retries to avoid multiple processing of the same request
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      requestBody:
        description: Request an offer for a loan
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestForOffer'
            examples:
              requestForOfferWithOneDebtor:
                $ref: '#/components/examples/RequestForOfferOneDebtorExample'
              requestForOfferWithTwoDebtors:
                $ref: '#/components/examples/RequestForOfferTwoDebtorsExample'
              requestForOfferWithOneDebtorWithOptionalFieldsFilledOut:
                $ref: '#/components/examples/RequestForOfferWithOneDebtorWithOptionalFieldsFilledOutExample'
        required: true
      responses:
        '201':
          description: An offer proposal was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestForOfferResponse'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 100
                message: Contracting bank details are Invalid or Missing.
              - code: 101
                message: The start date of residence address is required for one of the two addresses when the debtor has two of them. Please try again.
              - code: 102
                message: Insurance percentage should be multiple of 10. Please try again.
              - code: 104
                message: The PDF document you are trying to upload exceeds the maximum allowed limit of 20 MB. Please reduce the file size and try again
              - code: 105
                message: The document you are trying to upload exceeds the maximum allowed limit of 10 MB for image formats ("BMP" "JPG" "PNG" "TIFF"). Please reduce the file size and try again
              - code: 107
                message: The Document Validation Failed as it is not a Valid Image Data
              - code: 108
                message: The uploaded document does not meet requirements. Please check and try again.
              - code: 109
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 110
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
              - code: 111
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 112
                message: The uploaded document does not meet file size requirements. Please check and try again.
              - code: 113
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 114
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 9010
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
        '403':
          description: Unsuccessful operation, returns http status 403. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 103
                message: You do not have permission to access this resource.
      security:
      - api_client_credential:
        - request_private_loans
      operationId: postOffers
      x-operation-id-source: derived
  /offers/{offerId}/status:
    get:
      tags:
      - Loan Offers
      summary: Get status of the offer with given offer id
      operationId: getOfferStatus
      parameters:
      - name: offerId
        in: path
        description: Unique identifier of an offer.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      responses:
        '200':
          description: The status of the offer with offerId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferStatus'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 100
                message: Contracting bank details are Invalid or Missing.
              - code: 101
                message: The start date of residence address is required for one of the two addresses when the debtor has two of them. Please try again.
              - code: 102
                message: Insurance percentage should be multiple of 10. Please try again.
              - code: 104
                message: The PDF document you are trying to upload exceeds the maximum allowed limit of 20 MB. Please reduce the file size and try again
              - code: 105
                message: The document you are trying to upload exceeds the maximum allowed limit of 10 MB for image formats ("BMP" "JPG" "PNG" "TIFF"). Please reduce the file size and try again
              - code: 107
                message: The Document Validation Failed as it is not a Valid Image Data
              - code: 108
                message: The uploaded document does not meet requirements. Please check and try again.
              - code: 109
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 110
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
              - code: 111
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 112
                message: The uploaded document does not meet file size requirements. Please check and try again.
              - code: 113
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 114
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 9010
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
        '403':
          description: Unsuccessful operation, returns http status 403. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 103
                message: You do not have permission to access this resource.
      security:
      - api_client_credential:
        - request_private_loans
  /offers/{offerId}/documents:
    post:
      tags:
      - Loan Offers
      summary: Upload a document for a specified already opened loan offer
      description: The operation is used to upload a single PDF, BMP, JPG, PNG or TIFF document. PDFs may be up to 20 MB and all other file types documents may have a max size of 10 MB.
      operationId: uploadDocumentUsingDocumentInfo
      parameters:
      - name: offerId
        in: path
        description: Unique identifier of an offer.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: idempotency-id
        in: header
        description: Unique id of the service call. Should be resent during retries to avoid multiple processing of the same request
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      requestBody:
        description: The document info and document content.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDocumentRequest'
        required: true
      responses:
        '201':
          description: Successful creation of document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStatusInfo'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 100
                message: Contracting bank details are Invalid or Missing.
              - code: 101
                message: The start date of residence address is required for one of the two addresses when the debtor has two of them. Please try again.
              - code: 102
                message: Insurance percentage should be multiple of 10. Please try again.
              - code: 104
                message: The PDF document you are trying to upload exceeds the maximum allowed limit of 20 MB. Please reduce the file size and try again
              - code: 105
                message: The document you are trying to upload exceeds the maximum allowed limit of 10 MB for image formats ("BMP" "JPG" "PNG" "TIFF"). Please reduce the file size and try again
              - code: 107
                message: The Document Validation Failed as it is not a Valid Image Data
              - code: 108
                message: The uploaded document does not meet requirements. Please check and try again.
              - code: 109
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 110
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
              - code: 111
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 112
                message: The uploaded document does not meet file size requirements. Please check and try again.
              - code: 113
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 114
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 9010
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
        '403':
          description: Unsuccessful operation, returns http status 403. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 103
                message: You do not have permission to access this resource.
      security:
      - api_client_credential:
        - request_private_loans
  /offers/{offerId}/documents/startCase:
    post:
      tags:
      - Loan Offers
      summary: Commit uploaded documents and start processing the loan offer case
      description: 'This operation finalizes the document upload process for the specified loan offer by confirming that all required documents have been successfully submitted.

        Once triggered, the system initiates the internal processing of the case based on the uploaded documents. This endpoint should be called only after all intended documents for the case have been uploaded via the corresponding upload endpoint.'
      operationId: notifyDocumentsUpload
      parameters:
      - name: offerId
        in: path
        description: Unique identifier of an offer.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: idempotency-id
        in: header
        description: Unique id of the service call. Should be resent during retries to avoid multiple processing of the same request
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      requestBody:
        description: Payload carrying transactionId for this upload session.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyDocumentsUploadRequest'
        required: true
      responses:
        '202':
          description: 'Successful operation, case processing has been initiated. '
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 100
                message: Contracting bank details are Invalid or Missing.
              - code: 101
                message: The start date of residence address is required for one of the two addresses when the debtor has two of them. Please try again.
              - code: 102
                message: Insurance percentage should be multiple of 10. Please try again.
              - code: 104
                message: The PDF document you are trying to upload exceeds the maximum allowed limit of 20 MB. Please reduce the file size and try again
              - code: 105
                message: The document you are trying to upload exceeds the maximum allowed limit of 10 MB for image formats ("BMP" "JPG" "PNG" "TIFF"). Please reduce the file size and try again
              - code: 107
                message: The Document Validation Failed as it is not a Valid Image Data
              - code: 108
                message: The uploaded document does not meet requirements. Please check and try again.
              - code: 109
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 110
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
              - code: 111
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 112
                message: The uploaded document does not meet file size requirements. Please check and try again.
              - code: 113
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 114
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 9010
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
        '403':
          description: Unsuccessful operation, returns http status 403. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 103
                message: You do not have permission to access this resource.
      security:
      - api_client_credential:
        - request_private_loans
  /offers/{offerId}/documents/transaction:
    post:
      tags:
      - Loan Offers
      summary: Generate a new transactionId for a document upload session
      description: Generates a unique transactionId to be used for a new upload session. Each upload session (one or more document uploads followed by a single startCase call) requires a fresh transactionId. The generated transactionId must be used in subsequent document upload and startCase calls for this session.
      operationId: generateTransactionId
      parameters:
      - name: offerId
        in: path
        description: Unique identifier of an offer.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: idempotency-id
        in: header
        description: Unique id of the service call. Should be resent during retries to avoid multiple processing of the same request
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
      - name: Correlation-Id
        in: header
        description: Free form key controlled by the caller e.g. uuid
        required: false
        schema:
          maxLength: 50
          type: string
      responses:
        '200':
          description: Successfully generated transactionId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateTransactionIdResponse'
        '400':
          description: Unsuccessful operation, returns http status 400. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 2
                message: Invalid value for %s.
              - code: 3
                message: 'Invalid value for %s: %s.'
              - code: 17
                message: Invalid OTP.
              - code: 100
                message: Contracting bank details are Invalid or Missing.
              - code: 101
                message: The start date of residence address is required for one of the two addresses when the debtor has two of them. Please try again.
              - code: 102
                message: Insurance percentage should be multiple of 10. Please try again.
              - code: 104
                message: The PDF document you are trying to upload exceeds the maximum allowed limit of 20 MB. Please reduce the file size and try again
              - code: 105
                message: The document you are trying to upload exceeds the maximum allowed limit of 10 MB for image formats ("BMP" "JPG" "PNG" "TIFF"). Please reduce the file size and try again
              - code: 107
                message: The Document Validation Failed as it is not a Valid Image Data
              - code: 108
                message: The uploaded document does not meet requirements. Please check and try again.
              - code: 109
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 110
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
              - code: 111
                message: The uploaded document does not meet format requirements. Please check and try again.
              - code: 112
                message: The uploaded document does not meet file size requirements. Please check and try again.
              - code: 113
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 114
                message: Unable to identify transaction by Id.
              - code: 114
                message: The uploaded document exceeds the maximum allowed file size. Please check and try again.
              - code: 127
                message: Booking date from must precede booking date to.
              - code: 131
                message: Invalid value for 'sortBy'. Valid values are 'bookingDate[ASC]' and 'bookingDate[DESC]'.
              - code: 9010
                message: The uploaded document does not meet pdf-format requirements. Please check and try again.
        '401':
          description: Unsuccessful operation, returns http status 401. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 401
                message: The requested function requires a SCA Level Authentication.
        '403':
          description: Unsuccessful operation, returns http status 403. See 'example' property for possible values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
              - code: 103
                message: You do not have permission to access this resource.
      security:
      - api_client_credential:
        - request_private_loans
components:
  schemas:
    ExistingInsurance:
      type: object
      properties:
        disability:
          type: boolean
          description: Whether the customer has an existing disability insurance
        residualDebt:
          type: boolean
          description: Whether the customer has an existing residual debt insurance
        unemployment:
          type: boolean
          description: Whether the customer has an existing unemployment insurance
    PaymentDay:
      type: string
      description: Schedule of the loan repayment
      enum:
      - MONTH_START
      - MONTH_MIDDLE
    DebtRestructuring:
      required:
      - amount
      - bankName
      - ownerName
      - paymentType
      type: object
      properties:
        bankName:
          type: string
        bic:
          type: string
        iban:
          type: string
        ownerName:
          type: string
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        amount:
          type: number
          description: Account balance of the loan to be restructured
    PaymentHoliday:
      type: string
      description: Payment holiday month
      enum:
      - JANUARY
      - FEBRUARY
      - MARCH
      - APRIL
      - MAY
      - JUNE
      - JULY
      - AUGUST
      - SEPTEMBER
      - OCTOBER
      - NOVEMBER
      - DECEMBER
    DocumentType:
      type: string
      description: Structure of the transaction data
      enum:
      - JSON
    MaritalStatus:
      type: string
      description: Marital status of the debtor
      enum:
      - SINGLE
      - DIVORCED
      - CIVIL_UNION_SEPARATE_TAX_ASSESSMENT
      - MARRIED_SEPARATED
      - WIDOWED
      - CIVIL_UNION_SEPARATED
      - SINGLE_LIVING_IN_COHABITATION
      - MARRIED_JOINT_TAX_ASSESSMENT
      - MARRIED_SEPARATE_TAX_ASSESSMENT
      - CIVIL_UNION_JOINT_TAX_ASSESSMENT
    RequestForOfferResponse:
      required:
      - offerId
      type: object
      properties:
        offerId:
          type: string
          description: Unique identifier of an offer.
    Source:
      type: string
      description: Source format of the transaction data
      enum:
      - FINTEC
      - OTHER
    Employment:
      required:
      - disclosedProfession
      - employer
      - employmentLevel
      - employmentStart
      type: object
      properties:
        disclosedProfession:
          type: string
          description: Profession of the debtor
        employer:
          type: string
          description: Current employer of the debtor
        employmentLevel:
          $ref: '#/components/schemas/EmploymentLevel'
        employmentStart:
          type: string
          description: Start date of current employment. [ISO Date. I.e. YYYY-MM-DD]
          format: date
        shortTermEmploymentEndDate:
          type: string
          description: Short term employment end date. [ISO Date. I.e. YYYY-MM-DD]
          format: date
    StatusEnum:
      type: string
      enum:
      - CREATED
      - IN_PROGRESS
      - ACCEPTED
      - REJECTED
      - ERROR
    RequestForOffer:
      required:
      - listAccount
      - listDebtor
      - loanAmount
      - paymentDay
      - productType
      type: object
      properties:
        environment:
          type: string
          description: Identifies the environment in which the request should be processed.
        callbackUrl:
          type: string
          description: Callback URL provided for asynchronous notifications and document delivery related to the loan offers request. If missing, the default configuration will be applied.
        productType:
          $ref: '#/components/schemas/ProductType'
        productName:
          type: string
          description: Name of the product/conditions, to be agreed on between consumer/bank
        externalClientId:
          type: string
          description: Application/process ID in the system
        durationInMonths:
          type: integer
          description: Number of requested installment rates
          format: int32
        installment:
          type: number
          description: Requested amount per installment
        loanAmount:
          type: number
          description: Loan amount in euro
        purpose:
          type: string
          description: Purpose of the loan
        requestedVersion:
          type: string
          description: Application version to handle the request
        paymentDay:
          $ref: '#/components/schemas/PaymentDay'
        paymentHoliday:
          $ref: '#/components/schemas/PaymentHoliday'
        carLoan:
          $ref: '#/components/schemas/CarLoan'
        commission:
          type: number
        listAccountStatement:
          maxItems: 10
          type: array
          items:
            $ref: '#/components/schemas/AccountStatement'
        listAccount:
          maxItems: 2
          minItems: 2
          type: array
          items:
            $ref: '#/components/schemas/Account'
        listDebtRestructuring:
          maxItems: 5
          type: array
          items:
            $ref: '#/components/schemas/DebtRestructuring'
        listDebtor:
          maxItems: 2
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/Debtor'
        listAgent:
          type: array
          items:
            $ref: '#/components/schemas/Agent'
    OfferStatus:
      required:
      - status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusEnum'
    Address:
      required:
      - city
      - country
      - houseNumber
      - street
      - zipCode
      type: object
      properties:
        city:
          type: string
          description: city name
        country:
          type: string
          description: Country the address is located in [ISO 3166-1 alpha-3 code of the country]
        houseNumber:
          type: string
          description: house number
        ownProperty:
          type: boolean
          description: True if living in a self owned property
        street:
          type: string
          description: Street name
        zipCode:
          type: string
          description: Zip code
        residenceAddressSince:
          type: string
          description: Start date of living at the current address, only needed if there was a move in the last 2 years and predecessor addre

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deutsche-bank/refs/heads/main/openapi/deutsche-bank-loan-offers-api-openapi.yml