Update contract header

Use case

In this example, we will review how to modify the tax exemption status and tax residency country assigned to an active deposit contract. These values are stored on the contract header level. After updating the contract header, these parameters will apply to all versions of the deposit contract.

Use case data	API parameters
The contract header is ID-1696407222. See the find deposit contract page for more details.	...v2/contracts/ID-1696407222
We will change the tax residency country from Estonia to Germany.	"taxResidencyCountryCode": "DE"
We will set the tax exemption to true.	"taxExempt": "true"

Sample API call

To update the contract header, make the following API call. deposit-api.sandbox.tuumplatform.com/ api/v2/contracts/{headerId}

See more about the update contract header endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for changing deposit contract payout details.

JSON

{
  "taxResidencyCountryCode": "DE",
  "taxExempt": "true"
}

cURL

curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/contracts/ID-1696407222' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMjFUMTQ6NDg6MTciLCJleHAiOjE3Mjk1MjIwOTcsInJvbGVzIjpbIkFETUlOIl19.pM0GzsEXo-IsdVy5X2l9FcORAul0_XaH_SEU_HNugjI' \
--header 'Content-Type: application/json' \
--data '{
  "taxResidencyCountryCode": "DE",
  "taxExempt": "true"
}'

Sample response

Below you find an example response body to the API call above.

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "headerId": "ID-1696407222",
        "personId": "ID-2660",
        "accountId": "ID-1012",
        "applicationId": "ID-1696407202",
        "offerId": "ID-1718024054",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM",
        "contractNumber": "PR-EE-1001",
        "countryCode": "EE",
        "channelCode": "BACKOFFICE",
        "tenantCode": "MB",
        "depositClassCode": "PREMIUM_CUSTOMER",
        "headerActivationDate": "2026-07-08",
        "headerClosingDate": null,
        "activeVersion": {
            "versionId": "ID-1718024033",
            "headerId": "ID-1718024017",
            "versionNumber": 1,
            "statusCode": "ACTIVE",
            "preparationDate": "2026-07-08",
            "signingDate": null,
            "activationDate": "2026-07-08",
            "endDate": "2026-10-08",
            "closingDate": null,
            "period": 3,
            "periodTypeCode": "MONTH",
            "interestRate": 0.25,
            "interestPaymentFrequencyCode": "MONTH",
            "prolongCode": null,
            "countryCode": "EE",
            "cancelReasonCode": null,
            "lastCreditReceiveDate": "2026-07-10",
            "lastSigningDate": null,
            "changeTypeCode": "NEW_CONTRACT",
            "components": [
                {
                    "componentId": "ID-1718024154",
                    "versionId": "ID-1718024033",
                    "componentTypeCode": "PRI",
                    "initialMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 5000.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": null,
                    "rateBaseCode": null,
                    "rate": null,
                    "accruedUntil": null,
                    "paymentDay": 8,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": null
                },
                {
                    "componentId": "ID-1718024155",
                    "versionId": "ID-1718024033",
                    "componentTypeCode": "INT",
                    "initialMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "balanceMoney": {
                        "amount": 0.00,
                        "currencyCode": "EUR"
                    },
                    "calculationMethod": {
                        "daysInMonth": "30",
                        "daysInYear": 360
                    },
                    "rateBaseCode": null,
                    "rate": 0.25,
                    "accruedUntil": null,
                    "paymentDay": 8,
                    "paymentInterval": 1,
                    "baseInvalidFromDate": "2026-07-08"
                }
            ],
            "totalInterestMoney": {
                "amount": 3.13,
                "currencyCode": "EUR"
            },
            "totalInterestAccruedMoney": {
                "amount": 0.00,
                "currencyCode": "EUR"
            },
            "channelCode": "BACKOFFICE",
            "tenantCode": "MB",
            "terminationType": "WITHOUT_INTEREST",
            "nextPayoutDate": "2026-08-08",
            "payoutDetails": {
                "name": "Tech",
                "accountNumber": {
                    "value": "EE201225862567235311",
                    "type": "IBAN"
                },
                "financialInstitutionId": null,
                "referenceNumber": null,
                "countryCode": null
            }
        },
        "personTypeCode": "P",
        "taxResidencyCountryCode": "DE",
        "taxExempt": true,
        "rateBaseCode": null
    }
}

Result

As a result, the tax residency country was updated and the tax exemption was set to true. The updated settings were applied to all existing deposit contract versions.