There are two types of header parameters:

• Mandatory. The mandatory ones ensure that only authorised API calls will receive a positive response.

• Optional. The optional ones allow you to avoid duplicate calls if they are present in the request header.

You can find more information about each of the header parameter types by choosing the options:

To make an authorised API call, you must include the x-auth-token header parameter.

x-auth-token

For the HTTP header parameter x-auth-token, use the JWT token you received in response to the authentication call as a parameter value.

Example cURL with employee token

-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDMtMDhUMDg6NDg6NDkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2NzgyNjUzMjl9.G7rqNTJbeyMdMy1ZGwu1G7JRSvwAg084IiBYhOEz4I8'

Use case

In this example, we will find an existing employee by employeeId.

Sample API call

To find an employee by username, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/employees/username

Sample request

Below is an example request of the API call to retrieve customer data.

Sample response

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

Result

The result of the API call is the dataset of a particular employee.

In this block, you will learn how to open a deposit contract flow. There are two flows available:

• ,

• .

Deposit flow - from application

The first deposit flow starts from a deposit application and includes the following steps:

1. - once the deposit application is created, the Tuum system automatically creates a related deposit offer.

2. - once the deposit offer is accepted, the Tuum system automatically creates a related deposit contract. Or - reject the offer and terminate the flow.

Deposit flow - from offer

You can use this flow if your organisation processes deposit applications outside the Tuum system.

This deposit contract flow starts from a deposit offer and includes the following steps:

1. - to enter the required deposit information into the Tuum system.

2. - once the deposit offer is accepted, the Tuum system will automatically create a deposit contract based on the deposit offer. Or - to reject the deposit offer and terminate the flow.

Below, you will find the following chapters:

Here, you can learn how to use APIs to export roles and their privileges from one Tuum environment and import them into another. This functionality aims to facilitate smooth replication for testing across different environments.

Tuum offers three API endpoints for exporting and importing roles and their associated privileges.

1. Export roles endpoint enables you to retrieve all roles or specific roles and their privileges from the source Tuum environment.

2. Partial import endpoint allows you to add a selected set of roles and their privileges to the target Tuum environment. Any existing roles and privileges in the target environment not included in the import will remain unchanged.

3. Complete import endpoint lets you delete all existing roles and their privileges in the target environment and replace them with new roles and privileges specified in the payload.

Here, you can learn how to make an API call to authenticate a customer. Once you execute the call successfully, you will receive a JSON web token that permits you to make authorised API calls to other Tuum API endpoints.

Sample API call

To authenticate a customer, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/authorise

Sample request

Below is an example request body of the API call for authentication of a customer.

{
"username": "customer_username",
"password": "customer_password"
}

curl 'https://auth-api.sandbox.tuumplatform.com/api/v1/authorise' \
-H 'Content-Type: application/json' \
-d '{
"username": "customer_username",
"password": "customer_password"
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiYWF0b21payIsInBlcnNvbklkIjoiSUQtMTAzOCIsInRlbmFudENvZGUiOiJNQiIsImV4cGlyeURUaW1lIjoiMjAyMy0wNy0yOFQxMjoyMDoyMSIsImV4cCI6MTY5MDU0NjgyMX0.wpNOfTan73vnqQNZo5cI99B2NWuVZ6wurW9JiO7z0x0"
    }
}

Result

An customer is authenticated, and a JSON Web Token is returned in the response.

Here, you can learn how to make an API call to authenticate an employee. Once you execute the call successfully, you will receive a JSON web token that permits you to make authorised API calls to other Tuum API endpoints.

Sample API call

To authenticate an employee, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/employees/authorise

Sample request

Below is an example request body of the API call for authentication of an employee.

{
"username": "employee_username",
"password": "employee_password"
}

curl -X POST 'https://auth-api.sandbox.tuumplatform.com/api/v1/employees/authorise' \
-H 'Content-Type: application/json' \
--data-raw '{
"username": "employee_username",
"password": "employee_password"
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDMtMDhUMDg6NDg6NDkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2NzgyNjUzMjl9.G7rqNTJbeyMdMy1ZGwu1G7JRSvwAg084IiBYhOEz4I8"
    }
}

Result

An employee is authenticated, and a JSON Web Token is returned in the response.

Use case

Here we will review how to create customer groups that are used to make different price decisions based on the group. We will create a new customer group using the following data:

Sample API call

To create a new customer group, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v1/person-group-types

Sample request

Below is an example request body of the API call for creating a new customer group.

{
  "personGroupCode": "BUSINESS",
  "description": "Premium customers"
}

curl -L 'https://person-api.sandbox.tuumplatform.com/api/v1/person-group-types' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTlUMjA6NDQ6MTIiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODcyMDc0NTJ9.KsLN7WxZ10oCLe9pEHKaUP6mcqIjCXVazamMZpIEYQE' \
-H 'Content-Type: application/json' \
-d '{
  "personGroupCode": "BUSINESS",
  "description": "Premium customers"
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

A new BUSINESS customer group is created.

Use case

In this use case, we will review how to download an account transactions report.

Sample API call

To find the status of the requested report, make the following API call. reports-api.sandbox.tuumplatform.com/ /api/v1/generations/files/{generationFileId}

Sample request

Below is an example request of the API call to get the report file.

curl --location 'https://reports-api.sandbox.tuumplatform.com/api/v1/generations/files/ID-2864' \
--header 'x-channel-code: system' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEyMzgiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjUtMDMtMDdUMjM6MTQ6NTkiLCJleHAiOjE3NDEzODkyOTksInJvbGVzIjpbIkFDQ09VTlRBTlQiLCJBRE1JTiJdfQ.M_9PeWkEX4izXTAhYPNzj68FrMxB7gFJ7Zum9VPECKE' \
--data ''

Sample response

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

[{"transactionId":"ID-275388","groupId":"290379","postingDate":"2029-04-01","valueDate":"2029-04-01","accountId":"ID-12333","transactionTypeCode":"ACC_ADM_FEE","transactionSubtypeCode":null,"transactionGroupCode":"FEE","directionCode":"OUT","transactionAmount":{"amount":5.00,"currencyCode":"EUR"},"initialBalanceAmount":{"amount":-5.00,"currencyCode":"EUR"},"filingCode":"2029040100275388","source":{"sourceName":"ACCOUNT.ACCOUNT_PERIODIC_FEE","sourceRef":"ID-78253"},"contractSource":null,"counterparty":null,"details":"Account maintenance fee","referenceNumber":null,"metaInfo":null,"merchantInfo":null,"transactionDTime":"2025-02-28T11:23:58.16Z","reversedTransactionId":null,"endToEndId":null,"paymentServiceProviderCode":null,"virtualAccountId":null,"labels":[],"uniqueIdentifier":"1f78c038-96a6-4882-925e-ce8cd2668220","reportDateType":"POSTING_DATE","domainCode":"ACMT","familyCode":"MDOP","subfamilyCode":"FEES","reversed":false}, {"transactionId":"ID-1005","groupId":"1005","postingDate":"2024-06-11","valueDate":"2024-06-11","accountId":"ID-1006","transactionTypeCode":"ACC2SEPA_PAY","transactionSubtypeCode":null,"transactionGroupCode":"PAYMENT","directionCode":"OUT","transactionAmount":{"amount":1.00,"currencyCode":"EUR"},"initialBalanceAmount":{"amount":20000.00,"currencyCode":"EUR"},"filingCode":"2024061100001005","source":{"sourceName":"PAYMENT","sourceRef":"PAYM-1000"},"contractSource":null,"counterparty":{"name":"Simon Parker","accountNumber":{"value":"EE871275295834652820","type":"IBAN"},"accountNumberSubtype":null,"accountNumberCountryCode":"EE","financialInstitutionId":{"value":"PARXEE22XXX","type":"BIC"}},"details":"test","referenceNumber":null,"metaInfo":"{\"paymentResidencyCountryCode\":\"LV\",\"intrabankPaymentSource\":null,\"paymentMetaInfo\":\"[{\\\"typeCode\\\":\\\"SELECTED_SCHEME\\\",\\\"value\\\":\\\"SEPA_REGULAR\\\"}]\"}","merchantInfo":null,"transactionDTime":"2024-06-11T07:13:38.232717Z","reversedTransactionId":null,"endToEndId":null,"paymentServiceProviderCode":"SEPA","virtualAccountId":null,"labels":["COUNTERPARTY_EE","SEPA_REGULAR"],"uniqueIdentifier":"294ecf20-0e7f-46f8-9abe-3f4e040313bc","reportDateType":"POSTING_DATE","domainCode":"PMNT","familyCode":"ICDT","subfamilyCode":"OTHR","reversed":false}]

Result

As a result, the generated account transactions report was dowloaded.

Use case

In this use case we will activate a new deposit product that was created as a previous step.

Sample API call

To activate a deposit product, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v1/deposits/product/{depositTypeCode}/activate

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

As a result, the PREMIUM deposit product was activated.

Reports flow

If you need to generate and download the report, follow these steps:

1. Request to generate a report.

2. Check the report generation status.

3. Download the requested report.

For more detailed information about the report's workflow, see the example of account transactions report below.

Account transactions report

You can generate an accounts transactions report in CSV or JSON format by following these steps:

In this example, you can learn how to replace all roles and their privileges in the target Tuum environment.

As a precondition to import, first export all roles and associated privileges by making the API call, as shown in the example of exporting selected roles with an empty request body.

Use case

In this example, we showcase the steps to replace all roles and associated privileges in the target environment using the data retrieved in your export roles request.

Sample API calls

To import all roles and privileges, make the following API call with the roles and associated privileges (exported before) in the request body.

https://auth-api.{another-environment}.tuumplatform.com/api/v1/roles/privileges/import

Result

All valid roles and their privileges in the target environment have been replaced with roles and associated privileges exported from the source environment.

Use case

In this example, we will review how to deactivate a deposit product.

Sample API call

To deactivate a deposit product, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v1/deposits/product/{depositTypeCode}/deactivate

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

As a result, the PREMIUM deposit product was deactivated.

Instructions in this section will help you to manage deposit products throughout their lifecycle.

Below you will find the following chapters:

In this block, you will find the most common use cases that explain how to manage an active deposit contract.

Below you will find the following sections:

In this section, you will find instructions on how to create the following types of outgoing payments:

Here, you can learn how to make an API call to refresh a valid JSON Web Token. Once you execute the call successfully, you will receive a JSON Web Token with new expiration time.

Sample API call

To refresh a valid JSON Web Token, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/authorise/refresh

Sample request

Below is an example request body of the API call to refresh a valid JSON Web Token.

Sample response

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

Result

The response will contain a fresh JSON Web Token with an updated expiration time.

Use case

In this use case, we will create a new employee with the following data set:

Sample API call

To create a new employee, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/employees

Sample request

Below is an example request body of the API call for creating an employee.

Sample response

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

Result

As a result, a new employee with the employeeId: ID-1183 was created.

Here, you can learn how to make an API call to invalidate customer credentials. Once the call succeeds, your customer cannot authenticate using the invalidated credentials.

Sample API call

To create customer credentials, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/credentials/invalidate

Invalidate customer credentials

POST https://auth-api.sandbox.tuumplatform.com/api/v1/credentials/invalidate

Learn more about the in the Tuum developer portal.

Sample request

Below is an example request body of the API call to invalidate customer credentials.

Sample response

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

Result

After making the API call, the customer's credentials become invalid, making it impossible to authenticate themselves.

Use case

Learn how to find a particular person's addresses in Tuum. In this example, we will demonstrate it on a private person using the following data.

Sample API call

To retrieve customer data, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3392/addresses

Sample request

Below is an example request of the API call to retrieve person addresses.

Sample response

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

Result

The result of the API call is the overview of the addresses linked to the person.

Use case

In this example, we will review how to find a deposit offer using the application ID.

Sample API call

To find a deposit offer that was automatically created by the deposit application, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/applications/{applicationId}/offers

Sample response

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

Result

As an outcome, we found the deposit offer ID ID-1696407305 and fetched related details.

This guide will help you find details about an individual or a legal entity.

The endpoint provides a detailed overview of the person from various APIs.

The endpoint provides person's address details.

Based on your use case, use either of the endpoints to retrieve person data:

To use Tuum's API, you must first authenticate. Once you have completed the authentication process, you will receive a . This token allows you to make authorised API calls within the Tuum system.

Tuum has two different API endpoints for authentication:

1. ,

2. .

You must choose the authentication endpoint applicable to the context in which you will make API requests.

• When making API requests for your employees, select the authentication endpoint for employees.

• When making API requests for your customers, select the authentication endpoint for customers.

In this part of the API cookbook, you will find:

Use case

In this example, we will review how to forget a person record forever and make it unrecoverable.

Sample API call

To remove the restoration key, make the following call.

https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3415/forget/key

Sample request

Below is an example request to remove the restoration key call.

Sample response

The remove restoration key endpoint generates the following response.

Result

The restoration key of a forgotten person ID-3415 is removed. The personal data that belong to the person is non-recoverable.

Here, you can learn how to make an API call to create customer credentials. Once the call is successful, your customers can authenticate themselves using the created credentials.

Sample API call

To create customer credentials, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/credentials

Sample request

Below is an example request body of the API call to create customer credentials.

Sample response

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

Result

After making the API call, customer credentials will be created so that they can authenticate themselves.

Use case

Here we will review how to assign a person to the customer group. Let us assign a private person, Trevor Tuum, to a business customer group.

Sample API cal

To assign a person to the customer group, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3392/person-groups

Sample request

Below is the example body request of the API call for assigning a person to the group.

{
  "personGroupCode": "BUSINESS"
}

curl -L 'https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3392/person-groups' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMjFUMjE6Mjk6NDgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODczODI5ODh9.pPztGj-fAiRrRmZAOKYDuJSGrvZuUis59WKDAfcuE7A' \
-H 'Content-Type: application/json' \
-d '{
  "personGroupCode": "BUSINESS"
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "personGroupId": "ID-1489",
        "personId": "ID-3392",
        "personGroupCode": "BUSINESS",
        "validityRange": {
            "endTime": null,
            "startTime": "2023-06-21T20:48:57.250757Z"
        }
    }
}

Result

The user ID-3392 is assigned to the BUSINESS customer group.

Use case

In this example, we will review how to create an account class rule.

Sample API call

To create a new account type class rule, make the following API call.

https://account-api.sandbox.tuumplatform.com/api/v1/account-type-class-rules

Sample request

Below is an example request body of the API call for creating an account type class rule.

{
  "accountTypeCode": "INTERNAL",
  "accountClassCode": "NEW",
  "validityRange": {
    "startDate": "2023-07-31"
  }
}

curl --location 'https://account-api.sandbox.tuumplatform.com/api/v1/account-type-class-rules' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMzFUMTQ6Mjk6NTgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTA4MTM3OTh9.toMwogjfmBdNlD14soqIDPiZ6q1oF0dClO3hDFhJkHM' \
--header 'Content-Type: application/json' \
--data '{
  "accountTypeCode": "INTERNAL",
  "accountClassCode": "NEW",
  "validityRange": {
    "startDate": "2023-07-31"
  }
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "accountTypeCode": "INTERNAL",
        "accountClassCode": "NEW",
        "validityRange": {
            "startDate": "2023-07-31",
            "endDate": null
        },
        "accountTypeClassRuleId": "ID-1007"
    }
}

Result

A new account type class rule was created.

Use case

In this example, we will show how to create an account class code.

Sample API call

To create a new account class code, make the following API call.

https://account-api.sandbox.tuumplatform.com/api/v1/account-class-codes

Create account class code

POST https://account-api.sandbox.tuumplatform.com/api/v1/account-class-codes

See more information about this endpoint in the Tuum developer portal.

Sample request

Below is an example request body of the API call for creating an account class code.

{
  "description": "New account class code",
  "accountClassCode": "NEW"
}

curl --location 'https://account-api.sandbox.tuumplatform.com/api/v1/account-class-codes' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMzFUMTA6NTE6MzUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTA4MDA2OTV9.ocnwYQJzynRutWPRu-Jr_BmKkwRleeV5koMW_RbsNJ0' \
--header 'Content-Type: application/json' \
--data '{
  "description": "New account class code",
  "accountClassCode": "NEW"
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "description": "New account class code",
        "accountClassCode": "NEW"
    }
}

Result

A new account class code is created.

Use case

In this example, we will review how to accept a deposit offer.

Sample API call

To accept a deposit offer, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v2/offers/{offerId}/accept

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "offerId": "ID-1696407305",
        "personId": "ID-2660",
        "applicationId": "ID-1696407202",
        "depositGroupCode": "TIME_DEPOSIT",
        "depositTypeCode": "PREMIUM_TEST",
        "terminationType": "WITHOUT_INTEREST",
        "statusCode": "ACCEPTED",
        "reasonCode": null,
        "accountId": "ID-5334",
        "interestRate": 0.25,
        "period": 3,
        "periodTypeCode": "MONTH",
        "endDate": null,
        "initialMoney": {
            "amount": 5000.00,
            "currencyCode": "EUR"
        },
        "interestPaymentFreqCode": "END",
        "prolongationCode": null,
        "countryCode": "EE",
        "maturityDate": "2025-02-15",
        "returnAmount": {
            "amount": 5003.13,
            "currencyCode": "EUR"
        },
        "postingDate": "2024-11-15",
        "lastValidDate": "2024-11-16",
        "channelCode": "SYSTEM",
        "tenantCode": "MB",
        "contractHeaderId": null,
        "contractNumber": null,
        "depositClassCode": "PREMIUM_CUSTOMER",
        "payoutDetails": null,
        "personTypeCode": "P",
        "taxResidencyCountryCode": "EE",
        "taxExempt": false
    }
}

Result

As a result the deposit offer ID-1696407305 was accepted.

Use case

Here we will review how to create deposit class codes that can be used to define separate general ledger accounts for different deposit products. We will create a new deposit class code for the premium customers.

Sample API call

To create a new deposit class code, make the following API call.

deposit-api.sandbox.tuumplatform.com/api/v1/deposit-class-codes

Sample request

Below is an example request body of the API call for creating a deposit class code.

{
  "description": "Class code for premium customers",
  "depositClassCode": "PREMIUM_CUSTOMER"
}

curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/deposit-class-codes' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDItMjJUMTc6MDE6MTciLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MDg2MjEyNzd9.XD_GcGtj3ArKvsM2OxUKKhBNmhQ-TA5RcjmKxTR2fkA' \
--header 'Content-Type: application/json' \
--data '{
  "description": "Class code for premium customers",
  "depositClassCode": "PREMIUM_CUSTOMER"
}'

Sample response

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

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "description": "Class code for premium customers",
        "depositClassCode": "PREMIUM_CUSTOMER"
    }
}

Result

As an outcome, a new deposit class code for premium customers was created.

Use case

After confirming a SEPA payment, we will check that the credit transfer exists using SEPA API with the payment ID.

Sample API call

To find the payment, use the following endpoint:

https://sepa-api.sandbox.tuumplatform.comapi/v1/batch/PAYM-8813/settlement-transactions

Sample response

Below you will find the response to the sample request:

{
  "errors": null,
  "validationErrors": null,
  "data": [
    {
      "transactionId": "ID-11941",
      "txId": "ID-11940",
      "paymentId": null,
      "settlementTransactionType": "CREDIT_TRANSFER",
      "messageName": null,
      "reason": null,
      "status": "ACCEPTED",
      "event": null,
      "createdEventTime": "2023-07-12T12:59:19.613712Z",
      "relatedMessage": null,
      "fileReference": "CT00000000013062",
      "fileHeaderId": "ID-13143",
      "sepaScheme": "REGULAR",
      "latestEvent": "CT_ACCEPTED",
      "latestEventDateTime": null,
      "settlementDate": "2023-07-12",
      "amount": {
        "amount": 2,
        "currencyCode": "EUR"
      },
      "directionCode": "OUT"
    }
  ]
}

Result

With this request, we can see the credit transfer details in the response such as the transaction ID, the file reference number, and the status code of the transaction.

To protect your POST requests against duplicating, you can use the optional header parameter x-request-id - request ID.

Below we will provide examples to show the difference in the API call outcomes with and without the request ID header parameter.

Use case

We will review several examples that illustrate the difference in the API outcomes when the request ID is used and when the request ID is not applied.

The initial request data:

Explanatory examples

To view the examples, go to the following pages:

Summary

From the illustrated examples we can see that when the x-request-id parameter is applied, it prevents the system from creating new objects. And when the x-request-id is not used or is used with unique value as per each call, all the POST calls are treated as unique and new objects are created:

Usage recommendations

If you use the x-request-id header parameter, it is recommended to avoid reusing the same parameter value, even if the requests are made to different Tuum APIs.

Use case

Here we will cover how to add additional contacts to a legal person that can be used to reach out to different departments like accounting, fraud, risk etc. We will add fraud department contacts to New company Ltd.

Sample API call

To add additional contact to the person, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3394/additional-contacts

Sample request

Below is an example request body of the API call for creating additional contacts.

Sample response

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

Result

A new fraud department contact is added to the person.

Use case

In this example, we will review how to set up an account limit code. This parameter gives a name and description of the account limit that will be configured in the further articles.

Sample API call

To create a new account limit code, make the following call.

Create account limit code

https://account-api.sandbox.tuumplatform.com/api/v1/limits/codes

See more information about this in the Tuum developer portal.

Sample request

Below is an example body request of the API call for creating an account limit code.

Sample response

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

Result

A new limit code NEW_ACCOUNT_LIMIT is created and enabled. This parameter will be used for setting up an account limit type.

Use case

In this example, we will review how to request to generate account transactions report.

Sample API call

To request account transaction report, make the following call.

https://account-api.sandbox.tuumplatform.com/api/v4/accounts/{accountId}/transactions/export

Sample request

In the sample below you will find information on how to request an account transactions report.

Sample response

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

Result

As a result, an account transaction report was requested.

Sample account transaction export file

Below, you will find a sample of transaction export file. This way the file is structured after being .

Use case

Here, we will create a single currency account limit type with the account scope.

Sample API call

To create an account limit type, make the following call.

https://account-api.sandbox.tuumplatform.com/api/v1/limits/types

Sample request

Below is an example request body of the API call for creating an account and setting access rights.

Sample response

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

Result

A new single currency account limit type is created - ID-1002. In the , we will assign this limit type to an existing account and define the limit amount.

Use case

In this use case, we will review a situation when a person - Rhys Davey with personId ID-3204, who has the account inactivated, requested the bank to remove the personal data. To complete this request, you can initiate the forget person process.

Sample API call

To initiate the forget person process, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/forget/start

Sample request

Below is an example request body of the forget person API call.

Sample response

The forget person generates the following response.

Result

As an outcome, the personal data of Rhys Davey ID-3204 is forgotten.

Use case

Here, you can learn how to reactivate a person who is in INACTIVE status. We will reactivate a private person, Rhys Davey, who was inactivated previously, but has now returned as a client.

The by default processReason-s for private and legal persons:

• ERROR,

• OTHER.

Sample API call

To reactivate a person, make the following API call.

https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/reactivate/start

Sample request

Below is an example request body of the API call to inactivate a person.

Sample response

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

Result

The person's status is changed to PENDING. The person can be activated with endpoint.

Use case

In this example, we will review how to check the status of a requested report file.

Sample API call

To find the status of the requested report, make the following API call.

reports-api.sandbox.tuumplatform.com/ api/v2/generations/{generationId}

Sample request

Below is an example request of the API call to find report status.

Sample response

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

Result

This endpoint returns the status of the account transactions report. When the statusCode has a value DONE, the report is ready for . In this example, the generationFileId of the report file is ID-2864.

Use case

In this example, we will review how to find an employee by username.

Sample API call

To find an employee by username, make the following API call.

https://auth-api.sandbox.tuumplatform.com/api/v1/employees/{employeeId}

Sample request

Below is an example request of the API call to retrieve customer data.

Sample response

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

Result

The result of the API call is the dataset of a particular employee.

Use case

In this example, we will find the .

Sample API call

deposit-api.sandbox.tuumplatform.com/api/v1/deposits/product/{depositTypeCode}

Sample response

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

Result

As a result, a complete set of product details about the PREMIUM deposit product was returned.

Use case

In this example, we will review how to decline a deposit offer.

Sample API call

deposit-api.sandbox.tuumplatform.com/api/v3/offers/{offerId}/decline

Sample request

Below is an example request body of the API call for declining a deposit offer.

Sample response

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

Result

As a result, a deposit offer ID-1718023943 was declined.

Use case

We will use the AML API to find the AML-related information of a payment.

Sample API call

To find the AML details, use the following endpoint:

https://aml-api.sandbox.tuumplatform.com/api/v1/aml/process/by-payment?paymentId=PAYM-8834

Sample response

Below you will find the response to the sample request:

Result

With this request, we can see the AML status of the payment.

After and for a quote request, we will initiate the FX order. Initiating refers to confirming the FX request which creates an FX order.

Use case

We will confirm an FX request that we created.

Sample API call

To confirm the FX request, use the following endpoint:

https://payment-api.sandbox.tuumplatform.com/api/v1/accounts/ID-1026/fx-quotes/ID-1263/confirm/ID-1217

Sample response

Below you will find the response to the sample request:

Result

We have now confirmed the FX request and created a quote order which is in the status WAITING_FOR_PROCESSING. After the quote order is processed successfully by the service provider (in this case, Banking Circle), the status of the order is CONFIRMED.