search
Developer portal

Loan contract file

The JSON file for the loan contract data is structured as follows:

chevron-rightLoan contract filehashtag
{
  "contracts": [
    {
      "externalPersonId": "EXT-P-1000",
      "tuumPersonId": null,
      "externalContractId": "EXT-C-1000",
      "source": {
        "sourceName": "MY-CONTRACT-DB",
        "sourceRef": "ID1000"
      },
      "contractNumber": "900-100-1",
      "loanTypeCode": "SECURED_LOAN_TEST",
      "referenceNumber": null,
      "preparationDate": "2023-03-18",
      "signingDate": "2023-03-18",
      "startDate": "2023-03-18",
      "activationDate": "2023-03-18",
      "endDate": "2053-04-18",
      "stopDate": "2053-04-18",
      "statusCode": "ACTIVE",
      "period": 1,
      "apr": 0,
      "scheduleTypeCode": "ANNUITY",
      "limitMoney": {
        "amount": 1500,
        "currencyCode": "EUR"
      },
      "contractFeeMoney": {
        "amount": 1500,
        "currencyCode": "EUR"
      },
      "contractMoney": {
        "amount": 1500,
        "currencyCode": "EUR"
      },
      "countryCode": "EE",
      "tenantCode": "MB",
      "solvencyLevelCode": "NORMAL_CREDIT",
      "externalServicingAccountId": null,
      "repayment": {
        "paymentFreeMonths": null,
        "monthlyRepaymentAmount": {
          "amount": 1500,
          "currencyCode": "EUR"
        },
        "monthlyRepaymentRate": null,
        "maxInvoiceMoney": null,
        "minInvoiceMoney": null,
        "invoiceDay": null,
        "paymentDay": 18,
        "previousInvoiceDate": "2023-04-18"
      },
      "hasCollateral": true,
      "initialLtv": 0,
      "currentLtv": 0,
      "limitUsageDate": "2024-10-10",
      "penaltyGraceDays": 3,
      "penaltyGraceMoney": null,
      "repaymentChannelCode": null,
      "contractConditions": null,
      "components": [
        {
          "componentTypeCode": "PRI",
          "paymentInterval": 1,
          "balanceMoney": {
            "amount": 1500,
            "currencyCode": "EUR"
          },
          "invoicedBalanceMoney": {
            "amount": 1500,
            "currencyCode": "EUR"
          }
        },
        {
          "componentTypeCode": "ALIM",
          "balanceMoney": {
            "amount": 0,
            "currencyCode": "EUR"
          },
          "invoicedBalanceMoney": {
            "amount": 0,
            "currencyCode": "EUR"
          }
        },
        {
          "componentTypeCode": "INT",
          "paymentInterval": 1,
          "balanceMoney": {
            "amount": 0,
            "currencyCode": "EUR"
          },
          "invoicedBalanceMoney": {
            "amount": 0,
            "currencyCode": "EUR"
          },
          "calculationMethod": {
            "daysInMonth": "ACT",
            "daysInYear": "365"
          },
          "rateTypeCode": "FLOATING",
          "rateBaseCode": "BOFPR",
          "rate": 14.52,
          "marginRate": 10.77,
          "baseRate": 3.75,
          "nextBaseRateChangeDate": "2025-12-01",
          "rateChangeDay": 1
        }
      ],
      "coBorrowers": null,
      "scheduleLines": [
      {
        "componentTypeCode": "PRI",
        "paymentMoney": {
          "amount": 3500,
          "currencyCode": "EUR"
        },
        "paymentDate": "2024-02-11",
        "processed": false
      },
      {
        "componentTypeCode": "ADM",
        "paymentMoney": {
          "amount": 25,
          "currencyCode": "EUR"
        },
        "paymentDate": "2024-02-11",
        "processed": false
      },
      {
        "componentTypeCode": "INT",
        "paymentMoney": {
          "amount": 158.73,
          "currencyCode": "EUR"
        },
        "paymentDate": "2024-02-11",
        "processed": false
      },
      {
        "componentTypeCode": "ADM",
        "paymentMoney": {
          "amount": 25,
          "currencyCode": "EUR"
        },
        "paymentDate": "2024-03-11",
        "processed": false
      },
      {
        "componentTypeCode": "INT",
        "paymentMoney": {
          "amount": 124.57,
          "currencyCode": "EUR"
        },
        "paymentDate": "2024-03-11",
        "processed": false
      },
      {
        "componentTypeCode": "PRI",
        "paymentMoney": {
          "amount": 3500,
          "currencyCode": "EUR"
        },
        "paymentDate": "2024-03-11",
        "processed": false
      }
    ],
      "customFields": null
    }
  ]
}

Below you will find the table with the loan contract parameters description:

Parameter name
Description
Allowed values/validation

externalContractId*

The unique contract referenced from the external system.

The value is limited to the contract id of contract in the external system.

source:

  • sourceName*

The external source name.

The source name cannot exceed 50 characters.

source:

  • sourceRef*

The external source reference.

The source reference cannot exceed 50 characters.

externalPersonId*

The unique person reference from the external system.

The person record must be imported to Tuum prior to the loan contract import.

contractNumber

The unique contract number referenced to the external system.

If it is not provided, then the Tuum system generates it.

loanTypeCode*

Loan product type.

Note: this loan product type must already be created and activated in the Tuum system.

countryCode*

The loan contract country code.

The loan contract country code should match the loan product country code.

referenceNumber

The loan contract reference number.

If null, the reference number is generated by Tuum.

preparationDate*

The loan contract preparation date.

Conditionally mandatory:

If the loan product is a REVOLVING credit line.

Note: The date format: YYYY-MM-DD.

signingDate

The loan contract signing date.

The date format: YYYY-MM-DD.

startDate*

The loan contract start date.

The date format: YYYY-MM-DD.

activationDate*

The loan contract activation date.

The date format: YYYY-MM-DD.

endDate*

The loan contract end date.

Conditionally mandatory:

  • If a loan product term rule is INFINITE, then the endDate = null (sending endDate is not allowed).

  • If a loan product term rule is DEFINITE, then the endDate is mandatory.

  • If a loan product term rule is PERIOD IN MONTH, then the endDate should be set to the last payment date in the schedule.

limitUsageDate*

The loan contract limit usage date.

Conditionally mandatory:

If the loan product limit usage rule is SPECIFIC_DATE, then sending limitUsageDate is mandatory.

statusCode*

The loan contract status.

The only allowed value is ACTIVE.

Note: it is only possible to import contracts in ACTIVE status.

period*

The loan contract period.

Conditionally mandatory:

If the loan product term rule is PERIOD_IN_MONTHS for the product.

The loan period should be in the range defined in the product setup.

apr*

The annual percentage rate.

scheduleTypeCode*

The loan contract schedule type.

Should be the same as the loan product schedule type code.

contractFeeMoney

The loan contract activation fee amount.

limitMoney*

Loan contractual amount.

contractMoney*

Loan contract amount.

tenantCode

The tenant code where the loan contract was created.

The loan contract tenant code should be the same as for the loan product and the loan contract.

externalServicingAccountId*

The unique servicing account id; reference from the external system.

Conditionally mandatory:

If the loan product service account rule code = CURRENT_ACCOUNT_REQUIRED.

Note: the servicing account must be imported to the Tuum system before the loan contract import.

monthlyRepaymentAmount*

The loan contract monthly repayment amount.

monthlyRepaymentRate

Monthly repayment rate.

paymentDay*

The number of day in a month when a borrower needs to repay the loan contract.

The parameter value can be in the interval from 1 to 28.

invoiceDay*

The invoice day The number of a day in a month when the repayment invoice is issued.

Conditionally mandatory:

If the loan product invoice date rule is FIXED_DATE.

previousInvoiceDate*

The loan contract previous invoice date.

Conditionally mandatory:

  • If there is no invoice yet, then previousInvoiceDate = null.

  • If there was a previous invoice, the previousInvoiceDate should be filled in a date format: YYYY-MM-DD.

components[]*

List of the loan contract components.

It is required to provide PRI, INT, and ALIM components.

  • componentTypeCode*

The loan contract component type code.

The list of available values:

  • PRI - principal.

  • INT - interest.

  • ALIM - available limit.

Note: the component type code must be defined in the loan product settings.

  • paymentInterval*

Payment interval in months.

The parameter value should be an integer.

  • balanceMoney[]*

    • amount

    • currencyCode

The loan contract component balance amount.

The currencyCode format: ISO 4217.

  • Debts[]

    • debtMone

      • amount

      • currencyCode

    • debtStartDate

The loan contract debt component includes the debt amount, currency and start date.

  • The currencyCode format: ISO 4217.

  • The date format: YYYY-MM-DD.

Note: the overdue invoices are created based on debt objects. If the debt object is null, it means that there are no overdue invoices.

  • invoicedBalanceMoney[]*

    • amount

    • currencyCode

Component invoiced amount with a future due date.

The pending invoices are created based on the invoiced amount, and their due date is set to nextInvoiceDate.

Note: If there is no pending invoice, it is still mandatory to set the invoicedBalanceMoney parameter to 0.

  • regularMoney*

The loan contract regular fee amount.

Conditionally mandatory: Required if it is a regular fee.

  • calculationMethod[]*

    • daysInMonth

    • daysInYear

Interest calculation method includes daysInMonth and daysInYear.

Conditionally mandatory: Required for interest-like components. Available values:

  • Integer,

  • ACT.

  • rateTypeCode*

Rate type code.

Conditionally mandatory: Required for interest-like components.

Available values:

  • FIX,

  • FLOATING.

  • rate*

Interest rate value.

Conditionally mandatory:

Is included if the rateTypeCode = FLOATING.

  • rateBaseCode*

Interest rate base code.

Conditionally mandatory:

Is included if the rateTypeCode = FLOATING.

  • marginRate*

Margin rate.

Conditionally mandatory:

Is included if the rateTypeCode = FLOATING.

  • baseRate*

Base rate.

Conditionally mandatory:

Is included if the rateTypeCode = FLOATING.

  • nextBaseRateChangeDate*

The next base rate change date.

Conditionally mandatory:

Is included if the rateTypeCode = FLOATING.

Note: The date format: YYYY-MM-DD.

  • rateChangeDay*

The rate change day.

Conditionally mandatory:

Is included if the rateTypeCode = FLOATING.

Note: The number must be between 1 and 31.

coBorrowers[]

  • externalPersonId

  • borrowerTypeCode

List of coborrowers, includes the externalPersonId and the borrowerTypeCode.

Allowed values:

  • GUARANTOR,

  • BORROWER,

  • CO-BORROWER.

scheduleLines[]

  • componentTypeCode

  • paymentMoney

  • paymentDate

List of schedule lines. Includes componentTypeCode, paymentMoney and paymentDate.

Note: It should be equal to the PRI component.balanceMoney; otherwise, an error is raised.

customFields

List of custom fields.

contractConditions[]

List of contract temporary conditions.

  • interestConditions[]

    • temporaryRate

    • validityRange

      • startDate

      • endDate

Interest conditions. Includes temporaryRate, validityRange (startDate and endDate).

Note: To apply for an interest leave, the newRate must be set to 0.

  • feeConditions[]

    • componentTypeCode

    • Conditions[]

      • temporaryFeeAmount

      • validityRange

        • startDate

        • endDate

Fee conditions.

  • repaymentConditions

    • conditionTypeCode

    • vaidityRange

      • startDate

      • endDate

    • newRepaymentMoney*

Repayment conditions.

Conditionally mandatory: Required if coditionTypeCode = PAYMENT_AMOUNT.

The available values for conditionTypeCode:

  • PAYMENT_LEAVE,

  • INSTALMENT_LEAVE,

  • PAYMENT_AMOUNT.

penaltyGraceDays

Penalty grace days.

penaltyGraceAmount

The penalty grace amount and currency.

The currencyCode format: ISO 4217.

Attach the loan contract file to the request body of the data import API call as shown below.

PreviousTransaction fileNextImport data

Last updated

Was this helpful?