Couldn't generate the PDF for 200 pages, generation stopped at 100.
1 of 100
About authentication Tuum has two different API endpoints for authentication:
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:
To use Tuum's API, you must first authenticate. Once you have completed the authentication process, you will receive a
Import selected roles In this example, you can learn how to add specific roles and their privileges to the target Tuum environment.
Use case
Use case data
API parameters with values
The role codes we're importing roles and privileges for are: ACCOUNTANT and TEST_LT.
In this example, the role ACCOUNTANT already existed in the target environment, but role TEST_LT is a new role.
The system will import only roles and associated privileges with a valid validity range .
Sample API call
To import specific roles and associated privileges to the target environment, make the following API call.
Ensure the target environment for the import is different from the export environment.
Sample request
Below is an example request body of the API call for import roles.
JSON
Copy {
"rolesWithPrivileges": [
{
"roleCode": "ACCOUNTANT",
"privilegeNames": [
"ADD_PERSON",
"APPROVE_APPLICATIONS",
"DISBURSE_LOAN",
"EDIT_CONTRACT",
"EDIT_LOAN_PRODUCTS",
"EDIT_PERSON",
"MANAGE_USERS",
"SEARCH_CONTRACT_DOCUMENTS",
"VIEW_GL_JOURNAL",
"VIEW_LOAN_CONTRACT",
"VIEW_LOAN_PRODUCTS",
"VIEW_PERSON",
"VIEW_EXTERNAL_CONTRACTS",
"VIEW_PERSON_GROUP_TYPE",
],
"valid": true
},
{
"roleCode": "TEST_LT",
"privilegeNames": [
"MANAGE_USERS",
"READ_RESTRICTED_DATA",
"Test_LT",
"VIEW_FOUREYE_REVIEW_RULE",
"VIEW_REVIEW_APPROVALS_CONFIGURATION",
"VIEW_PERSON",
"VIEW_EXTERNAL_CONTRACTS",
"VIEW_PERSON_GROUP_TYPE",
],
"valid": true
}
]
} cURL
Copy curl --location --request PATCH 'https://target-environemnt.tuumaplatform.com/api/v1/roles/privileges/import' \
--header 'Accept-Language: en-GB' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGF1cmEgVGVlbcOkZ2kiLCJlbXBsb3llZUlkIjoiSUQtMTM0OCIsInRlbmFudENvZGUiOiJNQiIsImV4cGlyeURUaW1lIjoiMjAyNS0wMy0yMFQxMzoxODowMCIsImV4cCI6MTc0MjQ3NjY4MCwicm9sZXMiOlsiQURNSU4iXX0.FsBEnzSkQdNXqBcl3C2BuPs1OsyYyIBT-efAXyr8sqk' \
--header 'Content-Type: application/json' \
--data '{
"rolesWithPrivileges": [
{
"roleCode": "ACCOUNTANT",
"privilegeNames": [
"ADD_PERSON",
"APPROVE_APPLICATIONS",
"DISBURSE_LOAN",
"EDIT_CONTRACT",
"EDIT_LOAN_PRODUCTS",
"EDIT_PERSON",
"MANAGE_USERS",
"SEARCH_CONTRACT_DOCUMENTS",
"VIEW_GL_JOURNAL",
"VIEW_LOAN_CONTRACT",
"VIEW_LOAN_PRODUCTS",
"VIEW_PERSON",
"VIEW_PERSON_ADDITIONAL_CONTACT",
"VIEW_PERSON_GROUP_TYPE"
],
"valid": true
},
{
"roleCode": "TEST_LT",
"privilegeNames": [
"MANAGE_USERS",
"READ_RESTRICTED_DATA",
"VIEW_EXTERNAL_CONTRACTS",
"VIEW_FOUREYE_REVIEW_RULE",
"VIEW_PERSON",
"VIEW_PERSON_GROUP_TYPE",
"VIEW_REVIEW_APPROVALS_CONFIGURATION"
],
"valid": true
}
]
}
' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
The selected valid roles ACCOUNTANT and TEST_LT with related privileges have been imported.
We will import specific roles and associated privileges using the data retrieved in the previous
The roles and privileges combination was obtained from the
https://auth-api.target-environment.tuumplatform.com/api/v1/roles/privileges/import
Learn more about the
Copy rolesWithPrivileges": [
{
"roleCode": "ACCOUNTANT",
"privilegeNames": [
"ADD_PERSON",
"APPROVE_APPLICATIONS",
"DISBURSE_LOAN",
"EDIT_CONTRACT",
"EDIT_LOAN_PRODUCTS",
"EDIT_PERSON",
"MANAGE_USERS",
"SEARCH_CONTRACT_DOCUMENTS",
"VIEW_GL_JOURNAL",
"VIEW_LOAN_CONTRACT",
"VIEW_LOAN_PRODUCTS",
"VIEW_PERSON",
"VIEW_PERSON_ADDITIONAL_CONTACT",
"VIEW_PERSON_GROUP_TYPE"
],
"valid": true
},
{
"roleCode": "TEST_LT",
"privilegeNames": [
"MANAGE_USERS",
"READ_RESTRICTED_DATA",
"VIEW_EXTERNAL_CONTRACTS",
"VIEW_FOUREYE_REVIEW_RULE",
"VIEW_PERSON",
"VIEW_PERSON_GROUP_TYPE",
"VIEW_REVIEW_APPROVALS_CONFIGURATION"
],
"valid": true
} Export-import roles 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.
Export selected roles In this example, you can learn how to retrieve specific roles and their privileges from the source Tuum environment.
Use case
In this example, we will export specific roles and privileges.
Use case data
API parameters with values
The role codes we're exporting roles and privileges for are: ACCOUNTANT and TEST_LT.
The system will export only roles and associated privileges with a valid validity range .
Sample API call
To export specific roles and privileges, make the following API call.
Sample request
Below is an example request body of the API call for export roles.
JSON
Copy {
"roleCodes": [
"ACCOUNTANT",
"TEST_LT"
]
} cURL
Copy curl --location 'https://auth-api.sandbox.tuumplatform.com/api/v1/roles/privileges/export' \
--header 'Accept-Language: en-GB' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGF1cmEgVGVlbcOkZ2kiLCJlbXBsb3llZUlkIjoiSUQtMTA1MCIsInRlbmFudENvZGUiOiJNQi5FVSIsImV4cGlyeURUaW1lIjoiMjAyNS0wMy0xOFQxMDo0NjoxMSIsImV4cCI6MTc0MjI5NDc3MSwicm9sZXMiOlsiQURNSU4iXX0.zD1buC7eTHM0cDgGMhThq1II6TUY3DdmfrHzDphcBdE' \
--header 'Content-Type: application/json' \
--data '{
"roleCodes": [
"ACCOUNTANT",
"TEST_LT"
]
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"rolesWithPrivileges": [
{
"roleCode": "ACCOUNTANT",
"privilegeNames": [
"ADD_PERSON",
"APPROVE_APPLICATIONS",
"DISBURSE_LOAN",
"EDIT_CONTRACT",
"EDIT_LOAN_PRODUCTS",
"EDIT_PERSON",
"MANAGE_USERS",
"SEARCH_CONTRACT_DOCUMENTS",
"VIEW_GL_JOURNAL",
"VIEW_LOAN_CONTRACT",
"VIEW_LOAN_PRODUCTS",
"VIEW_PERSON",
"VIEW_PERSON_ADDITIONAL_CONTACT",
"VIEW_PERSON_GROUP_TYPE"
],
"valid": true
},
{
"roleCode": "TEST_LT",
"privilegeNames": [
"MANAGE_USERS",
"READ_RESTRICTED_DATA",
"VIEW_EXTERNAL_CONTRACTS",
"VIEW_FOUREYE_REVIEW_RULE",
"VIEW_PERSON",
"VIEW_PERSON_GROUP_TYPE",
"VIEW_REVIEW_APPROVALS_CONFIGURATION"
],
"valid": true
}
]
}
} Result
The selected valid roles ACCOUNTANT and TEST_LT with related privileges have been exported.
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.
The export and import functionality is restricted to users with the EXPORT_IMPORT_ROLE_PRIVILEGES privilege. Learn
https://auth-api.sandbox.tuumplatform.com/api/v1/roles/privileges/export
Learn more about the
Copy "roleCodes": [
"ACCOUNTANT",
"TEST_LT"
] Import all roles In this example, you can learn how to replace all roles and their privileges in the target Tuum environment.
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.
The system will import only roles and privileges with a valid validity range .
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.
Result
All valid roles and their privileges in the target environment have been replaced with roles and associated privileges exported from the source environment.
As a precondition to import, first export all roles and associated privileges by making the API call, as shown in the empty request body .
Use case data
API parameters with values
We want to import all roles to the target environment and thus we have to use the roles and privileges from the response of the export done before.
https://auth-api.{another-environment}.tuumplatform.com/api/v1/roles/privileges/import
Learn more about the
Copy All roles and privileges from the
response of the export done before. Authenticate customer 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.
Sample request
Below is an example request body of the API call for authentication of a customer.
JSON
Copy {
"username": "customer_username",
"password": "customer_password"
} cURL
Copy curl 'https://auth-api.sandbox.tuumplatform.com/api/v1/authorise' \
-H 'Content-Type: application/json' \
-d '{
"username": "customer_username",
"password": "customer_password"
}'
Please make sure to input the username and password of the particular customer when submitting your request.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiYWF0b21payIsInBlcnNvbklkIjoiSUQtMTAzOCIsInRlbmFudENvZGUiOiJNQiIsImV4cGlyeURUaW1lIjoiMjAyMy0wNy0yOFQxMjoyMDoyMSIsImV4cCI6MTY5MDU0NjgyMX0.wpNOfTan73vnqQNZo5cI99B2NWuVZ6wurW9JiO7z0x0"
}
} Result
An customer is authenticated, and a JSON Web Token is returned in the response.
https://auth-api.sandbox.tuumplatform.com/api/v1/authorise
Learn more about the
If your customer doesn't have login details, you can create them following the instructions provided in the
Optional parameters 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:
Use case data
API parameters with values
Person's Tuum id is ID-3419.
The name of the account holder is Eleanor Rigby.
Eleanor is a resident of Great Britain.
The standard price list is assigned to the account.
Eleanor is assigned to the GROUP_A customer group.
The account currency code is GBP.
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:
POST call / Request ID
Same request ID
No or unique request ID
Same as in the initial response
Duplicated POST with updated data
Same as in the initial response
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.
Refresh JSON Web Token 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.
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.
The request ID value must be in the format of a Universally Unique IDentifier (UUID),
https://auth-api.sandbox.tuumplatform.com/api/v1/authorise/refresh
Learn more about the
Copy .../persons/ID-3419/accounts
Copy "personName": "Eleanor Rigby"
Copy "residencyCountryCode": "GB"
Copy "priceListTypeCode": "STANDARD"
Copy "customerGroupCode": "GROUP_A"
Copy "accountTypeCode": "CURRENCY"
Copy "currencyCode": "GBP"
Copy https://auth-api.sandbox.tuumplatform.com/api/v1/authorise/refresh
Copy curl -X POST 'https://auth-api.sandbox.tuumplatform.com/api/v1/authorise/refresh' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMjhUMTA6MDM6MjEiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTA1Mzg2MDF9.vOLapdiXflbGV4c2pJnziQzgJzP1MYPPBcdk4wIZdoM' \
-d ''
Copy {
"errors": null,
"validationErrors": null,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMjhUMTA6MDM6MjEiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTA1Mzg2MDF9.vOLapdiXflbGV4c2pJnziQzgJzP1MYPPBcdk4wIZdoM"
}
} Mandatory parameters To perform an authorised API call, you must use two header parameters.
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
Copy -H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDMtMDhUMDg6NDg6NDkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2NzgyNjUzMjl9.G7rqNTJbeyMdMy1ZGwu1G7JRSvwAg084IiBYhOEz4I8' x-channel-code
Use one of the following values for the x-channel-code HTTP header parameter:
SYSTEM- to perform API calls with the x-auth-token of the digital identity of your employee.
SELFSERVICE- to perform API calls with the x-auth-token of the digital identity of the authenticated customer.
Example cURL with employee token
Copy -H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDMtMDhUMDg6NDg6NDkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2NzgyNjUzMjl9.G7rqNTJbeyMdMy1ZGwu1G7JRSvwAg084IiBYhOEz4I8' \
-H 'x-channel-code: SYSTEM' Example cURL with customer token
Copy -H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiYWF0b21payIsInBlcnNvbklkIjoiSUQtMTAzOCIsInRlbmFudENvZGUiOiJNQiIsImV4cGlyeURUaW1lIjoiMjAyMy0wNy0yOFQxMjoyMDoyMSIsImV4cCI6MTY5MDU0NjgyMX0.wpNOfTan73vnqQNZo5cI99B2NWuVZ6wurW9JiO7z0x0' \
-H 'x-channel-code: SELFSERVICE' Authenticate employee 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.
Sample request
Below is an example request body of the API call for authentication of an employee.
JSON
Copy {
"username": "employee_username",
"password": "employee_password"
} cURL
Copy 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"
}'
Please make sure to input the username and password of the particular employee when submitting your request.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDMtMDhUMDg6NDg6NDkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2NzgyNjUzMjl9.G7rqNTJbeyMdMy1ZGwu1G7JRSvwAg084IiBYhOEz4I8"
}
} Result
An employee is authenticated, and a JSON Web Token is returned in the response.
Invalidate customer credentials 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.
Invalidate customer credentials
POST https://auth-api.sandbox.tuumplatform.com/api/v1/credentials/invalidate
Sample request
Below is an example request body of the API call to invalidate customer credentials.
JSON
Copy {
"personId": "ID-1038",
"username": "customer_username",
"password": "customer_password"
} cURL
Copy curl 'https://auth-api.sandbox.tuumplatform.com/api/v1/credentials/invalidate' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMjhUMTM6MjE6MTYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTA1NTA0NzZ9.KFAC4t3rgo6Cc2yr9V2-h6ZfgOyKLXyI9u22FLa_gvQ' \
-H 'Content-Type: application/json' \
-d '{
"personId": "ID-1038",
"username": "customer_username",
"password": "customer_password"
}'
Please make sure to input the username and password of the particular customer when submitting your request.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
After making the API call, the customer's credentials become invalid, making it impossible to authenticate themselves.
About cookbooks Getting started
We have organised API cookbooks by grouping them per business domain. So, for example, you can find detailed instructions about authentication-related use cases in the authentication group , account-related ones in the account group and payment-related in the payment group . Just proceed to any cookbook to get the left-hand menu with all cookbooks displayed to find the one of your interest.
Shortcuts to cookbooks
Here you can find the shortcuts to the API recipes:
Create customer credentials 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.
Sample request
Below is an example request body of the API call to create customer credentials.
JSON
Copy {
"personId": "ID-1038",
"username": "customer_username",
"password": "customer_password"
} cURL
Copy curl 'https://auth-api.sandbox.tuumplatform.com/api/v1/credentials' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiYWF0b21payIsInBlcnNvbklkIjoiSUQtMTAzOCIsInRlbmFudENvZGUiOiJNQiIsImV4cGlyeURUaW1lIjoiMjAyMy0wNy0yOFQxMjoyMDoyMSIsImV4cCI6MTY5MDU0NjgyMX0.wpNOfTan73vnqQNZo5cI99B2NWuVZ6wurW9JiO7z0x0' \
-H 'Content-Type: application/json' \
-d '{
"personId": "ID-1038",
"username": "customer_username",
"password": "customer_password"
}'
Please make sure to input the username and password of the particular customer when submitting your request.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"credentialId": "ID-1005",
"personId": "ID-1038",
"username": "customer_username",
"tenantId": "ID-1000"
}
} Result
After making the API call, customer credentials will be created so that they can authenticate themselves.
Find employee by username 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.
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.
Create private person Use case
Here, you can learn how to create a record of a person (record of your customer) in Tuum. In this example, we will showcase the creation of a record of a private person with the following data.
Sample API call
To create a record of a person, make the following API call.
Sample request
Below is an example request body of the API call for creating a private person.
When using the example request, please change the x-auth-token to the one you obtained with your authentication API call.
Sample response
Below you find an example response body to the API call above.
Result
A new private person ID-3726 is created and activated. The new person record is available for further actions.
Create employee 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.
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.
About header parameters 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:
https://auth-api.sandbox.tuumplatform.com/api/v1/employees/authorise
Learn more about the
https://auth-api.sandbox.tuumplatform.com/api/v1/credentials/invalidate
Learn more about the
Learn more about the
To make a successful API call, you must include the JSON Web Token of the authenticated employee with specific user rights as a header parameter with the value of x-auth-token. Kindly adhere to the instructions given in the explanations for
Hello, and welcome to the Tuum API cookbooks. Here you can get detailed instructions on how to use Tuum API endpoints to achieve your desired outcome. It is a complementary page to the
https://auth-api.sandbox.tuumplatform.com/api/v1/credentials
Learn more about the
To make a successful API call, you must include the JSON Web Token of the authenticated employee with specific user rights as a header parameter with the value of x-auth-token. Kindly adhere to the instructions given in the explanations for
Use case data
API parameters with values
https://auth-api.sandbox.tuumplatform.com/api/v1/employees/{employeeId}
Learn more about the
Use case data
API parameters with values
https://person-api.sandbox.tuumplatform.com/api/v2/persons
Learn more about the
Use case data
API parameters with values
https://auth-api.sandbox.tuumplatform.com/api/v1/employees
Learn more about the
We will search for the employee with the test.employee@bank.com username.
...api/v1/employees/username?username=test.employee@bank.com
Copy curl --location 'https://auth-api.sandbox.tuumplatform.com/api/v1/employees/username?username=test.employee%40bank.com' \
--header 'x-channel-code: BACKOFFICE' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjUtMDEtMDZUMjI6MzA6MjIiLCJleHAiOjE3MzYyMDI2MjIsInJvbGVzIjpbIkFETUlOIl19.N67SgRQZXpJHFCh-Ea6oAyQjlq86kl8vUkEyokn6bDw' \
--data ''
Copy {
"errors": null,
"validationErrors": null,
"data": {
"employeeId": "ID-1183",
"firstName": "Test",
"lastName": "Employee",
"username": "test.employee@bank.com",
"email": "test.employee@bank.com",
"authenticationMethod": "PASSWORD",
"defaultTenantCode": "MB",
"roles": [
"CUSTOMER_SERVICE"
],
"tenants": [
{
"tenantEmployeeId": "ID-1213",
"defaultTenant": true,
"tenantId": "ID-1000",
"tenantCode": "MB",
"roles": [
"CUSTOMER_SERVICE"
]
}
],
"externalId": null,
"lastLogin": "2024-11-25T12:28:04.635156Z",
"blockedUntil": null,
"failedAttempts": 0
}
}
Copy "personTypeCode": "P" The person's name is Trevor Tuum
Copy "surname": "Tuum",
"givenName": "Trevor" The person's United Kingdom identification number is QQ123456B
Copy "identificationNumbers": [
{
"idNumber": "QQ123456B",
"idCountryCode": "GB",
"primary": true
}
] The person's registration address is United Kingdom
85 Park end St
Broomhill
NE65 0YW
Copy "addresses": [
{
"addressTypeCode": "R",
"countryCode": "GB",
"cityCounty": "Broomhill",
"street1": "85 Park End St",
"zip": "NE65 0YW"
}
]
Copy {
"personTypeCode": "P",
"surname": "Tuum",
"givenName": "Trevor",
"identificationNumbers": [
{
"idNumber": "QQ123456B",
"idCountryCode": "GB",
"primary": true
}
],
"addresses": [
{
"addressTypeCode": "R",
"countryCode": "GB",
"cityCounty": "Broomhill",
"street1": "85 Park End St",
"zip": "NE65 0YW"
}
]
}
Copy curl --location 'https://person-api.dev.tuum.xyz/api/v2/persons' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjUtMDEtMTRUMTU6MDA6MzQiLCJleHAiOjE3MzY4NjY4MzQsInJvbGVzIjpbIkFETUlOIl19.Y80MTpnA-h5xQ-8W194W0h-I8SbhgOJoZApPbREBB-0' \
--header 'x-channel-code: SYSTEM' \
--header 'Content-Type: application/json' \
--data '{
"personTypeCode": "P",
"surname": "Tuum",
"givenName": "Trevor",
"identificationNumbers": [
{
"idNumber": "QQ123456B",
"idCountryCode": "GB",
"primary": true
}
],
"addresses": [
{
"addressTypeCode": "R",
"countryCode": "GB",
"cityCounty": "Broomhill",
"street1": "85 Park End St",
"zip": "NE65 0YW"
}
]
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personId": "ID-3726",
"statusCode": "ACTIVE",
"source": null,
"tenantCode": "MB",
"forgotten": false,
"legalForm": null,
"creationDate": "2025-01-14",
"personalInfo": {
"personTypeCode": "P",
"givenName": "Trevor",
"middleName": null,
"surname": "Tuum",
"name": null,
"email": null,
"phoneNumber": null,
"phoneCountryCode": null,
"residencyCountryCode": null,
"sex": null,
"nationality": null,
"dependantPersons": null,
"legalForm": null
},
"additionalInfo": {
"birthDate": null,
"countryOfBirth": null,
"placeOfBirth": null,
"language": null,
"educationCode": null,
"maritalStatusCode": null,
"dependantPersons": null,
"taxResidencyCountry": null,
"usResident": false,
"pep": false,
"customerTypeCode": null,
"statusCodeReason": null,
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"tradingName": null,
"registrationDate": null,
"webAddress": null,
"pepExplanation": null,
"businessAreaCodes": [],
"businessModelDescription": null,
"intraOrgCode": null,
"counterpartySectorCode": null
},
"work": {
"activityCode": null,
"businessAreaCodes": [],
"employmentTimeCode": null,
"fixedEmploymentLength": null
},
"home": null,
"addresses": [
{
"addressId": "ID-4870",
"personId": "ID-3726",
"addressTypeCode": "R",
"street1": "85 Park End St",
"street2": null,
"cityCounty": "Broomhill",
"stateRegion": null,
"zip": "NE65 0YW",
"countryCode": "GB",
"moveInDate": null,
"validityRange": {
"endTime": null,
"startTime": "2025-01-14T14:21:58.145Z"
}
}
],
"documents": [],
"relationships": [],
"additionalContacts": [],
"personGroupCodes": [],
"identificationNumbers": [
{
"idNumberId": "ID-3715",
"personId": "ID-3726",
"idNumber": "QQ123456B",
"idCountryCode": "GB",
"validityRange": {
"endTime": null,
"startTime": "2025-01-14T14:21:58.291Z"
},
"primary": true
}
],
"taxNumbers": [],
"accessRestricted": false,
"fullName": "Trevor Tuum"
}
} We will create a record for a Test Employee.
Copy "username": "test.employee@bank.com",
"email": "test.employee@bank.com",
"firstName": "Test",
"lastName": "Employee" Test Employee is a Customer Support representative.
Copy "roles": [
"CUSTOMER_SERVICE"
] The employee password must be 12 to 20 characters long and contain one upper-case letter, one digit, and one special character.
Copy "password": "Vys%k6;)#,bab" The name of the tenant where new employee is created.
Copy {
"username": "test.employee@bank.com",
"email": "test.employee@bank.com",
"firstName": "Test",
"lastName": "Employee",
"roles": [
"CUSTOMER_SERVICE"
],
"password": "Vys%k6;)#,bab",
"tenantCode": "BANK"
}
Copy curl --location 'https://auth-api.sandbox.tuumplatform.com/api/v1/employees' \
--header 'x-channel-code: BACKOFFICE' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTEtMjVUMTM6MDc6MTUiLCJleHAiOjE3MzI1NDAwMzUsInJvbGVzIjpbIkFETUlOIl19.zIFVF28Qu62-9V6xRJI_t1QpnWd4HdPpPSFx5FaepEM' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test.employee@bank.com",
"email": "test.employee@bank.com",
"firstName": "Test",
"lastName": "Employee",
"roles": [
"CUSTOMER_SERVICE"
],
"password": "Vys%k6;)#,bab",
"tenantCode": "BANK"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"employeeId": "ID-1183",
"firstName": "Test",
"lastName": "Employee",
"username": "test.employee@bank.com",
"email": "test.employee@bank.com",
"authenticationMethod": "PASSWORD",
"defaultTenantCode": "MB",
"roles": [
"CUSTOMER_SERVICE"
],
"tenants": [
{
"tenantEmployeeId": "ID-1213",
"defaultTenant": true,
"tenantId": "ID-1000",
"tenantCode": "BANK",
"roles": [
"CUSTOMER_SERVICE"
]
}
],
"externalId": null,
"lastLogin": "2024-11-25T12:28:04.635156Z",
"blockedUntil": null,
"failedAttempts": 0
}
} Requests without request ID Duplicated POST without request ID and the same data
We will make another API call without the request ID, but the data from the first call remains the same.
JSON
Copy {
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
} cURL
Copy curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTI6Mzk6MTgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNTI3NTh9.L6hz-vAyOWwTZ5z5e2aBpppxmwdhq7JqPVbOoC4n7Ak' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}' The response shows that the new account with accountId: ID-1293 was created and activated .
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1293",
"personId": "ID-3419",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-08-04",
"accountName": null,
"personName": "Eleanor Rigby",
"statusCode": "ACTIVE",
"iban": "GB16XXXX04030000001024",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1222",
"accountId": "ID-1293",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00001024",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1148",
"accountId": "ID-1293",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Duplicated POST without request ID but changed data
This time, we will make an additional API call without the request ID. However, we will change the currency from GBP to EUR.
JSON
Copy {
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "EUR"
} cURL
Copy curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTI6Mzk6MTgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNTI3NTh9.L6hz-vAyOWwTZ5z5e2aBpppxmwdhq7JqPVbOoC4n7Ak' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "EUR"
}' The response shows that the new account with accountId: ID-1294 was created and activated .
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1294",
"personId": "ID-3419",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-08-04",
"accountName": null,
"personName": "Eleanor Rigby",
"statusCode": "ACTIVE",
"iban": "XX61XXXX99999000000000000001325",
"bic": "ICECLOUDXXX",
"defaultCurrencyCode": "EUR",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1223",
"accountId": "ID-1294",
"currencyCode": "EUR",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "EUR",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Summary for not using the request ID
If you make multiple POST calls to the same API endpoint without including the header parameter x-request-id, each subsequent call is treated as unique and will receive a separate response .
Find employee by ID Use case
In this example, we will find an existing employee by employeeId.
Use case data
API parameters with values
...api/v1/employees/ID-1183
Sample API call
To find an employee by username, make the following API call.
Sample request
Below is an example request of the API call to retrieve customer data.
cURL
Copy curl --location 'https://auth-api.sandbox.tuumplatform.com/api/v1/employees/ID-1183' \
--header 'x-channel-code: BACKOFFICE' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMTZUMjI6Mzk6MTUiLCJleHAiOjE3MzQzODg3NTUsInJvbGVzIjpbIkFETUlOIl19.ftJgnhviaIP-qTsXh19FIG6wpZntGXezBIXHVK0-63U' \
--data '' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"employeeId": "ID-1183",
"firstName": "Test",
"lastName": "Employee",
"username": "test.employee@bank.com",
"email": "test.employee@bank.com",
"authenticationMethod": "PASSWORD",
"defaultTenantCode": "MB",
"roles": [
"CUSTOMER_SERVICE"
],
"tenants": [
{
"tenantEmployeeId": "ID-1213",
"defaultTenant": true,
"tenantId": "ID-1000",
"tenantCode": "MB",
"roles": [
"CUSTOMER_SERVICE"
]
}
],
"externalId": null,
"lastLogin": "2024-11-25T12:28:04.635156Z",
"blockedUntil": null,
"failedAttempts": 0
}
} Result
The result of the API call is the dataset of a particular employee.
Create legal person Use case
Here you can learn how to create a legal person - record of your customer's business organisation. In this example, we will use the following data:
Sample API call
To create a legal person, make the following API call.
Sample request
Below is an example request body of the API call for creating a legal person.
Sample response
Below you will find an example response to the API call from above.
Result
A new legal person ID-3397 is created and activated. The legal person record is now available for the further actions.
Activate person Use case
This example presents how to activate a person from PENDING status to ACTIVE.
In this example, we will demonstrate how to activate a recently created private individual, Ashley Tuum, as she has passed all pre-activation checks.
Sample API call
To activate the person, make the following API call.
Sample request
Below is an example request of the API call to activate person.
Sample response
Below you will find an example response to the API call from above.
Result
A private person Ashley Tuum has been activated.
Find person addresses 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.
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.
We will search an employee ID-1183 whose
https://auth-api.sandbox.tuumplatform.com/api/v1/employees/username
Learn more about the
Use case data
API parameters with values
https://person-api.sandbox.tuumplatform.com/api/v2/persons
Learn more about the
The ability to use the PENDING.
Use case data
API parameters with values
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-29367/activate
Learn more about the
Use case data
API parameters with values
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3392/addresses
Learn more about the
Copy "personTypeCode": "L" The company name is New company Ltd
Copy "name": "New company Ltd" The company registration address:
Carnaby street 10, London, Great Britain, 13347
Copy "addresses":
[
{
"addressTypeCode": "R",
"street1": "Carnaby 10",
"cityCounty": "London",
"zip": "13347",
"countryCode": "GB"
}
] The company registration number is 111111
Copy "identificationNumber": {
"idNumber": "111111",
"idCountryCode": "GB"
}
Copy {
"personTypeCode": "L",
"name": "New company Ltd",
"addresses": [
{
"addressTypeCode": "R",
"street1": "Carnaby 10",
"cityCounty": "London",
"zip": "13347",
"countryCode": "GB"
}
],
"identificationNumber": {
"idNumber": "111111",
"idCountryCode": "GB"
}
}
Copy curl 'https://person-api.sandbox.tuumplatform.com/api/v2/persons' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTNUMjA6MDM6MDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODY2ODY1ODB9.bF0nEpm7Z1LgW08F9Fri-q1zAyDH5PsFwqhJCygdODQ' \
-H 'Content-Type: application/json' \
-d '{
"personTypeCode": "L",
"name": "New company Ltd",
"addresses": [
{
"addressTypeCode": "R",
"street1": "Carnaby 10",
"cityCounty": "London",
"zip": "13347",
"countryCode": "GB"
}
],
"identificationNumber": {
"idNumber": "111111",
"idCountryCode": "GB"
}
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personId": "ID-3397",
"statusCode": "ACTIVE",
"source": null,
"tenantCode": "MB",
"forgotten": false,
"creationDate": "2023-06-13",
"personalInfo": {
"personTypeCode": "L",
"givenName": null,
"middleName": null,
"surname": null,
"name": "New company Ltd",
"email": null,
"phoneNumber": null,
"phoneCountryCode": null,
"residencyCountryCode": null,
"sex": null,
"nationality": null,
"dependantPersons": null,
"legalForm": null,
"identificationNumber": {
"idNumberId": "ID-1773",
"personId": "ID-3397",
"idNumber": "111111",
"idCountryCode": "GB",
"vatNumber": null,
"taxNumber": null,
"validityRange": {
"startTime": "2023-06-13T19:06:34.159654Z",
"endTime": null
}
}
},
"additionalInfo": {
"birthDate": null,
"countryOfBirth": null,
"placeOfBirth": null,
"language": null,
"educationCode": null,
"maritalStatusCode": null,
"dependantPersons": null,
"taxResidencyCountry": null,
"usResident": false,
"pep": false,
"customerTypeCode": null,
"statusCodeReason": null,
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"tradingName": null,
"registrationDate": null,
"webAddress": null,
"pepExplanation": null,
"businessModelDescription": null,
"intraOrgCode": null,
"counterpartySectorCode": null
},
"work": null,
"home": null,
"addresses": [
{
"addressId": "ID-3057",
"personId": "ID-3397",
"addressTypeCode": "R",
"street1": "Carnaby 10",
"street2": null,
"cityCounty": "London",
"stateRegion": null,
"zip": "13347",
"countryCode": "GB",
"moveInDate": null,
"validityRange": {
"startTime": "2023-06-13T19:06:34.057318Z",
"endTime": null
}
}
],
"documents": [],
"relationships": [],
"additionalContacts": [],
"personGroupCodes": [],
"identificationNumbers": [
{
"idNumberId": "ID-1773",
"personId": "ID-3397",
"idNumber": "111111",
"idCountryCode": "GB",
"validityRange": {
"startTime": "2023-06-13T19:06:34.159654Z",
"endTime": null
},
"primary": true
}
],
"taxNumbers": [],
"fullName": "New company Ltd"
}
} The personId of the Ashley Tuum is ID-29367.
...persons/ID-29367/activate
Copy curl --location --request POST 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-29367/activate' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDUtMjlUMTQ6MzM6MDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE3MTY5OTMxODB9.hIvk230HwvSX2BMWxas_P7Xq8WyGfAEzeZsPz_U0ITY' \
--header 'x-channel-code: SYSTEM' \
--header 'Accept-Language: en' \
--data''
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personId": "ID-29367",
"statusCode": "ACTIVE",
"source": null,
"tenantCode": "MB",
"forgotten": false,
"legalForm": null,
"creationDate": "2024-05-29",
"personalInfo": {
"personTypeCode": "P",
"givenName": "Tuum",
"middleName": null,
"surname": "Ashley",
"name": null,
"email": null,
"phoneNumber": null,
"phoneCountryCode": null,
"residencyCountryCode": null,
"sex": null,
"nationality": null,
"dependantPersons": null,
"legalForm": null,
"identificationNumber": {
"idNumberId": "ID-3390",
"personId": "ID-29367",
"idNumber": "testidddd",
"idCountryCode": "GB",
"vatNumber": null,
"taxNumber": null,
"validityRange": {
"startTime": "2024-05-29T13:29:50.225Z",
"endTime": null
}
}
},
"additionalInfo": {
"birthDate": null,
"countryOfBirth": null,
"placeOfBirth": null,
"language": null,
"educationCode": null,
"maritalStatusCode": null,
"dependantPersons": null,
"taxResidencyCountry": null,
"usResident": false,
"pep": false,
"customerTypeCode": null,
"statusCodeReason": null,
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"tradingName": null,
"registrationDate": null,
"webAddress": null,
"pepExplanation": null,
"businessAreaCodes": [],
"businessModelDescription": null,
"intraOrgCode": null,
"counterpartySectorCode": null
},
"work": {
"activityCode": null,
"businessAreaCode": null,
"businessAreaCodes": [],
"employmentTimeCode": null,
"fixedEmploymentLength": null
},
"home": null,
"addresses": [
{
"addressId": "ID-28849",
"personId": "ID-29367",
"addressTypeCode": "R",
"street1": "24 Botley Road",
"street2": null,
"cityCounty": "Middleton Hall",
"stateRegion": null,
"zip": "NE71 3LL",
"countryCode": "GB",
"moveInDate": null,
"validityRange": {
"startTime": "2024-05-29T13:29:50.118Z",
"endTime": null
}
}
],
"documents": [],
"relationships": [],
"additionalContacts": [],
"personGroupCodes": [],
"identificationNumbers": [
{
"idNumberId": "ID-3390",
"personId": "ID-29367",
"idNumber": "testidddd",
"idCountryCode": "GB",
"validityRange": {
"startTime": "2024-05-29T13:29:50.225Z",
"endTime": null
},
"primary": true
}
],
"taxNumbers": [],
"accessRestricted": false,
"fullName": "Tuum Ashley"
}
} Private person with Tuum personId : ID-3392.
.../persons/ID-3392/addresses
Copy curl --location 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3392/addresses' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDUtMjFUMTA6NTc6MzIiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE3MTYyODkwNTJ9.nz1Fm5JV4tgUvL9rD-PbVb_fBVbIgbbxDhVpPdp6h2Q' \
--header 'x-channel-code: SYSTEM' \
--data ''
Copy {
"errors": null,
"validationErrors": null,
"data": [
{
"addressId": "ID-3052",
"personId": "ID-3392",
"addressTypeCode": "R",
"street1": "85 Park End St",
"street2": null,
"cityCounty": "Broomhill",
"stateRegion": null,
"zip": "NE65 0YW",
"countryCode": "GB",
"moveInDate": null,
"validityRange": {
"endTime": null,
"startTime": "2023-06-01T07:55:53.213023Z"
}
}
]
} Find person This guide will help you find details about an individual or a legal entity.
Based on your use case, use either of the endpoints to retrieve person data:
Find person details Use case
Learn how to find a particular person's (your customer's) main details in Tuum. In this example, we will demonstrate it on a private person using the following data.
Use case data
API parameters with values
Private person with Tuum personId : ID-3392
Sample API call
To retrieve customer data, make the following API call.
Sample request
Below is an example request of the API call to retrieve customer data.
cURL
Copy curl 'https://person-api.sandbox.tuumplatform.com/api/v3/persons/ID-3392' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMDFUMDg6NTU6NDciLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODU2MDk3NDd9.55aYdFuNopFjauFv8XG-FO6S5io6c4PNlF__rUIJixM' \
-H 'x-channel-code: SYSTEM' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personId": "ID-3392",
"personTypeCode": "P",
"statusCode": "ACTIVE",
"statusCodeReason": null,
"name": null,
"givenName": "Trevor",
"middleName": null,
"surname": "Tuum",
"birthDate": null,
"creationDate": "2023-06-01",
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"registrationDate": null,
"sex": null,
"email": null,
"customerTypeCode": null,
"nationality": null,
"taxResidencyCountry": null,
"placeOfBirth": null,
"countryOfBirth": null,
"phoneCountryCode": null,
"phoneNumber": null,
"idNumber": "DQ654327C",
"idCountryCode": "GB",
"residencyCountryCode": null,
"language": null,
"educationCode": null,
"activityCode": null,
"housingTypeCode": null,
"buildingTypeCode": null,
"moveInDate": null,
"maritalStatusCode": null,
"dependantPersons": null,
"employmentTimeCode": null,
"fixedEmploymentLength": null,
"businessAreaCode": null,
"intraOrgCode": null,
"tradingName": null,
"webAddress": null,
"pepExplanation": null,
"legalForm": null,
"businessModelDescription": null,
"counterpartySectorCode": null,
"forgotten": null,
"usResident": false,
"pep": false,
"source": null,
"tenantCode": "MB",
"fullName": "Trevor Tuum"
}
} Result
The result of the API call is the dataset of the particular person.
The
The
You can use use other endpoints to find person details such as
https://person-api.sandbox.tuumplatform.com/api/v3/persons/ID-3392
Learn more about the
Requests with same request ID Initial POST request
We will create a new account for a person by making the following API call.
Create account
POST https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts
Below is an example request body of the API call for creating an account.
JSON
Copy {
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
} cURL
Copy curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTE6MjM6MjUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNDgyMDV9.1lnY03GWnnGdki0uJlkNNSMydwiWv_jsdII10PKPUkA' \
-H 'x-request-id: eb1d4135-bca1-4612-aa83-29637830fe37' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}' As a result, a new account with accountId: ID-1292 was created and activated .
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1292",
"personId": "ID-3419",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-08-04",
"accountName": null,
"personName": "Eleanor Rigby",
"statusCode": "ACTIVE",
"iban": "GB76XXXX04030000001011",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1221",
"accountId": "ID-1292",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00001011",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1147",
"accountId": "ID-1292",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Duplicated POST request
We will make the API call again without changing the request ID and using the same request data .
The response we received is identical to the initial call, confirming the creation of the account with the ID-1292. No new account was created .
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1292",
"personId": "ID-3419",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-08-04",
"accountName": null,
"personName": "Eleanor Rigby",
"statusCode": "ACTIVE",
"iban": "GB76XXXX04030000001011",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1221",
"accountId": "ID-1292",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00001011",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1147",
"accountId": "ID-1292",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Duplicated POST request with changed data
We will repeat the API call using the same request ID but with updated request data . We will change the currency from GBP to USD.
Below is an example request body for creating an account with the updated currency.
JSON
Copy {
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "USD"
} cURL
Copy curl 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3419/accounts' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDgtMDRUMTE6MjM6MjUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTExNDgyMDV9.1lnY03GWnnGdki0uJlkNNSMydwiWv_jsdII10PKPUkA' \
-H 'x-request-id: eb1d4135-bca1-4612-aa83-29637830fe37' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Eleanor Rigby",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "USD"
}' As a result, no new account is created . However, the account currency on the existing account ID-1292is updated to USD as requested.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1292",
"personId": "ID-3419",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-08-04",
"accountName": null,
"personName": "Eleanor Rigby",
"statusCode": "ACTIVE",
"iban": "GB76XXXX04030000001011",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1221",
"accountId": "ID-1292",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00001011",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1147",
"accountId": "ID-1292",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Summary for using the same request ID
If you make multiple POST calls to the same API endpoint using the same value for the x-request-id header parameter, all subsequent calls will receive the same response as the initial call . This principle also holds even if you use different data in the request body of a repeated request.
Create customer group 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:
Use case data
API parameters with values
The group name is business.
This is a group for the premium customers.
Sample API call
To create a new customer group, make the following API call.
Sample request
Below is an example request body of the API call for creating a new customer group.
JSON
Copy {
"personGroupCode": "BUSINESS",
"description": "Premium customers"
} cURL
Copy 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.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
A new BUSINESS customer group is created.
Update personal info Use case
Here you can learn how to update a record of a particular person (your customer) in Tuum. In this example, we will demonstrate how to update the record of a private person using the following data.
Use case data
API parameters with values
Updating private person with Tuum personId : ID-3392.
...persons/ID-3392/personal
Adding the middleName : Harry.
Sample API call
To update the particular person's record, make the following API call.
Sample request
Below is an example request of the API call to update the particular customer's data.
JSON
Copy {
"surname": "Tuum",
"givenName": "Trevor",
"middleName": "Harry",
"identificationNumber": {
"idNumberId": "ID-1770",
"idNumber": "DQ654327C",
"idCountryCode": "GB"
}
} cURL
Copy curl --location --request PUT 'https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3392/personal' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMDctMjRUMTE6MjU6NTMiLCJleHAiOjE3MjE4MjAzNTMsInJvbGVzIjpbIkFETUlOIl19.G-2NqlqmoHvoBRj3666a-Lv8VGRUybpX-ta4UPRpcsQ' \
--header 'x-channel-code: SYSTEM' \
--header 'Content-Type: application/json' \
--data '{
"surname": "Tuum",
"givenName": "Trevor",
"middleName": "Harry",
"identificationNumber": {
"idNumberId": "ID-1770",
"idNumber": "DQ654327C",
"idCountryCode": "GB"
}
}'
When using the example request, please change the x-auth-token to the one you obtained with your authentication API call.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personTypeCode": "P",
"givenName": "Trevor",
"middleName": "Harry",
"surname": "Tuum",
"name": null,
"email": null,
"phoneNumber": null,
"phoneCountryCode": null,
"residencyCountryCode": null,
"sex": null,
"nationality": null,
"dependantPersons": null,
"legalForm": null,
"identificationNumber": {
"idNumberId": "ID-1770",
"personId": "ID-3392",
"idNumber": "DQ654327C",
"idCountryCode": "GB",
"vatNumber": null,
"taxNumber": null,
"validityRange": {
"startTime": "2023-06-01T07:55:53.37628Z",
"endTime": null
}
}
}
} Result
The middleName of the private person is updated.
Update person address Use case
Here we will review how to update the person address.
Use case data
API parameters with values
Updating the addressId ID-3088of the legal person with personId ID-3397.
...persons/ID-3397/addresses/ID-3088
Sample API call
To update person address, make the following call.
Sample request
Below is an example body request of the API call for updating the person address.
JSON
Copy {
"street1": "Brick Lane 4",
"cityCounty": "London",
"zip": "13789",
"countryCode": "GB"
} cURL
Copy curl -L -X PUT 'https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3397/addresses/ID-3057' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTJUMTU6MzM6MTAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODkxNzU5OTB9.qzjD0zt7w5nIvYTaz9xEMP_jfZEgcH6KsnJZdlkdLy8' \
-H 'Content-Type: application/json' \
-d '{
"street1": "Brick Lane 4",
"cityCounty": "London",
"zip": "13789",
"countryCode": "GB"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"addressId": "ID-3088",
"personId": "ID-3397",
"addressTypeCode": "R",
"street1": "Brick Lane 4",
"street2": null,
"cityCounty": "London",
"stateRegion": null,
"zip": "13789",
"countryCode": "GB",
"moveInDate": null,
"validityRange": {
"endTime": null,
"startTime": "2023-07-12T14:33:23.624199Z"
}
}
} Result
The person address information is updated.
Create person document Use case
In this example, we will review how to add a document record for a person.
Use case data
API parameters with values
Adding a document record for a private person ID-3392.
...persons/ID-3392/documents
Adding the person's passport details.
Sample API call
To create a person document, make the following API call.
Sample request
Below is an example request body of the API call for creating a person document.
JSON
Copy {
"issuingCountry": "GB",
"number": "0124R5M1P5",
"documentTypeCode": "PASSPORT",
"expiryDate": "2025-01-03"
} cURL
Copy curl -L -g 'https://person-api.{{env}}.{{domain}}/api/v1/persons/ID-3392/documents' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTdUMTg6Mzk6MTAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODk2MTkxNTB9.cfzAzYCJ2lAWGHj_YxX9-vc21YS-ekBsZvOJx9C9Pqk' \
-H 'Content-Type: application/json' \
-d '{
"issuingCountry": "GB",
"number": "0124R5M1P5",
"documentTypeCode": "PASSPORT",
"expiryDate": "2025-01-03"
}' Sample response
Below you will find an example response to the API call from above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"docuId": "ID-1024",
"personId": "ID-3392",
"issuingCountry": "GB",
"number": "0124R5M1P5",
"documentTypeCode": "PASSPORT",
"expiryDate": "2025-01-03",
"validityRange": {
"startTime": "2023-07-17T17:47:42.187928Z",
"endTime": null
}
}
} Result
A new passport record ID-1024 was added for a private person.
Close person representation Use case
In the Tuum environment, to remove the representative from a legal or another private person, you can close the representation rights. Once the representation is closed, the representative loses their rights.
Use case data
API parameters with values
Removing the representation rights with the personRelationshipId ID-1003 from the parentPerson (legal person with the personId ID-3394).
.../persons/ID-3394/relations/closing/ID-1003
Sample API call
To close the person representation, make the following call.
Sample request
Below is an example request of the API call to close the person representation rights.
cURL
Copy curl -L -X POST 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3392/relations/closing/ID-1002' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTlUMTY6MjA6MDIiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODcxOTE2MDJ9.VDHNExXmgRmLvyx_ChTO2iOrwl7WaLRaTNe_T_A47rk' \
-d '' Sample response
Below you will find an example response to the API call from above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personRelationshipId": "ID-1003",
"parentPersonId": "ID-3394",
"personId": "ID-3392",
"relationTypeCode": "REPRESENTATIVE",
"statusCode": "CLOSING",
"role": null,
"percentageOfShares": null,
"percentageOfSignature": null,
"beneficiary": true,
"representingRange": {
"startDate": "2023-06-06",
"endDate": "2023-06-13"
},
"additionalData": null,
"validityRange": {
"startTime": "2023-06-14T21:32:09.684826Z",
"endTime": "2023-06-14T21:38:29.637157Z"
},
"parentIdNumber": null,
"personIdNumber": null,
"parent": {
"personId": "ID-3394",
"personTypeCode": "L",
"statusCode": "ACTIVE",
"statusCodeReason": null,
"name": "New company Ltd",
"givenName": null,
"middleName": null,
"surname": null,
"birthDate": null,
"creationDate": "2023-06-13",
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"registrationDate": null,
"sex": null,
"email": null,
"customerTypeCode": null,
"nationality": null,
"taxResidencyCountry": null,
"placeOfBirth": null,
"countryOfBirth": null,
"phoneCountryCode": null,
"phoneNumber": null,
"idNumber": "120045",
"idCountryCode": "GB",
"residencyCountryCode": null,
"language": null,
"educationCode": null,
"activityCode": null,
"housingTypeCode": null,
"buildingTypeCode": null,
"moveInDate": null,
"maritalStatusCode": null,
"dependantPersons": null,
"employmentTimeCode": null,
"fixedEmploymentLength": null,
"businessAreaCode": null,
"intraOrgCode": null,
"tradingName": null,
"webAddress": null,
"pepExplanation": null,
"legalForm": null,
"businessModelDescription": null,
"counterpartySectorCode": null,
"forgotten": null,
"usResident": false,
"pep": false,
"source": null,
"tenantCode": "MB",
"fullName": "New company Ltd"
},
"person": {
"personId": "ID-3392",
"personTypeCode": "P",
"statusCode": "ACTIVE",
"statusCodeReason": null,
"name": null,
"givenName": "Trevor",
"middleName": "Harry",
"surname": "Tuum",
"birthDate": null,
"creationDate": "2023-06-01",
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"registrationDate": null,
"sex": null,
"email": null,
"customerTypeCode": null,
"nationality": null,
"taxResidencyCountry": null,
"placeOfBirth": "Alabama",
"countryOfBirth": null,
"phoneCountryCode": null,
"phoneNumber": null,
"idNumber": "DQ654327C",
"idCountryCode": "GB",
"residencyCountryCode": null,
"language": null,
"educationCode": null,
"activityCode": null,
"housingTypeCode": null,
"buildingTypeCode": null,
"moveInDate": null,
"maritalStatusCode": null,
"dependantPersons": null,
"employmentTimeCode": null,
"fixedEmploymentLength": null,
"businessAreaCode": null,
"intraOrgCode": null,
"tradingName": null,
"webAddress": null,
"pepExplanation": null,
"legalForm": null,
"businessModelDescription": null,
"counterpartySectorCode": null,
"forgotten": null,
"usResident": false,
"pep": false,
"source": null,
"tenantCode": "MB",
"fullName": "Trevor Tuum"
}
}
} Result
The person representation is set to the CLOSING status.
Create additional contact 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.
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.
See more about the
https://person-api.sandbox.tuumplatform.com/api/v1/person-group-types
See more information about the
https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3392/personal
Learn more about the
The addressId parameter is generated when a
https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3397/addresses/ID-3088
See more information about the
You can add different types of personal documents: ID cards, passports, driving licences and residence permits. See more in the
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3392/documents
See more about the
https://person-api.sandbox.tuumplatform.com/api/v1/persons/{personId}/relations/closing/{personRelationshipId}
Learn more about the
Use case data
API parameters with values
https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3394/additional-contacts
See more information about
Copy "personGroupCode": "BUSINESS"
Copy "description": "Premium customers"
Copy "middleName": "Harry"
Copy "street1": "Brick Lane 4"
Copy {
"issuingCountry": "GB",
"number": "0124R5M1P5",
"documentTypeCode": "PASSPORT",
"expiryDate": "2025-01-03"
} The personId of the legal person New company Ltd is ID-3394.
...persons/ID-3394/additional-contact
The contact type code is the fraud department.
Copy "contactTypeCode": "FRAUD_CONTACT" The description of the contact type.
Copy "description": "Contacts for fraud department" The email of the contact.
Copy "email": "psmidt@smidt.de" The phone number of the contact.
Copy "phoneNumber": "0901820" The country code of the phone number.
Copy "phoneCountryCode": "+49"
Copy {
"contactTypeCode": "FRAUD_CONTACT",
"description": "Contacts for fraud department",
"email": "psmidt@smidt.de",
"phoneNumber": "0901820",
"phoneCountryCode": "+49"
}
Copy curl --location 'https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3394/additional-contacts' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDUtMjFUMDc6MjY6NTMiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE3MTYyNzY0MTN9.sQw8rjIaygzdHjCKDSlEQsHu0Lvh3U0EjAWWEYaAH5A' \
--header 'x-channel-code: SYSTEM' \
--header 'Content-Type: application/json' \
--data-raw '{
"contactTypeCode": "FRAUD_CONTACT",
"description": "Contacts for fraud department",
"email": "psmidt@smidt.de",
"phoneNumber": "0901820",
"phoneCountryCode": "+49"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"additionalContactId": "ID-1009",
"personId": "ID-3394",
"contactTypeCode": "FRAUD_CONTACT",
"description": "Contacts for fraud department",
"email": "psmidt@smidt.de",
"phoneCountryCode": "+49",
"phoneNumber": "0901820",
"preferredMethodOfContact": false,
"validityRange": {
"endTime": null,
"startTime": "2024-05-21T06:46:42.928Z"
}
}
} Reactivate person 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.
Use case data
API parameters with values
The personId of Rhys Davey who we want to reactivate isID-3204.
Since the person returned as a client, the reason can be set as OTHER.
The reactivation is effective from June 15th 2023. The date format: YYYY-MM-DD.
The by default processReason- s for private and legal persons:
Sample API call
To reactivate a person, make the following API call.
Sample request
Below is an example request body of the API call to inactivate a person.
JSON
Copy {
"processReason": "OTHER",
"processDate": "2023-06-15"
} cURL
Copy curl --location 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/reactivate/start' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGF1cmEgVCIsImVtcGxveWVlSWQiOiJJRC0xMDU0IiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA1VDE1OjEwOjE4IiwiZXhwIjoxNzQxMTg3NDE4LCJyb2xlcyI6WyJBRE1JTiJdfQ.gnVRav5NmpZapS3uGMLt69xADsYdEPiGGOjXnt1jqyY' \
--header 'x-channel-code: SYSTEM' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--data '{
"processReason": "OTHER",
"processDate": "2023-06-15"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
Assign person to group 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.
Sample request
Below is the example body request of the API call for assigning a person to the group.
Sample response
Here you find an example response body to the API call above.
Result
The user ID-3392 is assigned to the BUSINESS customer group.
Create person financial data Use case
In this example, we will show how to set up legal person financial data. We will modify New company Ltd and add assets as a currency worth 10000000 EUR.
Sample API call
To create financial data, call the following endpoint.
Sample request
Below is an example request body of the API call for creating person representation.
Sample response
Below you will find an example response to the API call from above.
Result
Assets as a currency worth 10000000 EUR are added to the legal person.
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/reactivate/start
Learn more about the
The person's status is changed to PENDING. The person can be activated with
Use case data
API parameters with values
https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3392/person-groups
To learn more about the
Use case data
API parameters with values
Learn more about the
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3394/financial-data
Copy .../persons/ID-3204/reactivate/start
Copy "processReason": "OTHER"
Copy "processDate": "2023-06-15" A private person with personId : ID-3392
...persons/ID-3392/person-groups
A customer group for business customers
Copy "personGroupCode": "BUSINESS"
Copy {
"personGroupCode": "BUSINESS"
}
Copy 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"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"personGroupId": "ID-1489",
"personId": "ID-3392",
"personGroupCode": "BUSINESS",
"validityRange": {
"endTime": null,
"startTime": "2023-06-21T20:48:57.250757Z"
}
}
} The personId of the legal person. New company Ltd is ID-3394.
...persons/ID-3394/financial-data
The financial data type code is assets.
Copy "financialDataTypeCode": "ASSETS" The financial data value type code is currency.
Copy "financialDataValueTypeCode": "CURRENCY" The currency code is EUR.
The currencyCode follows ISO 4217 format.
Copy "currencyCode": "EUR" The period presents the count of months for the validity range and is 12 months.
The financial value for the current period is 10000000.
Copy "currentPeriodValue": 10000000
Copy {
"financialDataTypeCode": "ASSETS",
"financialDataValueTypeCode": "CURRENCY",
"currentPeriodValue": 10000000,
"currencyCode": "EUR",
"period": 12
}
Copy curl --location 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3394/financial-data' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDUtMjBUMTE6NDY6MTMiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE3MTYyMDU1NzN9.rhx33fBFHBGOlwWyXJKTtPh4u7J58F2SuvrIdhuA_3c' \
--header 'x-channel-code: SYSTEM' \
--header 'Content-Type: application/json' \
--data '{
"financialDataTypeCode": "ASSETS",
"financialDataValueTypeCode": "CURRENCY",
"currentPeriodValue": 10000000,
"currencyCode": "EUR",
"period": 12
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"financialDataId": "ID-1017",
"personId": "ID-3394",
"financialDataTypeCode": "ASSETS",
"financialDataValueTypeCode": "CURRENCY",
"currentPeriodValue": 10000000,
"currencyCode": "EUR",
"period": 12,
"periodRange": null,
"nextPeriodEstimateValue": null,
"description": null,
"valueRange": null,
"validityRange": {
"startTime": "2024-05-20T10:49:58.556Z",
"endTime": null
}
}
} Reactivate person 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.
Use case data
API parameters with values
The personId of Rhys Davey who we want to reactivate isID-3204.
Since the person returned as a client, the reason can be set as OTHER.
The reactivation is effective from June 15th 2023. The date format: YYYY-MM-DD.
The by default processReason- s for private and legal persons:
Sample API call
To reactivate a person, make the following API call.
Sample request
Below is an example request body of the API call to inactivate a person.
JSON
Copy {
"processReason": "OTHER",
"processDate": "2023-06-15"
} cURL
Copy curl --location 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/reactivate/start' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGF1cmEgVCIsImVtcGxveWVlSWQiOiJJRC0xMDU0IiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA1VDE1OjEwOjE4IiwiZXhwIjoxNzQxMTg3NDE4LCJyb2xlcyI6WyJBRE1JTiJdfQ.gnVRav5NmpZapS3uGMLt69xADsYdEPiGGOjXnt1jqyY' \
--header 'x-channel-code: SYSTEM' \
--header 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--data '{
"processReason": "OTHER",
"processDate": "2023-06-15"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
Create person representation Use case
In this example, we will show how to set up person representation. We will set a private person Trevor Tuum as a representative of the legal person, New company Ltd.
Use case data
API parameters with values
The personId of the New company Ltd is ID-3394.
...persons/ID-3394/relations
Use case data
API parameters with values
The identification number of the private person Trevor Tuum is DQ654327C.
The private person is registered in the Great Britain.
The private person is the representative of the New company Ltd.
The representation is in active status.
The private person is the beneficiary owner of the company.
Note: If the private person is not a benificiary owner of the company, set to false .
The representation validity period. The date format: YYYY-MM-DD .
Sample API call
To set the representation rights, call the following endpoint.
Sample request
Below is an example request body of the API call for creating person representation.
JSON
Copy {
"relationships": [
{
"idNumber": "DQ654327C",
"idCountryCode": "GB",
"relationTypeCode": "REPRESENTATIVE",
"statusCode": "ACTIVE",
"beneficiary": true,
"representingRange": {
"startDate": "2023-06-06",
"endDate": "2023-06-13"
}
}
]
} cURL
Copy curl 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3394/relations' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTNUMjM6MDc6NDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODY2OTc2NjB9.Tt708jxWsjUQPurWItoY9QVqa2tb5PbnFBV-8voVRxY' \
-H 'Content-Type: application/json' \
-d '{
"relationships": [
{
"idNumber": "DQ654327C",
"idCountryCode": "GB",
"relationTypeCode": "REPRESENTATIVE",
"statusCode": "ACTIVE",
"beneficiary": true,
"representingRange": {
"startDate": "2023-06-06",
"endDate": "2023-06-13"
}
}
]
}'
``` Sample response
Below you will find an example response to the API call from above.
Copy {
"errors": null,
"validationErrors": null,
"data": [
{
"personRelationshipId": "ID-1003",
"parentPersonId": "ID-3394",
"personId": "ID-3392",
"relationTypeCode": "REPRESENTATIVE",
"statusCode": "ACTIVE",
"role": null,
"percentageOfShares": null,
"percentageOfSignature": null,
"beneficiary": true,
"representingRange": {
"startDate": "2023-06-06",
"endDate": "2023-06-13"
},
"additionalData": null,
"validityRange": {
"startTime": "2023-06-14T21:32:09.684826Z",
"endTime": null
},
"parentIdNumber": null,
"personIdNumber": null,
"parent": {
"personId": "ID-3394",
"personTypeCode": "L",
"statusCode": "ACTIVE",
"statusCodeReason": null,
"name": "New company Ltd",
"givenName": null,
"middleName": null,
"surname": null,
"birthDate": null,
"creationDate": "2023-06-13",
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"registrationDate": null,
"sex": null,
"email": null,
"customerTypeCode": null,
"nationality": null,
"taxResidencyCountry": null,
"placeOfBirth": null,
"countryOfBirth": null,
"phoneCountryCode": null,
"phoneNumber": null,
"idNumber": "120045",
"idCountryCode": "GB",
"residencyCountryCode": null,
"language": null,
"educationCode": null,
"activityCode": null,
"housingTypeCode": null,
"buildingTypeCode": null,
"moveInDate": null,
"maritalStatusCode": null,
"dependantPersons": null,
"employmentTimeCode": null,
"fixedEmploymentLength": null,
"businessAreaCode": null,
"intraOrgCode": null,
"tradingName": null,
"webAddress": null,
"pepExplanation": null,
"legalForm": null,
"businessModelDescription": null,
"counterpartySectorCode": null,
"forgotten": null,
"usResident": false,
"pep": false,
"source": null,
"tenantCode": "MB",
"fullName": "New company Ltd"
},
"person": {
"personId": "ID-3392",
"personTypeCode": "P",
"statusCode": "ACTIVE",
"statusCodeReason": null,
"name": null,
"givenName": "Trevor",
"middleName": "Harry",
"surname": "Tuum",
"birthDate": null,
"creationDate": "2023-06-01",
"deathDate": null,
"liquidationDate": null,
"inactivationDate": null,
"registrationDate": null,
"sex": null,
"email": null,
"customerTypeCode": null,
"nationality": null,
"taxResidencyCountry": null,
"placeOfBirth": "Alabama",
"countryOfBirth": null,
"phoneCountryCode": null,
"phoneNumber": null,
"idNumber": "DQ654327C",
"idCountryCode": "GB",
"residencyCountryCode": null,
"language": null,
"educationCode": null,
"activityCode": null,
"housingTypeCode": null,
"buildingTypeCode": null,
"moveInDate": null,
"maritalStatusCode": null,
"dependantPersons": null,
"employmentTimeCode": null,
"fixedEmploymentLength": null,
"businessAreaCode": null,
"intraOrgCode": null,
"tradingName": null,
"webAddress": null,
"pepExplanation": null,
"legalForm": null,
"businessModelDescription": null,
"counterpartySectorCode": null,
"forgotten": null,
"usResident": false,
"pep": false,
"source": null,
"tenantCode": "MB",
"fullName": "Trevor Tuum"
}
}
]
}
``` Result
A new person relationship is created:
Parameter and value
Explanation
The code ID-1003 is a unique identifier of the person relationship between a legal and a private person.
A legal person (New company Ltd) was set as a parent person. And a private person (Trevor Tuum) was added as a company representative.
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/reactivate/start
Learn more about the
The person's status is changed to PENDING. The person can be activated with
https://person-api.sandbox.tuumplatform.com/api/v1/persons/{personId}/relations
Learn more about the
Copy .../persons/ID-3204/reactivate/start
Copy "processReason": "OTHER"
Copy "processDate": "2023-06-15"
Copy "idNumber": "DQ654327C"
Copy "idCountryCode": "GB"
Copy "relationTypeCode": "REPRESENTATIVE"
Copy "statusCode": "ACTIVE"
Copy "representingRange": {
"startDate": "2023-06-06",
"endDate": "2023-06-13"
}
Copy "personRelationshipId": "ID-1003"
Copy "parentPersonId": "ID-3394",
"personId": "ID-3392",
"relationTypeCode": "REPRESENTATIVE" Remove person restoration key Use case
In this example, we will review how to forget a person record forever and make it unrecoverable.
Use case data
API parameters with values
There is a private person personId ID-3415 whose person record is already inactivated and forgotten. The person wants to ensure that the personal data is removed completely and is non-recoverable.
...persons/ID-3415/forget/key
Sample API call
To remove the restoration key, make the following call.
Sample request
Below is an example request to remove the restoration key call.
cURL
Copy curl -L -X DELETE 'https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3415/forget/keyhttps://person-api.{{env}}.{{domain}}/api/v1/persons/ID-3415/forget/key' \
-H 'x-channel-code: BACKOFFICE' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTJUMTQ6MDg6MTYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODkxNzA4OTZ9.Weps_UVn2b2iOkcZYgSyZd_mcxu7TSoOVxABvDWsWkI' \
-d '{
"processReason": "OTHER",
"processDate": "2023-06-15"
}' Sample response
The remove restoration key endpoint generates the following response.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
The restoration key of a forgotten person ID-3415 is removed. The personal data that belong to the person is non-recoverable.
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3415/forget/key
See more about the
Forget person 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.
Sample request
Below is an example request body of the forget person API call.
JSON
Copy {
"processReason": "CUSTOMER_REQUESTED",
"processDate": "2023-06-15"
} cURL
Copy curl -X 'POST' \
'https://person-api.dev.tuum.xyz/api/v1/persons/ID-3204/forget/start' \
-H 'accept: */*' \
-H 'x-channel-code: SYSTEM' \
-H 'x-tenant-code: MB.EU' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjc3JmVG9rZW4iOiJzdHJpbmciLCJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTZUMTg6NDg6NDQiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE2ODY5NDEzMjR9.OBniiwiaI2ZN1PMdr6InOjUNtg22vEso8wnpV6kJ104' \
-H 'Content-Type: application/json' \
-d '{
"processReason": "CUSTOMER_REQUESTED",
"processDate": "2023-06-15"
}' Sample response
The forget person generates the following response.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
As an outcome, the personal data of Rhys Davey ID-3204 is forgotten.
https://person-api.sandbox.tuumplatform.com/api/v1/persons/ID-3204/forget/start
Learn more about the
Create internal account Use case
Here we will review how to set up an bank technical account - internal account.
Use case data
API parameters with values
The name of the account holder is Trevor Harry Tuum
For the internal accounts, use the internal customer group
For the internal accounts, use the internal pricelist
Trevor's residency country is the Great Britain
The internal account currency is euro
Sample API call
To create an internal account, make the following API call.
Sample request
Below is an example request body of the API call for creating an internal account.
JSON
Copy {
"accountTypeCode": "INTERNAL",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "INTERNAL",
"priceListTypeCode": "INTERNAL",
"currencyCode": "EUR"
} cURL
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3392/accounts' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMjZUMTM6NTc6MDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODc3ODc4MjB9.dLFGW9A1MvRHNAhjFr_yXBm0m24bHI0NlIARuiwbBqE' \
-d '{
"accountTypeCode": "INTERNAL",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "INTERNAL",
"priceListTypeCode": "INTERNAL",
"currencyCode": "EUR"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1282",
"personId": "ID-3392",
"accountTypeCode": "INTERNAL",
"activationDate": "2023-06-26",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "XX54XXXX99999000000000000001257",
"bic": "ICECLOUDXXX",
"defaultCurrencyCode": "EUR",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "INTERNAL",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1209",
"accountId": "ID-1282",
"currencyCode": "EUR",
"balanceAmount": 0,
"reservedAmount": 0,
"overdraftLimitAmount": 0,
"defaultCurrencyCode": "EUR",
"availableBalanceInDefaultCcy": 0,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0
}
],
"masterAccountId": null,
"accountNumbers": [],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Result
The outcome of the API call is the complete set of account data. Including the parameters generated by the Tuum system:
Parameter and value
Explanation
A unique identifier is assigned to the new account.
The new account is created and activated.
The IBAN assigned to the new account.
The BIC assigned to the new account.
https://account-api.sandbox.tuumplatform.com/api/v4/persons/{personId}/accounts
See more about the
Copy "accountTypeCode": "INTERNAL"
Copy "personName": "Trevor Harry Tuum"
Copy "customerGroupCode": "INTERNAL"
Copy "priceListTypeCode": "INTERNAL"
Copy "residencyCountryCode": "GB"
Copy "currencyCode": "EUR"
Copy "statusCode": "ACTIVE"
Copy "iban": "XX54XXXX99999000000000000001257" Create currency account Use case
In this example we will review how to open a currency account with the minimal set of date.
Sample API call
To create an account for a person, make the following API call.
Sample request
Below is an example request body of the API call for creating an account.
Sample response
Below you find an example response body to the API call above.
Result
The outcome of the API call is the complete set of account data. Including the parameters generated by the Tuum system:
Use case data
API parameters with values
https://account-api.sandbox.tuumplatform.com/api/v4/persons/{personId}/accounts
See more about the
Parameter and value
Explanation
Copy "accountTypeCode": "CURRENCY" The name of the account holder is Trevor Harry Tuum
Copy "personName": "Trevor Harry Tuum" Trevor is assigned to the GROUP_A customer group.
Copy "customerGroupCode": "GROUP_A" The standard price list is assigned to the account
Copy "priceListTypeCode": "STANDARD" Trevor's residency country is the Great Britain
Copy "residencyCountryCode": "GB" The account currency code is GBP
Copy "currencyCode": "GBP"
Copy {
"accountTypeCode": "CURRENCY",
"personName": "Trevor Harry Tuum",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3392/accounts' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTlUMTg6NDI6MjIiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODcyMDAxNDJ9.ug4KhUwVSEuRx0VcbBUMc2Emf_RJw-nde3aHdKFbHkY' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Trevor Harry Tuum",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1279",
"personId": "ID-3392",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-06-19",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "GB72XXXX04030000000986",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1206",
"accountId": "ID-1279",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00000986",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1143",
"accountId": "ID-1279",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
}
Copy "accountId": "ID-1279" A unique identifier is assigned to the new account.
Copy "statusCode": "ACTIVE" The new account is created and activated.
Copy "iban": "GB72XXXX04030000000986" The IBAN assigned to the new account.
The BIC assigned to the new account.
Create account limit type 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.
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
Use case data
API parameters with values
You can find more information about the
https://account-api.sandbox.tuumplatform.com/api/v1/limits/types
A new single currency account limit type is created - ID-1002. In the
Copy {
"scopeTypeCode": "ACCOUNT",
"periodTypeCode": "MONTHLY",
"calcTypeCode": "PER_CURRENCY",
"limitCode": "NEW_ACCOUNT_LIMIT"
}
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v1/limits/types' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTFUMTU6MDA6MTUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODkwODc2MTV9.wfWaIi2x7wg64c0UPBPBHoezz5EhajJqQp1oHD7Rm7o' \
-H 'Content-Type: application/json' \
-d '{
"scopeTypeCode": "ACCOUNT",
"periodTypeCode": "MONTHLY",
"calcTypeCode": "PER_CURRENCY",
"limitCode": "NEW_ACCOUNT_LIMIT"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"limitTypeId": "ID-1002",
"scopeTypeCode": "ACCOUNT",
"periodTypeCode": "MONTHLY",
"calcTypeCode": "PER_CURRENCY",
"limitCode": "NEW_ACCOUNT_LIMIT"
}
} The limit must be applicable on the account level.
Copy "scopeTypeCode": "ACCOUNT" The limit is active on a montly basis.
Copy "periodTypeCode": "MONTHLY" The limit is calculated per currency.
Copy "calcTypeCode": "PER_CURRENCY"
Copy "limitCode": "NEW_ACCOUNT_LIMIT" The
Inactivate person Use case
Here, you can learn how to inactivate a person who is no longer an active user. We will inactivate a private person, Rhys Davey, who no longer uses any services and does not wish to maintain an active customer record.
Use case data
API parameters with values
The personId of Rhys Davey who we want to inactivate isID-3204.
Since the person requested to inactivate their account, the reason can be set as OTHER.
The inactivation is effective from June 15th 2023. The date format: YYYY-MM-DD.
You can use different values for the processReason parameter. See below:
Private person
The processReason for private person:
DATA_RETENTION_PERIOD_END.
Legal person
The processReason for legal person:
DATA_RETENTION_PERIOD_END.
Sample API call
To inactivate a person, make the following API call.
Sample request
Below is an example request body of the API call to inactivate a person.
JSON
Copy {
"processReason": "OTHER",
"processDate": "2023-06-15"
} cURL
Copy curl --location 'https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3204/inactivate/start' \
--header 'x-channel-code: system' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMTVUMTQ6MTc6MTgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODY4Mzg2Mzh9.nohgrCBeB0UK4HVFLGlV867_C923zuMe_m_Y6I6Jl8k' \
--header 'Content-Type: application/json' \
--data '{
"processReason": "OTHER",
"processDate": "2023-06-15"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
The person's status is changed to INACTIVE.
Person inactivation is not permanent and person can be PENDING status and later ACTIVE status.
https://person-api.sandbox.tuumplatform.com/api/v2/persons/ID-3204/inactivate/start
Learn more about the
Copy .../persons/ID-3204/inactivate/start
Copy "processReason": "OTHER"
Copy "processDate": "2023-06-15" Create virtual account Use case
Here we will review how to set up a virtual account when Tuum is the service provider:
Use case data
API parameters with values
The master account is a currency account with the ID-1279.
The name of the account holder is Trevor Harry Tuum.
Trevor is assigned to the GROUP_A customer group.
The standard price list is assigned to the account.
Trevor's residency country is the Great Britain.
The virtual account currency is GBP.
The account is opened with standard setup scheme. And account numbers are generated and assigned by Tuum.
Tuum is the service provider.
Sample API call
To create a virtual account, make the following API call.
Sample request
Below is an example request body of the API call for creating an account.
JSON
Copy {
"accountTypeCode": "VIRTUAL",
"masterAccountId": "ID-1279",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"currencyCode": "GBP",
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM"
} cURL
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3392/accounts' \
-H 'x-channel-code: system' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDYtMjZUMTk6MDU6MDgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODc4MDYzMDh9.iySF4SAjJzd6j5-KGeiZ-JYP3fIAnLZUkUjyhiTTsbM' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "VIRTUAL",
"masterAccountId": "ID-1279",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"currencyCode": "GBP",
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1283",
"personId": "ID-3392",
"accountTypeCode": "VIRTUAL",
"activationDate": "2023-06-26",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "GB05XXXX04030100000462",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [],
"masterAccountId": "ID-1279",
"accountNumbers": [
{
"accountNumber": {
"value": "00000462",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040301",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1144",
"accountId": "ID-1283",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
} Result
The outcome of the API call is the complete set of account data. Including the parameters generated by the Tuum system:
Parameter and value
Explanation
A unique identifier is assigned to the new account.
The new account is created and activated.
The IBAN assigned to the new account.
The BIC assigned to the new account.
https://account-api.sandbox.tuumplatform.com/api/v4/persons/{personId}/account
See more about the
Copy "accountTypeCode": "VIRTUAL"
Copy "masterAccountId": "ID-1279"
Copy "personName": "Trevor Harry Tuum"
Copy "customerGroupCode": "GROUP_A"
Copy "priceListTypeCode": "STANDARD"
Copy "residencyCountryCode": "GB"
Copy "currencyCode": "GBP"
Copy "accountTypeSetupCode": "STANDARD"
Copy "serviceProviderCode": "TUUM"
Copy "accountId": "ID-1283"
Copy "statusCode": "ACTIVE"
Copy "iban": "GB05XXXX04030100000462" Create account limit Use case
In this example, we will review how to set up an account limit and apply it to the particular account.
Use case data
API parameters with values
The current account id to which the account limit is going to be applied.
The account limit amount is 10000 EUR.
Sample API call
To create a new account limit, make the following API call.
Create account limit
POST https://account-api.sandbox.tuumplatform.com/api/v2/accounts/limits
Sample request
Below is an example request body of the API call for creating an account limit.
JSON
Copy {
"limitTypeId": "ID-1002",
"accountId": "ID-1279",
"amount": {
"amount": "10000",
"currencyCode": "EUR"
}
} cURL
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v2/accounts/limits'
-H 'x-channel-code: SYSTEM'
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTlUMTU6MDU6MzYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODk3NzkxMzZ9.ITizqprIzqJfEhgygd8ij1gxzN2Wj5yNiR5U6IxI_c4'
-H 'Content-Type: application/json'
-d '{ "limitTypeId": "ID-1002", "accountId": "ID-1279", "amount": { "amount": "10000", "currencyCode": "EUR" } }' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountLimitId": "ID-1445",
"limitTypeId": "ID-1002",
"accountId": "ID-1279",
"ownerPersonId": null,
"userPersonId": null,
"amount": {
"amount": 10000.00,
"currencyCode": "EUR"
},
"validityRange": {
"endTime": null,
"startTime": "2023-07-19T14:05:43.241Z"
},
"editable": true
}
} Result
A new account limit ID-1445 was created on the current account ID-1279.
Create account class code 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.
Create account class code
POST https://account-api.sandbox.tuumplatform.com/api/v1/account-class-codes
Sample request
Below is an example request body of the API call for creating an account class code.
Sample response
Below you find an example response body to the API call above.
Result
A new account class code is created.
The account limit type that was created in the
https://account-api.sandbox.tuumplatform.com/api/v2/accounts/limits
See more information about the
See more
Use case data
API parameters
https://account-api.sandbox.tuumplatform.com/api/v1/account-class-codes
See more information about the
See more information about this
Copy "limitTypeId": "ID-1002"n
Copy "accountId": "ID-1279"
Copy "amount": {
"amount": "10000",
"currencyCode": "EUR"
} Create a new account class code.
Copy {
"description": "New account class code",
"accountClassCode": "NEW"
}
Copy {
"description": "New account class code",
"accountClassCode": "NEW"
}
Copy 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"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"description": "New account class code",
"accountClassCode": "NEW"
}
} Create account limit code 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
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 data
API parameters with values
https://account-api.sandbox.tuumplatform.com/api/v1/limits/codes
See more information about this
The technical name of the account limit code.
Copy "code": "NEW_ACCOUNT_LIMIT" The description of the new account limit code.
Copy "name": "New account limit" The account limit code is enabled.
Copy {
"code": "NEW_ACCOUNT_LIMIT",
"name": "New account limit",
"enabled": true
}
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v1/limits/codes' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTFUMTM6NDg6MDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODkwODMyODB9.w8DHO1S6HtsPCmAc98IG3F3b7bN2f2m7mlHoXf2gR4U' \
-H 'Content-Type: application/json' \
-d '{
"code": "NEW_ACCOUNT_LIMIT",
"name": "New account limit"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"code": "NEW_ACCOUNT_LIMIT",
"name": "New account limit",
"description": null,
"enabled": true
}
} Request to generate account transactions report Use case
In this example, we will review how to request to generate account transactions report.
Use case data
API parameters with values
The ID of the account from where the transactions report will be exported.
...accounts/ID-12333/transactions/export
The type of report file that is going to be generated. The exportFileType can be:
The transaction export time frame. For the dateType you can choose:
POSTING_DATE - is the current Tuum banking date when the account transaction was posted.
VALUE_DATE - is the date on which operation actually carries out or is supposed to carry out in the account. Must be the same or earlier than the posting date.
Sample API call
To request account transaction report, make the following call.
Sample request
In the sample below you will find information on how to request an account transactions report.
JSON
Copy {
"exportFileType": "JSON",
"dateFrom": "2029-04-01",
"dateTo": "2029-05-31",
"dateType": "POSTING_DATE"
} cURL
Copy curl --location 'https://reports-api.sandbox.tuumplatform.com/api/v4/accounts/ID-12333/transactions/export' \
--header 'x-channel-code: system' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEyMzgiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjUtMDMtMDdUMTg6MDA6NTYiLCJleHAiOjE3NDEzNzA0NTYsInJvbGVzIjpbIkFDQ09VTlRBTlQiLCJBRE1JTiJdfQ.BCgLd6S47mKEIZ0JG1ADMtc6ThjJlJPWPpv3pidIugk' \
--header 'Content-Type: application/json' \
--data '{
"exportFileType": "JSON",
"dateFrom": "2029-04-01",
"dateTo": "2029-05-31",
"dateType": "POSTING_DATE"
}' Sample response
Below you will find an example response to the API call from above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"generationId": "ID-2864",
"generationTypeCode": "ACCOUNT_TRANSACTIONS",
"groupTypeCode": "ACCOUNT",
"statusCode": "PENDING",
"createdDTime": "2025-03-07T17:21:10.04Z",
"inputJson": "{\"exportFileType\":\"JSON\",\"transactionType\":null,\"transactionSubtype\":null,\"dateFrom\":\"2029-04-01\",\"dateTo\":\"2029-05-31\",\"dateType\":\"POSTING_DATE\",\"directionCode\":null,\"amountFrom\":null,\"amountTo\":null,\"currencyCode\":null,\"contractNumber\":null,\"transactionGroupCodes\":null,\"referenceNumber\":null,\"counterpartyNameSubstring\":null,\"counterpartyAccountNumberSubstring\":null,\"detailsSubstring\":null,\"virtualAccountId\":null,\"source\":null,\"includeAccessRestricted\":false,\"uniqueIdentifier\":null}",
"errorCode": null,
"source": {
"sourceName": "ACCOUNT",
"sourceRef": "ID-12333"
},
"previewEnabled": false
}
} Result
As a result, an account transaction report was requested.
Sample account transaction export file
Create account type class rule 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.
Sample request
Below is an example request body of the API call for creating an account type class rule.
Sample response
Below you find an example response body to the API call above.
Result
A new account type class rule was created.
https://account-api.sandbox.tuumplatform.com/api/v4/accounts/{accountId}/transactions/export
See more about the
Below, you will find a sample of transaction export file. This way the file is structured after being
Use case data
API parameters
https://account-api.sandbox.tuumplatform.com/api/v1/account-type-class-rules
See more about the
Copy "exportFileType": "JSON"
Copy "dateFrom": "2029-04-01",
"dateTo": "2029-05-31",
"dateType": "POSTING_DATE"
Copy {
"accountTypeCode": "INTERNAL",
"accountClassCode": "NEW",
"validityRange": {
"startDate": "2023-07-31"
}
}
Copy 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"
}
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountTypeCode": "INTERNAL",
"accountClassCode": "NEW",
"validityRange": {
"startDate": "2023-07-31",
"endDate": null
},
"accountTypeClassRuleId": "ID-1007"
}
} Setting a new rule for the internal accounts type.
Copy "accountTypeCode": "INTERNAL"
Copy "accountClassCode": "NEW" The validity range of the rule. The validity range format: YYYY-MM-DD .
Copy "validityRange": {
"startDate": "2023-07-31"
} Search account transactions Use case
In this example, we will review how to fetch the account transactions.
Use case data
API parameters with values
Searching for transactions on the ID-1279 account.
...accounts/ID-1279/transactions...
The search from and to dates. The date format is: YYYY-MM-DD .
...search?dateFrom=2023-01-01&dateTo=2023-07-10...
The search data type is the posting date .
...&dateType=POSTING_DATE...
Requesting to display the search results on the first page; the page size is 5.
...&pageNumber=1&pageSize=5
Sample API call
To search the account transactions, make the following call.
Sample request
Below is the sample request to find account transactions.
JSON
Copy https://account-api.{{env}}.{{domain}}/api/v4/accounts/ID-1279/transactions/search?dateFrom=2023-01-01&dateTo=2023-07-10&dateType=POSTING_DATE&pageNumber=1&pageSize=5 cURL
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v4/accounts/ID-1279/transactions/search?dateFrom=2023-01-01&dateTo=2023-07-10&dateType=POSTING_DATE&pageNumber=1&pageSize=5' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTBUMTc6MDk6MzUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODkwMDg5NzV9.grNoFmnvoFcSb2IifdVKojVUQHZTwLU083wH2ci4fpc' \
-d '' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"values": [
{
"accountTransactionId": "ID-1183",
"groupId": "1190",
"postingDate": "2023-07-01",
"valueDate": "2023-07-01",
"accountId": "ID-1279",
"transactionTypeCode": "ACC_ADM_FEE",
"transactionSubtypeCode": null,
"directionCode": "OUT",
"currencyCode": "EUR",
"amount": 5.00,
"initialBalanceAmount": 0.00,
"filingCode": "2023070100001183",
"details": "Account maintenance fee",
"referenceNumber": null,
"source": {
"sourceName": "ACCOUNT.ACCOUNT_PERIODIC_FEE",
"sourceRef": "ID-1063",
"sourceLink": null
},
"contractSource": null,
"merchantInfo": null,
"metaInfo": null,
"createdDTime": "2023-07-01T00:00:09.294656Z",
"endToEndId": null,
"paymentServiceProviderCode": null,
"transactionDTime": "2023-07-01T00:00:09.963737Z",
"reversed": false,
"virtualAccountId": null,
"labels": [],
"counterparty": null
}
],
"pageNumber": 1,
"pageSize": 5,
"endReached": true,
"sort": null,
"total": 1
}
} Result
The details of the existing account transactions are fetched.
Create account application Use case
In this example, we will review how to create a currency account (account application) with an external service provider.
Use case data
API parameters with values
Creating a currency account.
The external provider is LHV.
The name of the account holder is Trevor Harry Tuum.
Trevor is assigned to the GROUP_A customer group.
The standard price list is assigned to the account.
The account currency is EUR.
The account interest rate is set to 10.
The account holder is a private person.
Sample API call
To create an account application, make the following API call.
Sample request
Below is an example request body of the API call for creating an account application.
JSON
Copy {
"accountTypeCode": "CURRENCY",
"accountTypeSetupCode": "EXTERNAL_VIRTUAL",
"serviceProviderCode": "LHV",
"accountName": "My business account",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"currencyCode": "EUR",
"accountInterestRate": 10,
"personTypeCode": "P"
} cURL
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v2/persons/ID-3392/applications' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMDVUMTg6MjI6MjEiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODg1ODEzNDF9.LFWDXWOCWurR4ywAhL-idPSQIVexdUXHad6h7p4mXJ0' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"accountTypeSetupCode": "EXTERNAL_VIRTUAL",
"serviceProviderCode": "LHV",
"accountName": "My business account",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"currencyCode": "EUR",
"accountInterestRate": 10,
"personTypeCode": "P"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountApplicationId": "ID-1007",
"personId": "ID-3392",
"applicationStatusCode": "INSERTED",
"accountTypeSetupCode": "EXTERNAL_VIRTUAL",
"accountTypeCode": "CURRENCY",
"accountClassCode": null,
"serviceProviderCode": "LHV",
"tenantCode": "MB",
"applicationDate": "2023-07-05",
"accountNumber": null,
"statusNote": null
}
} Result
A new account application ID-1007 is created.
Download requested report Use case
In this use case, we will review how to download an account transactions report.
Use case data
API parameters with values
...generations/files/ID-2864
Sample API call
Sample request
Below is an example request of the API call to get the report file.
cURL
Copy 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.
Copy [{"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.
Find person accounts Use case
In this example we will review how to find existing accounts by personId .
Use case data
API parameters with values
Searching for accounts that belong to the person ID-3392.
...persons/ID-3392/accounts...
Requesting to display the search results on the first page; the page size is 5.
...?pageNumber=1&pageSize=5
Sample API call
To find person accounts, make the following API call.
Find person account
GET https://account-api.sandbox.tuumplatform.com/api/v5/persons/{personId}/accounts
Sample request
Below is the example request of the call for finding person accounts.
JSON
Copy https://account-api.{{env}}.{{domain}}/api/v5/persons/ID-3392/accounts?pageNumber=1&pageSize=5 cURL
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v5/persons/ID-3392/accounts?pageNumber=1&pageSize=5' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTBUMTQ6NTk6MDUiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODkwMDExNDV9.CDrDuZ-2fAgeA_7KEdHNbjYup1tD8Vgs_kwkkDZ7NOw' \
-d '' Sample request
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"values": [
{
"accountId": "ID-1283",
"personId": "ID-3392",
"accountTypeCode": "VIRTUAL",
"activationDate": "2023-06-26",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "GB05XXXX04030100000462",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_B",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [],
"masterAccountId": "ID-1279",
"accountNumbers": [
{
"accountNumber": {
"value": "00000462",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040301",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1144",
"accountId": "ID-1283",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
},
{
"accountId": "ID-1282",
"personId": "ID-3392",
"accountTypeCode": "INTERNAL",
"activationDate": "2023-06-26",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "XX54XXXX99999000000000000001257",
"bic": "ICECLOUDXXX",
"defaultCurrencyCode": "EUR",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "INTERNAL",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1209",
"accountId": "ID-1282",
"currencyCode": "EUR",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "EUR",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
},
{
"accountId": "ID-1281",
"personId": "ID-3392",
"accountTypeCode": "INTERNAL",
"activationDate": "2023-06-26",
"accountName": "Internal BO",
"personName": "Trevor",
"statusCode": "ACTIVE",
"iban": "XX17XXXX99999000000000000001244",
"bic": "ICECLOUDXXX",
"defaultCurrencyCode": "EUR",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "INTERNAL",
"personTypeCode": "P",
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1208",
"accountId": "ID-1281",
"currencyCode": "EUR",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "EUR",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
},
{
"accountId": "ID-1279",
"personId": "ID-3392",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-06-19",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "GB72XXXX04030000000986",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1212",
"accountId": "ID-1279",
"currencyCode": "EUR",
"balanceAmount": -5.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": -4.24,
"negativeBalanceStartDate": "2023-07-01",
"availableBalanceAmount": -5.00
},
{
"balanceId": "ID-1206",
"accountId": "ID-1279",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00000986",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1143",
"accountId": "ID-1279",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
],
"pageNumber": 1,
"pageSize": 5,
"endReached": true,
"sort": null,
"total": 4
}
} Result
The person account information is fetched.
Reports Reports flow
If you need to generate and download the report, follow these steps:
Request to generate a report.
Check the report generation status.
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:
Check report generation status 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.
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
Set account access rights Use case
In this example, we will review how to create a currency account for a legal person and add access rights for a private person.
Sample API call
To create an account and set access rights, make the following call.
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 current account ID-1286 was created. The private person ID-3397 was granted all rights to the created account.
Account transactions report parameters On this page, you will find a list of parameters included in the account transactions report. The report is available in both CSV and JSON formats, with a similar parameter structure. The key difference is that in the JSON format, the following parameters are represented as nested objects:
transactionAmount : amount, currencyCode
initialBalanceAmount : amount, currencyCode
source : sourceName, sourceRef
counterparty : name, accountNumber, accountNumberSubtype, accountNumberCountryCode, financialInstitutionId
Update deposit product Use case
Note that you can completely modify the deposit product configuration when the deposit product is in the DRAFT status. Once the product is in the ACTIVE status, you can only update the interest conditions. When the product is in the INACTIVE status, you cannot modify any product fields.
In the table below, you will find a list of the settings that have been modified for the deposit product:
Sample API call
To update a deposit product, make the following API call.
Sample request
Below is an example request body for the API call to update a deposit product.
Sample response
Below, you find an example response body to the API call above.
Result
As a result, the following deposit product settings were updated:
The
https://account-api.sandbox.tuumplatform.com/api/v4/accounts/{accountId}/transactions/search
See more about the
https://account-api.sandbox.tuumplatform.com/api/v2/persons/{personId}/applications
See more information about the
The generationFileId is ID-2864 . This parameter is generated when
To find the status of the requested report, make the following API call.
reports-api.sandbox.tuumplatform.com/
/api/v1/generations/files/{generationFileId}
See more about the
https://account-api.sandbox.tuumplatform.com/api/v5/persons/{personId}/accounts
See more information about the
See more information about this
Use case data
API parameters with values
reports-api.sandbox.tuumplatform.com/
api/v2/generations/{generationId}
See more about the
This endpoint returns the status of the account transactions report. When the statusCode has a value DONE, the report is ready for generationFileId of the report file is ID-2864.
Use case data
API parameters with values
https://account-api.sandbox.tuumplatform.com/api/v4/persons/{personId}/accounts
See more about the
Parmeter name
Type
Description
In this use case, we will review how to update a deposit product. We will change the deposit product that was created in a
Use case data
API parameters with values
deposit-api.sandbox.tuumplatform.com/
api/v2/deposits/product/{depositTypeCode}
See more information about the
Copy "accountTypeCode": "CURRENCY"
Copy "accountTypeSetupCode": "EXTERNAL_VIRTUAL",
"serviceProviderCode": "LHV",
Copy "personName": "Trevor Harry Tuum"
Copy "customerGroupCode": "GROUP_A"
Copy "priceListTypeCode": "STANDARD"
Copy "currencyCode": "EUR"
Copy "accountInterestRate": 10
Copy "personTypeCode": "P"
Copy curl --location --request GET 'https://reports-api.sandbox.tuumplatform.com/api/v2/generations/ID-4714' \
--header 'x-channel-code: system' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEyMzgiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjUtMDMtMDdUMTg6MzY6NTAiLCJleHAiOjE3NDEzNzI2MTAsInJvbGVzIjpbIkFDQ09VTlRBTlQiLCJBRE1JTiJdfQ.WMgoNN6FnntbkVsSxBZtI6mosBNnoOWBrC14reJ9RJM' \
--header 'Content-Type: application/json' \
--data '{
"accountTypeCode": "INTERNAL",
"personName": "Trevor Harry Tuum",
"residencyCountryCode": "GB",
"customerGroupCode": "INTERNAL",
"priceListTypeCode": "INTERNAL",
"currencyCode": "EUR"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"generationId": "ID-2864",
"generationTypeCode": "ACCOUNT_TRANSACTIONS",
"generationGroupCode": "ACCOUNT",
"statusCode": "DONE",
"createdDTime": "2025-03-07T17:57:04.304Z",
"entryDate": null,
"inputJson": "{\"exportFileType\":\"JSON\",\"transactionType\":null,\"transactionSubtype\":null,\"dateFrom\":\"2029-04-01\",\"dateTo\":\"2029-05-31\",\"dateType\":\"POSTING_DATE\",\"directionCode\":null,\"amountFrom\":null,\"amountTo\":null,\"currencyCode\":null,\"contractNumber\":null,\"transactionGroupCodes\":null,\"referenceNumber\":null,\"counterpartyNameSubstring\":null,\"counterpartyAccountNumberSubstring\":null,\"detailsSubstring\":null,\"virtualAccountId\":null,\"source\":null,\"includeAccessRestricted\":false,\"uniqueIdentifier\":null}",
"errorCode": null,
"source": {
"sourceName": "ACCOUNT",
"sourceRef": "ID-12333"
},
"fileInfos": [
{
"generationFileId": "ID-2864",
"fileName": "account-transactions-ID-12333-20250307-1757-04-365.json",
"storageSource": null,
"additionalData": null
}
],
"previewJson": null
}
} The legal account ID-3397.
...persons/ID-3397/accounts
The private person ID-3392 is granted all rights to the bank account of the legal person.
Copy "representatives": [
{
"personId": "ID-3392",
"accountRightCode": "ALL",
Copy {
"accountTypeCode": "CURRENCY",
"personName": "Trevor Harry Tuum",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP",
"representatives": [
{
"personId": "ID-3392",
"accountRightCode": "ALL",
"limits": [
{
"amount": {
"amount": "1000",
"currencyCode": "GBP"
},
"accountLimitTypeCode": "DAILY"
},
{
"amount": {
"amount": "10000",
"currencyCode": "GBP"
},
"accountLimitTypeCode": "MONTHLY"
}
]
}
]
}
Copy curl -L 'https://account-api.sandbox.tuumplatform.com/api/v4/persons/ID-3397/accounts' \
-H 'x-channel-code: SYSTEM' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMDZUMTQ6NDE6NTAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2ODg2NTQ1MTB9.qDVHzIowyGFM-XRG9xEktcwaA6YNf6WhPNp6yw4aTzE' \
-H 'Content-Type: application/json' \
-d '{
"accountTypeCode": "CURRENCY",
"personName": "Trevor Harry Tuum",
"customerGroupCode": "GROUP_A",
"priceListTypeCode": "STANDARD",
"residencyCountryCode": "GB",
"currencyCode": "GBP",
"representatives": [
{
"personId": "ID-3392",
"accountRightCode": "ALL",
"limits": [
{
"amount": {
"amount": "1000",
"currencyCode": "GBP"
},
"accountLimitTypeCode": "DAILY"
},
{
"amount": {
"amount": "10000",
"currencyCode": "GBP"
},
"accountLimitTypeCode": "MONTHLY"
}
]
}
]
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"accountId": "ID-1286",
"personId": "ID-3397",
"accountTypeCode": "CURRENCY",
"activationDate": "2023-07-06",
"accountName": null,
"personName": "Trevor Harry Tuum",
"statusCode": "ACTIVE",
"iban": "GB12XXXX04030000000999",
"bic": "LHVBGB2LXXX",
"defaultCurrencyCode": "GBP",
"tenantCode": "MB",
"residencyCode": "GB",
"customerGroupCode": "GROUP_A",
"personTypeCode": null,
"intraOrgCode": null,
"accountTypeSetupCode": "STANDARD",
"serviceProviderCode": "TUUM",
"interestMethodAssignmentCode": null,
"accountClassCode": null,
"balances": [
{
"balanceId": "ID-1213",
"accountId": "ID-1286",
"currencyCode": "GBP",
"balanceAmount": 0.00,
"reservedAmount": 0.00,
"overdraftLimitAmount": 0.00,
"defaultCurrencyCode": "GBP",
"availableBalanceInDefaultCcy": 0.00,
"negativeBalanceStartDate": null,
"availableBalanceAmount": 0.00
}
],
"masterAccountId": null,
"accountNumbers": [
{
"accountNumber": {
"value": "00000999",
"type": "BBAN"
},
"countryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"defaultCurrencyCode": "GBP",
"accountNumberId": "ID-1145",
"accountId": "ID-1286",
"financialInstitutionIdTypeCode": null,
"statusCode": "ENABLED"
}
],
"taxResidencyCountryCode": "GB",
"jurisdictionCountryCode": "GB"
}
}o Transaction Id number.
Example: ID-275388
Transaction groupId.
Example: 290379
Posting date is the current Tuum banking date when the account transaction was posted to the Account API.
Date format: YYYY-MM-DD .
Example: 2029-04-01
The account number from where the account transactions are extracted.
Example: ID-12333
The transaction type code.
Example: ACC_ADM_FE
Transaction direction.
Example: OUT
Initial balance amount.
Example: 3989.97
Transaction amount.
Example: 12.4
Transaction currency.
Example: EUR
Transaction counterparty name.
Example: Simon Parker
counterpartyAccountNumber
Counterparty account number.
Example: EE871275295834652820
counterpartyAccountNumberTypeCode
Counterparty account number type.
Example: IBAN
counterpartyAccountNumberSubtype
Counterparty account number subtype.
counterpartyAccountNumberCountryCode
Counterparty account number country code.
Example: EE
counterpartyFinancialInstitutionId
Counterparty financial institution Id.
Example: PARXEE22XXX
counterpartyFinancialInstitutionIdTypeCode
Counterparty financial institution type.
Example: BIC
Transaction details.
Example: Account maintenance fee
Transaction meta info.
Example: {"paymentResidencyCountryCode":"LV","intrabankPaymentSource":null,"paymentMetaInfo":"[{"typeCode":"SELECTED_SCHEME","value":"SEPA_REGULAR"}]"}
End to end Id.
Example: 2222223
Transaction date-time.
Format: YYYY-MM-DDThh:mm:ss.sssZ
Example: 2025-02-28T11:23:58.16Z
paymentServiceProviderCode
Payment service provider code.
Example: SEPA
Transaction labels.
Example: SEPA_REGULAR
Transaction reference number.
Contract source name.
Example: LOAN.CONTRACT_HEADER
Contract source reference.
Example: ID-1718026338
Value date is
the date on which operation actually carries out or is supposed to carry out in the account. Must be the same or earlier than the posting date.
Date format: YYYY-MM-DD .
Example: 2029-04-01
Defines if the transaction is reversed.
Example: false
Id number of the reversed transaction.
Technical code assigned to the transaction record.
Example: 2029040100275388
Account transaction report date type.
Example: POSTING_DATE
Domain code.
Example: PMNT
Transaction family code.
Example: RCDT
Transaction subfamily code.
Example: FEES
Transaction source name.
Example: ACCOUNT.ACCOUNT_PERIODIC_FEE
Transaction source reference.
Example: ID-78253
Transaction group code.
Example: FEE
Transaction unique identifier.
Example: 1f78c038-96a6-4882-925e-ce8cd2668220
The product description is updated.
Copy "description": "Premium deposit Germany" The deposit country is set to Germany.
The contract number prefix is modified.
Copy "contractNumberPrefix": "PR-DE-" The premature deposit contract termination is with interest.
Copy "terminationType": "WITH_TOTAL_INTEREST" The deposit contract period is 12 months.
The deposit is offered for legal entities.
Copy "personTypeCode": "L" The deposit product end is updated.
Note: the date format is YYYY-MM-DD .
Copy "endDate": "2031-02-08"
Copy {
"description": "Premium deposit Germany"
"depositGroupCode": "TIME_DEPOSIT"
"countryCode": "DE"
"currencyCode": "EUR"
"contractNumberPrefix": "PR-DE-"
"offerValidDays": 1
"daysToWaitCredit": 2
"calculateTaxesEnabled": false,
"terminationType": "WITH_TOTAL_INTEREST"
"interestCalculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"interestPeriodSelector": "FIXED",
"interests": [
{
"amountRange": {
"startValue": 6000,
"endValue": 100001
},
"interestRate": 0.25,
"periodRange": {
"startValue": 0,
"endValue": 0
},
"period": 12,
"periodTypeCode": "MONTH",
"paymentFrequencyTypeCode": "END",
"validityRange": {
"startDate": "2027-02-08",
"endDate": "2031-02-08"
}
}
],
"personTypeCode": "L"
}
Copy curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/deposits/product/PREMIUM' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDUtMDNUMjA6NDQ6MDMiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE3MTQ3NjkwNDN9.rdBXcIkNYRWcVC_iNUuYaVnaEIuN3my3L3d2hNlwSK8' \
--header 'Content-Type: application/json' \
--data '{
"description": "Premium deposit Germany",
"depositGroupCode": "TIME_DEPOSIT",
"countryCode": "DE",
"currencyCode": "EUR",
"contractNumberPrefix": "PR-DE-",
"offerValidDays": 1,
"daysToWaitCredit": 2,
"calculateTaxesEnabled": false,
"terminationType": "WITH_TOTAL_INTEREST",
"interestCalculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"interestPeriodSelector": "FIXED",
"interests": [
{
"amountRange": {
"startValue": 6000,
"endValue": 100001
},
"interestRate": 0.25,
"periodRange": {
"startValue": 0,
"endValue": 0
},
"period": 12,
"periodTypeCode": "MONTH",
"paymentFrequencyTypeCode": "END",
"validityRange": {
"startDate": "2027-02-08",
"endDate": null
}
}
],
"personTypeCode": "P"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": null
} ...api/v2/generations/ID-ID-2864
Activate deposit product Use case
Use case data
API parameters with values
The path parameter is depositTypeCode . We will use the PREMIUM deposit product.
.../product/PREMIUM/activate
Sample API call
To activate a deposit product, make the following API call.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
As a result, the PREMIUM deposit product was activated.
Deposit product management Instructions in this section will help you to manage deposit products throughout their lifecycle.
Below you will find the following chapters:
Create deposit class code 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.
Use case data
API parameters with values
The new class code is created for the premium customers group.
Sample API call
To create a new deposit class code, make the following API call.
Sample request
Below is an example request body of the API call for creating a deposit class code.
JSON
Copy {
"description": "Class code for premium customers",
"depositClassCode": "PREMIUM_CUSTOMER"
} cURL
Copy 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.
Copy {
"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.
Create deposit application Use case
In this example, we will review how to create a deposit application with a minimum data set.
Use case data
API parameters with values
We will create a deposit application for a test person whose account ID is ID-2660.
...persons/ID-2660/applications
The amount that the test person is going to deposit is 5000 EUR.
The deposit is offered with the 3 month duration. The interest will be paid at the end of the contract period. The deposit's jurisdiction country is Estonia.
The tax residency code determines which tax rate is enabled for this country when deducting the tax from the interest during the pay out.
The tax exempt is false by default.
Note: the taxResidencyCountryCode and taxExempt parameters are editable even after the deposit contract is created or activated.
Sample API call
Sample request
Below is an example request body of the API call for creating a deposit application.
JSON
Copy {
"initialMoney": {
"amount": 5000,
"currencyCode": "EUR"
},
"depositTypeCode": "PREMIUM",
"accountId": "ID-5334",
"period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"countryCode": "EE",
"taxResidencyCountryCode": "EE",
"taxExempt": "false"
} cURL
Copy curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v2/persons/ID-2660/applications' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjQtMDUtMjlUMTc6MjM6MDQiLCJleHAiOjE3MTcwMDMzODQsInJvbGVzIjpbIkFETUlOIl19.RyH47_HA4Run4sJtIGeiJmxhlN8sCin_GnGLH_6qKZc' \
--header 'Content-Type: application/json' \
--data '{
"initialMoney": {
"amount": 5000,
"currencyCode": "EUR"
},
"depositTypeCode": "PREMIUM",
"accountId": "ID-5334",
"period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"countryCode": "EE",
"taxResidencyCountryCode": "EE",
"taxExempt": "false"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"applicationId": "ID-1696407202",
"personId": "ID-2660",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"statusCode": "ACCEPTED",
"accountId": "ID-5334",
"period": 3,
"periodTypeCode": "MONTH",
"endDate": null,
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"interestPaymentFreqCode": "END",
"prolongationCode": null,
"countryCode": "EE",
"interestRate": 0.25,
"postingDate": "2024-11-14",
"channelCode": "SYSTEM",
"tenantCode": "MB",
"offerId": null,
"depositClassCode": "PREMIUM_CUSTOMER",
"payoutDetails": null,
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false
}
}
Result
As a result, a new deposit application ID-1696407202 was created.
Find deposit application Use case
Use case data
API parameters with values
...v2/persons/ID-2660/applications
This API call requires mandatory query parameters pageSize and pageNumber .
...?pageSize=1&pageNumber=1
Sample API call
To find a deposit application, make the following API call.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"values": [
{
"applicationId": "ID-1696407202",
"personId": "ID-2660",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM_TEST",
"statusCode": "ACCEPTED",
"accountId": "ID-5334",
"period": 3,
"periodTypeCode": "MONTH",
"endDate": null,
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"interestPaymentFreqCode": "END",
"prolongationCode": null,
"countryCode": "EE",
"interestRate": 0.25,
"postingDate": "2024-11-14",
"channelCode": "SYSTEM",
"tenantCode": "MB",
"offerId": null,
"depositClassCode": "PREMIUM_CUSTOMER",
"payoutDetails": null,
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false
}
],
"pageNumber": 1,
"pageSize": 1,
"endReached": true,
"sort": null
}
} Result
As a result we found the deposit application with the ID-1696407202 and fetched other information related to the deposit application.
Edit deposit offer Use case
In this example, we will review how to edit a deposit offer.
Sample API call
To edit a deposit offer, make the following API call.
Sample request
Below is an example request body of the API call for editing a deposit offer.
Sample response
Below you find an example response body to the API call above.
Result
As a result the deposit offer ID-1718024058 was updated. The initial offer amount was changed.
The generationId number of the report file that was
In this use case we will activate a new deposit product that was created as a
deposit-api.sandbox.tuumplatform.com/api/v1/deposits/product/{depositTypeCode}/activate
See more information about the
deposit-api.sandbox.tuumplatform.com/api/v1/deposit-class-codes
See more about the
The deposit application is opened for a PREMIUM
The servicing account ID that is tied to the deposit. Note: see the
deposit-api.sandbox.tuumplatform.com/api/v2/persons/{personId}/applications
See more information about the
In this case, we will review how to find the ID of a person ID .
We will find an existing ID-2660.
deposit-api.sandbox.tuumplatform.com/api/v3/persons/{personId}/applications
See more about the
Use case data
API parameters with values
deposit-api.sandbox.tuumplatform.com/api/v2/offers/{offerId}
See more about the
Copy {
"description": "Class code for premium customers",
"depositClassCode": "PREMIUM_CUSTOMER"
}
Copy "initialMoney": {
"amount": 5000,
"currencyCode": "EUR"
}
Copy "depositTypeCode": "PREMIUM"
Copy "accountId": "ID-5334"
Copy "period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"countryCode": "EE"
Copy "taxResidencyCountryCode": "EE",
"taxExempt": "false" We will change the deposit offer ID-1718024058.
We will change the deposit offer initial amount from 5000 EUR to 6000 EUR.
Copy "initialMoney": {
"amount": 6000,
"currencyCode": "EUR"
}
Copy {
"initialMoney": {
"amount": 6000,
"currencyCode": "EUR"
},
"period": 3,
"interestPaymentFreqCode": "END",
"taxResidencyCountryCode": "EE",
"prolongationCode": "PRINCIPAL",
"taxExempt": "false",
"interestRate": 0.35
}
Copy curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/offers/ID-1718024058' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMzBUMTM6MzI6MjgiLCJleHAiOjE3MzAyOTUxNDgsInJvbGVzIjpbIkFETUlOIl19.7g3ys-QseNqtzu6P5l5lEdpj1tk5izFT10f4AEc9RVo' \
--header 'Content-Type: application/json' \
--data '{
"initialMoney": {
"amount": 6000,
"currencyCode": "EUR"
},
"period": 3,
"interestPaymentFreqCode": "END",
"taxResidencyCountryCode": "EE",
"prolongationCode": "PRINCIPAL",
"taxExempt": "false",
"interestRate": 0.35
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"offerId": "ID-1718024058",
"personId": "ID-2660",
"applicationId": null,
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "COPY_PREMIUM_NEW",
"terminationType": "WITHOUT_INTEREST",
"statusCode": "PRESENTED",
"reasonCode": null,
"accountId": "ID-1012",
"interestRate": 0.35,
"period": 3,
"periodTypeCode": "MONTH",
"endDate": null,
"initialMoney": {
"amount": 6000.00,
"currencyCode": "EUR"
},
"interestPaymentFreqCode": "END",
"prolongationCode": "PRINCIPAL",
"countryCode": "EE",
"maturityDate": "2027-04-26",
"returnAmount": {
"amount": 6005.25,
"currencyCode": "EUR"
},
"postingDate": "2027-01-26",
"lastValidDate": "2027-01-27",
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"contractHeaderId": null,
"contractNumber": null,
"depositClassCode": "PREMIUM_CUSTOMER",
"payoutDetails": {
"name": "Test User",
"accountNumber": {
"value": "EE961221248796768756",
"type": "IBAN"
},
"financialInstitutionId": null,
"referenceNumber": null,
"countryCode": null
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false,
"marginRate": null
}
} Inactivate deposit product Use case
In this example, we will review how to deactivate a deposit product.
Use case data
API parameters with values
The path parameter is depositTypeCode . We will use the PREMIUM deposit product.
...product/PREMIUM/deactivate
Sample API call
To deactivate a deposit product, make the following API call.
Sample response
Below, you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
As a result, the PREMIUM deposit product was deactivated.
Find deposit product Use case
Use case data
API parameters with values
The path parameter is depositTypeCode . We will use the PREMIUM deposit product.
...deposits/product/PREMIUM
Sample API call
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"depositTypeCode": "PREMIUM",
"depositGroupCode": "TIME_DEPOSIT",
"description": "Premium deposit",
"tenantCode": "MB",
"statusCode": "ACTIVE",
"countryCode": "EE",
"currencyCode": "EUR",
"contractNumberPrefix": "PR-EE-",
"offerValidDays": 1,
"daysToWaitCredit": 2,
"calculateTaxesEnabled": false,
"terminationType": "WITHOUT_INTEREST",
"signatureRequired": false,
"daysToWaitSignature": null,
"fileGenerationRequired": false,
"withdrawalAllowed": false,
"autoProlongationAllowed": true,
"interestCalculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"interestPeriodSelector": "FIXED",
"interests": [
{
"interestId": "ID-1696407383",
"amountRange": {
"startValue": 5000,
"endValue": 100001
},
"periodTypeCode": "MONTH",
"period": 3,
"periodRange": null,
"interestRate": 0.25,
"minInterestRate": null,
"maxInterestRate": null,
"paymentFrequencyTypeCode": "END",
"validityRange": {
"endDate": null,
"startDate": "2027-01-09"
},
"depositTypeCode": "PREMIUM",
"employeeId": "1"
}
],
"depositClassCode": "PREMIUM_CUSTOMER"
}
} Result
As a result, a complete set of product details about the PREMIUM deposit product was returned.
Decline deposit offer Use case
In this example, we will review how to decline a deposit offer.
Use case data
API parameters with values
We will decline a deposit offer ID-1718023944.
...offers/ID-1718023944/decline
Sample API call
Sample request
Below is an example request body of the API call for declining a deposit offer.
JSON
Copy {
"reasonCode": "DOCUMENT_MISSING"
} cURL
Copy curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v3/offers/ID-1718023944/decline' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMDYtMjdUMDk6NDU6NTgiLCJleHAiOjE3MTk0ODE1NTgsInJvbGVzIjpbIkFETUlOIl19.Iek0Ie70FXaTaduvpSat17RcEV8KPp9c9JsL14S1QOU' \
--header 'Content-Type: application/json' \
--data '{
"reasonCode": "DOCUMENT_MISSING"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"offerId": "ID-1718023943",
"personId": "ID-1015",
"applicationId": null,
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"terminationType": "WITHOUT_INTEREST",
"statusCode": "DECLINED",
"reasonCode": null,
"accountId": "ID-1012",
"interestRate": 0.25,
"period": 3,
"periodTypeCode": "MONTH",
"endDate": null,
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"interestPaymentFreqCode": "MONTH",
"prolongationCode": "PRINCIPAL",
"countryCode": "EE",
"maturityDate": "2025-03-30",
"returnAmount": {
"amount": 5003.12,
"currencyCode": "EUR"
},
"postingDate": "2024-12-30",
"lastValidDate": "2024-12-31",
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"contractHeaderId": null,
"contractNumber": null,
"depositClassCode": "PREMIUM_CUSTOMER",
"payoutDetails": {
"name": "Tech Writing",
"accountNumber": {
"value": "XX47XXXX99999000000000000000122",
"type": "IBAN"
},
"financialInstitutionId": null,
"referenceNumber": null,
"countryCode": null
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false
}
} Result
As a result, a deposit offer ID-1718023943 was declined.
Deposit flow 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:
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:
Below, you will find the following chapters:
Create deposit product Use case
Here we will review how to create a deposit product with the minimum set of data:
Use case data
API parameters with values
The description of the deposit product.
The deposit group code. Currently, the TIME_DEPOSIT is the only available value.
A unique code for product identification.
It must be a unique value and can contain uppercase letters, numbers, and the special characters “-” (dash), “_” (underscore), and “.” (full-stop). Spaces are not allowed.
The code of the tenant where the deposit product is going to be opened.
The deposit product country is Estonia and the currency is euro.
A contract number prefix.
It must be a unique value and can contain uppercase letters, numbers, and the special characters “-” (dash), “_” (underscore), “/” (slash), and “.” (full-stop). Spaces are not allowed.
The deposit offer opened based on this product will be valid for 1 day.
The number of days that the system will wait for the contracts of this product type to receive the deposit balance amount from the servicing account. If the expected deposit amount is not received
within 2 days, the system cancels the deposit product.
The premature contract termination is without interest.
The automatic prolongation of the deposit contract is allowed.
Deposit product interest settings:
Interest calculation method 30/360 - considers that each month has 30 days and there are 360 days in a year.
Interest conditions are applied for a fixed period of time.
The amount that the customer can deposit is a range from 5000 to 10000 EUR . Note: The endValue is an exclusive parameter.
The default deposit interest rate is 0.25 .
The minimum interest rate is 0.21 and the maximum is 0.75 .
The deposit period is 3 months .
The deposit interest is paid out at the end of the deposit period.
This deposit product holder is a private person.
Sample API call
To create a deposit product, make the following API call.
Sample request
Below is an example request body of the API call for creating a deposit product.
JSON
Copy {
"description": "Premium deposit",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"tenantCode": "MB",
"countryCode": "EE",
"currencyCode": "EUR",
"contractNumberPrefix": "PR-EE-",
"offerValidDays": 1,
"daysToWaitCredit": 2,
"terminationType": "WITHOUT_INTEREST",
"autoProlongationAllowed": true,
"interestCalculationMethod":
{
"daysInMonth": "30",
"daysInYear": 360
},
"interestPeriodSelector": "FIXED",
"interests": [
{
"amountRange": {
"startValue": 5000,
"endValue": 100001
},
"interestRate": 0.25,
"minInterestRate": 0.21,
"maxInterestRate": 0.75,
"period": 3,
"periodTypeCode": "MONTH",
"paymentFrequencyTypeCode": "END",
"validityRange": {
"startDate": "2027-01-09"
}
}
],
"depositClassCode": "PREMIUM_CUSTOMER",
"personTypeCode": "P"
}
cURL
Copy curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v2/deposits/product' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDItMjJUMTk6MTc6MDAiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MDg2Mjk0MjB9.Np7yiNhKpkY35dIPSBD8h1qMoe9zz4IRbsHYZnnoBlo' \
--data '{
"description": "Premium deposit",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"tenantCode": "MB",
"countryCode": "EE",
"currencyCode": "EUR",
"contractNumberPrefix": "PR-EE-",
"offerValidDays": 1,
"daysToWaitCredit": 2,
"terminationType": "WITHOUT_INTEREST",
"autoProlongationAllowed": true,
"interestCalculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"interestPeriodSelector": "FIXED",
"interests": [
{
"amountRange": {
"startValue": 5000,
"endValue": 100001
},
"interestRate": 0.25,
"minInterestRate": 0.21,
"maxInterestRate": 0.75,
"periodRange": {
"startValue": 0,
"endValue": 0
},
"period": 3,
"periodTypeCode": "MONTH",
"paymentFrequencyTypeCode": "END",
"validityRange": {
"startDate": "2027-01-09",
"endDate": null
}
}
],
"depositClassCode": "PREMIUM_CUSTOMER",
"personTypeCode": "P"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": null
} Result
As an outcome, a new deposit product was created in a DRAFT status.
Create deposit offer Use case
In this example we will review the first step of the deposit contract origination flow that starts with creating a deposit offer.
Sample API call
POST /deposit-api.sandbox.tuumplatform.com/api/v2/persons/{personId}/offers
Sample request
Below is an example request body of the API call for creating a deposit offer.
Sample response
Below you find an example response body to the API call above.
Result
As an outcome, a new deposit offer ID-1718024058 was created.
deposit-api.sandbox.tuumplatform.com/api/v1/deposits/product/{depositTypeCode}/deactivate
See more information about the
In this example, we will find the
deposit-api.sandbox.tuumplatform.com/api/v1/deposits/product/{depositTypeCode}
See more about the
deposit-api.sandbox.tuumplatform.com/api/v3/offers/{offerId}/decline
See more information about the
The
deposit-api.sandbox.tuumplatform.com/api/v2/deposits/product
See more information about the
Use case data
API parameters with values
See more information about the
Copy "description": "Premium deposit"
Copy "depositGroupCode": "TIME_DEPOSIT"
Copy "depositTypeCode": "PREMIUM"
Copy "countryCode": "EE",
"currencyCode": "EUR"
Copy "contractNumberPrefix": "PR-EE-"
Copy "offerValidDays": 1,
"daysToWaitCredit": 2
Copy "terminationType": "WITHOUT_INTEREST",
"autoProlongationAllowed": true
Copy "interestCalculationMethod":
{
"daysInMonth": "30",
"daysInYear": 360
},
"interestPeriodSelector": "FIXED",
"interests": [
{
"amountRange": {
"startValue": 5000,
"endValue": 10001
},
"interestRate": 0.25,
"minInterestRate": 0.21,
"maxInterestRate": 0.75,
"period": 3,
"periodTypeCode": "MONTH",
"paymentFrequencyTypeCode": "END",
"validityRange": {
"startDate": "2027-01-09",
}
}
],
Copy "depositClassCode": "PREMIUM_CUSTOMER"
Copy "personTypeCode": "P"
Copy {
"depositTypeCode": "PREMIUM",
"accountId": "ID-1012",
"period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"initialMoney": {
"amount": 5000,
"currencyCode": "EUR"
},
"countryCode": "EE",
"payoutDetails": {
"name": "Test user",
"accountNumber": {
"value": "EE961221248796768756",
"type": "IBAN"
}
},
"taxResidencyCountryCode": "EE",
"interestRate": 0.35
}
Copy curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v2/persons/ID-1015/offers' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMjlUMjA6MTI6MzEiLCJleHAiOjE3MzAyMzI3NTEsInJvbGVzIjpbIkFETUlOIl19.ViX6Uwnv1n_h2cBxprFUJRxlXJGce0_A1F5o-HA04oE' \
--header 'Content-Type: application/json' \
--data '{
"depositTypeCode": "PREMIUM",
"accountId": "ID-1012",
"period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"initialMoney": {
"amount": 5000,
"currencyCode": "EUR"
},
"countryCode": "EE",
"payoutDetails": {
"name": "Test user",
"accountNumber": {
"value": "EE961221248796768756",
"type": "IBAN"
}
},
"taxResidencyCountryCode": "EE",
"interestRate": 0.35
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"offerId": "ID-1718024058",
"personId": "ID-2660",
"applicationId": null,
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"terminationType": "WITHOUT_INTEREST",
"statusCode": "PREPARING",
"reasonCode": null,
"accountId": "ID-1012",
"interestRate": 0.35,
"period": 3,
"periodTypeCode": "MONTH",
"endDate": null,
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"interestPaymentFreqCode": "END",
"prolongationCode": null,
"countryCode": "EE",
"maturityDate": "2027-04-21",
"returnAmount": {
"amount": 5004.38,
"currencyCode": "EUR"
},
"postingDate": "2027-01-21",
"lastValidDate": "2027-01-22",
"channelCode": "SYSTEM",
"tenantCode": "MB",
"contractHeaderId": null,
"contractNumber": null,
"depositClassCode": "PREMIUM_CUSTOMER",
"payoutDetails": {
"name": "Test user",
"accountNumber": {
"value": "EE961221248796768756",
"type": "IBAN"
},
"financialInstitutionId": null,
"referenceNumber": null,
"countryCode": null
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false,
"marginRate": null
}
} We will create a deposit offer for a test person whose account ID is ID-2660.
...persons/ID-2660/offers
Copy "depositTypeCode": "PREMIUM"
Copy "accountId": "ID-1012" The deposit is offered with the 3 month duration. The interest will be payed at the end of the contract period. The deposit country is Estonia.
Copy "period": 3,
"periodTypeCode": "MONTH",
"interestPaymentFreqCode": "END",
"countryCode": "EE" The deposit amount is 5000 EUR.
Copy "initialMoney": {
"amount": 5000,
"currencyCode": "EUR" Upon maturity of the deposit contract, the deposit API transfers the payout to the designated payout account. If payout details are not provided, the payout is automatically directed to the servicing account.
Copy "payoutDetails": {
"name": "Test user",
"accountNumber": {
"value": "EE961221248796768756",
"type": "IBAN"
}
} The default deposit interest rate is set at 0.35.
Note: If the deposit product has a defined minimum and maximum interest rate range, you can set a custom interest rate within this range to override the default rate. If no interest range is defined for the deposit product, the default interest rate of 0.35 is applied.
Deposit contract management 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:
Find deposit offer Use case
In this example, we will review how to find a deposit offer using the application ID.
Use case data
API parameters with values
...applications/ID-1696407202/offers
Sample API call
To find a deposit offer that was automatically created by the deposit application, make the following API call.
Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"offerId": "ID-1696407305",
"personId": "ID-2660",
"applicationId": "ID-1696407202",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM_TEST",
"terminationType": "WITHOUT_INTEREST",
"statusCode": "PRESENTED",
"reasonCode": null,
"accountId": "ID-1012",
"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 an outcome, we found the deposit offer ID ID-1696407305 and fetched related details.
The deposit offer is opened for a PREMIUM
The account ID that is tied to the deposit.
Note: see the
Searching the deposit offer that was created for the ID-1696407202.
deposit-api.sandbox.tuumplatform.com/api/v2/applications/{applicationId}/offers
See more about the
Find deposit contract Use case
Use case data
API parameters with values
...v2/persons/ID-2660/contracts
This API call requires mandatory query parameters pageSize and pageNumber .
...?pageSize=1&pageNumber=1
Sample API call
Sample response
Below you will find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"values": [
{
"headerId": "ID-1696407222",
"personId": "ID-2660",
"accountId": "ID-1012",
"applicationId": "ID-1696407202",
"offerId": "ID-1696407305",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM_TEST",
"contractNumber": "PR-EE-1000",
"countryCode": "EE",
"channelCode": "SYSTEM",
"tenantCode": "MB",
"depositClassCode": null,
"headerActivationDate": null,
"headerClosingDate": null,
"activeVersion": {
"versionId": "ID-1718023938",
"headerId": "ID-1718023942",
"versionNumber": 1,
"statusCode": "ACTIVE",
"preparationDate": "2024-11-15",
"signingDate": null,
"activationDate": null,
"endDate": "2025-02-15",
"closingDate": null,
"period": 3,
"periodTypeCode": "MONTH",
"interestRate": 0.25,
"interestPaymentFrequencyCode": "END",
"prolongCode": null,
"countryCode": "EE",
"cancelReasonCode": "CREDIT_PERIOD_PASSED",
"lastCreditReceiveDate": "2024-11-17",
"lastSigningDate": null,
"changeTypeCode": "NEW_CONTRACT",
"components": [
{
"componentId": "ID-1718023964",
"versionId": "ID-1718023938",
"componentTypeCode": "PRI",
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"calculationMethod": null,
"rateBaseCode": null,
"rate": null,
"accruedUntil": null,
"paymentDay": 15,
"paymentInterval": 1,
"baseInvalidFromDate": null
},
{
"componentId": "ID-1718023965",
"versionId": "ID-1718023938",
"componentTypeCode": "INT",
"initialMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"calculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"rateBaseCode": "FIX",
"rate": 0.25,
"accruedUntil": null,
"paymentDay": 15,
"paymentInterval": 1,
"baseInvalidFromDate": null
}
],
"totalInterestMoney": {
"amount": 3.13,
"currencyCode": "EUR"
},
"totalInterestAccruedMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"channelCode": "SYSTEM",
"tenantCode": "MB",
"terminationType": "WITHOUT_INTEREST",
"nextPayoutDate": null,
"payoutDetails": null
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false
}
],
"pageNumber": 1,
"pageSize": 1,
"endReached": true,
"sort": null
}
} Result
As a result, we found the deposit contract number PR-EE-1000 with headerId ID-1696407222 and activeVersionId ID-1696407267.
Change contract prolongation status Use case
Use case data
API parameters with values
...v2/contracts/ID-1696407222/...
...versions/ID-1696407267/payment-instructions
We will change prolongation status to principal with interest. With this setting when the deposit contract is automatically prolonged, the interest is moved to principal.
Prolongation types
The prolongationCode parameter can have one of the following values:
PRINCIPAL - The deposit contract is extended to a new period with only the initial deposit principal amount. All interest accrued during the term will be paid out to the payout account defined for the deposit.
PRINCIPAL_WITH_INTEREST - The deposit contract is extended to a new period with both the initial deposit principal amount and the interest accrued during the previous term. The interest is capitalised, meaning it is added to the initial principal amount, resulting in a new principal amount for the next term period.
Sample API call
To change the deposit contract prolongation details, make the following API call.
Sample request
Below is an example request body of the API call for changing deposit contract payout details.
JSON
Copy {
"prolongationCode": "PRINCIPAL"
} cURL
Copy curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v2/contracts/ID-1696407222/versions/ID-1696407267/prolongation-status' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMDhUMTY6NDE6MDAiLCJleHAiOjE3Mjg0MDU2NjAsInJvbGVzIjpbIkFETUlOIl19.Dgxh4-g9be0P0mosxeihMtOol3XBkde3T84SYPHG3W4' \
--header 'Content-Type: application/json' \
--data '{
"prolongationCode": "PRINCIPAL"
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"headerId": "ID-1696407222",
"personId": "ID-2660",
"accountId": "ID-1012",
"applicationId": null,
"offerId": "ID-16964073051",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"contractNumber": "PR-EE-1000",
"countryCode": "EE",
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"depositClassCode": "PREMIUM_CUSTOMER",
"headerActivationDate": "2026-04-04",
"headerClosingDate": null,
"activeVersion": {
"versionId": "ID-1718024026",
"headerId": "ID-1718024016",
"versionNumber": 1,
"statusCode": "ACTIVE",
"preparationDate": "2026-04-04",
"signingDate": null,
"activationDate": "2026-04-04",
"endDate": "2026-07-04",
"closingDate": null,
"period": 3,
"periodTypeCode": "MONTH",
"interestRate": 0.25,
"interestPaymentFrequencyCode": "MONTH",
"prolongCode": "PRINCIPAL",
"countryCode": "EE",
"cancelReasonCode": null,
"lastCreditReceiveDate": "2026-04-06",
"lastSigningDate": null,
"changeTypeCode": "NEW_CONTRACT",
"components": [
{
"componentId": "ID-1718024140",
"versionId": "ID-1718024026",
"componentTypeCode": "PRI",
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"calculationMethod": null,
"rateBaseCode": null,
"rate": null,
"accruedUntil": null,
"paymentDay": 4,
"paymentInterval": 1,
"baseInvalidFromDate": null
},
{
"componentId": "ID-1718024141",
"versionId": "ID-1718024026",
"componentTypeCode": "INT",
"initialMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 0.28,
"currencyCode": "EUR"
},
"calculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"rateBaseCode": null,
"rate": 0.25,
"accruedUntil": "2026-04-12",
"paymentDay": 4,
"paymentInterval": 1,
"baseInvalidFromDate": "2026-04-12"
}
],
"totalInterestMoney": {
"amount": 3.13,
"currencyCode": "EUR"
},
"totalInterestAccruedMoney": {
"amount": 0.28,
"currencyCode": "EUR"
},
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"terminationType": "WITHOUT_INTEREST",
"nextPayoutDate": "2026-05-04",
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"
},
"financialInstitutionId": null,
"referenceNumber": null,
"countryCode": null
}
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false,
"rateBaseCode": null
}
} Result
As a result, the deposit contract prolongation status was updated.
In this example, we will find the deposit contract that was automatically created by the Tuum system after
We will find an existing deposit contract that was ID-2660.
/deposit-api.sandbox.tuumplatform.com/api/v3/persons/{personId}/contracts
See more information about the
In this example, we will change the contract prolongation status for an active contract. We will use the
The contract header is ID-1696407222. See the
The active contract version is ID-1696407267. See the
deposit-api.sandbox.tuumplatform.com/api/v2/contracts/{headerId}/versions/{versionId}/prolongation-status
See more about the
Copy "prolongationCode": "PRINCIPAL" find deposit contract
Adjust deposit contract interest Use case
Use case data
API parameters with values
The contract header is ID-1696407222. See find deposit contract page for more details.
...contracts/ID-1696407222/adjustments
The contract adjustment is an interest increase . And the component is interest.
Note: to create an interest decrease adjustment, use the following value for the eventTypeCode parameter: INTEREST_DECREASE.
The interest increase amount is 0.25 EUR.
Note: the contract interest adjustments must fall within the overall deposit interest adjustments rule.
Sample API call
Sample request
Below is an example request body of the API call for changing deposit contract payout details.
JSON
Copy {
"valueDateRule": "APPROVAL_DATE",
"valueDate": "2027-03-06",
"eventTypeCode": "INTEREST_INCREASE",
"details": "Test",
"componentTypeCode": "INT",
"money": {
"amount": 0.25,
"currencyCode": "EUR"
}
} cURL
Copy curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/adjustments' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDMtMTVUMTU6Mjk6MzgiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MTA1MTY1Nzh9.B5YRuidueo8Ykoqv3z89Jm1rYSwPe2_B1w7Kk_sjP-k' \
--header 'Content-Type: application/json' \
--data '{
"valueDateRule": "APPROVAL_DATE",
"valueDate": "2027-03-06",
"eventTypeCode": "INTEREST_INCREASE",
"details": "Test",
"componentTypeCode": "INT",
"money": {
"amount": 0.25,
"currencyCode": "EUR"
}
}' Sample response
Below you will find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"adjustmentBookingId": "ID-1021",
"componentTypeCode": "INT",
"eventTypeCode": "INTEREST_INCREASE",
"adjustmentType": "BOOKING",
"postingDate": "2027-06-03",
"valueDateRule": "APPROVAL_DATE",
"valueDate": "2027-06-03",
"statusCode": "PROCESSED",
"initiatedByUserId": "1",
"amountMoney": {
"amount": 0.25,
"currencyCode": "EUR"
},
"details": "Test",
"source": {
"sourceName": "DEPOSIT.CONTRACT_HEADER",
"sourceRef": "ID-1696407222",
"sourceLink": null
},
"originalAdjustmentBookingId": null,
"headerId": "ID-1696407222",
"personId": "ID-2660",
"versionId": "ID-1696407267"
}
} Result
As a result a deposit contract interest adjustment: INTEREST_INCREASE with ID-1021 was created.
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
...v2/contracts/ID-1696407222
We will change the tax residency country from Estonia to Germany.
We will set the tax exemption to true.
Sample API call
Sample request
Below is an example request body of the API call for changing deposit contract payout details.
JSON
Copy {
"taxResidencyCountryCode": "DE",
"taxExempt": "true"
} cURL
Copy 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.
Copy {
"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.
In this use case, we will create an interest adjustment for an active deposit contract. We will use the
To adjust the deposit contract interest, make the following API call.
deposit-api.sandbox.tuumplatform.com/api/v1/contracts/{headerId}/adjustments
See more about the
The contract header is ID-1696407222. See the
To update the contract header, make the following API call.
deposit-api.sandbox.tuumplatform.com/
api/v2/contracts/{headerId}
See more about the
Copy "eventTypeCode": "INTEREST_INCREASE",
"componentTypeCode": "INT",
Copy "money": {
"amount": 0.25,
"currencyCode": "EUR"
}
Copy "taxResidencyCountryCode": "DE" Create SWIFT payment Use case
In this scenario, we will initialise an outgoing SWIFT (cross border) payment to a counterparty account with an IBAN and some sample data - ACC2SWIFT payment type.
Use case data
API parameters with values
Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum account ID-1887.
The payment also includes additional transferable data, such as chargeBearer and endToEndId .
Note: the chargeBearer and endToEndId parameters are optional.
Sample API call
To initialise the payment, use the following endpoint:
Sample request
The sample request body is as follows:
JSON
Copy {
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountId": "ID-21508"
},
{
"typeCode": "COUNTERPARTY",
"name": "Ben Eficiary",
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
},
"financialInstitutionId": "PARXEE22XXX",
"address": {
"street1": "First street 123",
"street2": "Second street 321",
"cityCounty": "Some city",
"zip": "06777",
"countryCode": "EE"
}
}
],
"money": {
"amount": 1,
"currencyCode": "DKK"
},
"details": "Test payment",
"endToEndId": "20240103-E000003",
"chargeBearer": "DEBT"
} cURL
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDZUMTM6Mjc6MzUiLCJleHAiOjE3MzM0OTE2NTUsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.r4Efnh8m_waGXaTRBQDLhLDb2M6no_SRJpZCGPoO6K8' \
--header 'Content-Type: application/json' \
--data '{
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountId": "ID-21508"
},
{
"typeCode": "COUNTERPARTY",
"name": "Ben Eficiary",
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
},
"financialInstitutionId": "PARXEE22XXX",
"address": {
"street1": "First street 123",
"street2": "Second street 321",
"cityCounty": "Some city",
"zip": "06777",
"countryCode": "EE"
}
}
],
"money": {
"amount": 1,
"currencyCode": "DKK"
},
"details": "Test payment",
"endToEndId": "20240103-E000003",
"chargeBearer": "DEBT"
}' Sample response
Below you will find the response to the sample request:
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-21846",
"accountId": "ID-21508",
"directionCode": "OUT",
"statusCode": "INSERTED",
"errorCode": null,
"money": {
"amount": 1.00,
"currencyCode": "DKK"
},
"details": "Test payment",
"referenceNumber": null,
"source": null,
"contractSource": null,
"endToEndId": "20240103-E000003",
"valueDate": "2029-12-02",
"postingDate": "2029-12-02",
"insertedDateTime": "2024-12-06T12:41:45.629822Z",
"paymentServiceProviderCode": "SWIFT",
"paymentTypeCode": "ACC2SWIFT",
"preferredPaymentScheme": null,
"selectedPaymentScheme": null,
"chargeBearer": "DEBT",
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlDeclineReason": null,
"amlMonitoringEnabled": null,
"lastStatusRequestDate": null,
"residencyCountryCode": "EE",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-57584",
"typeCode": "COUNTERPARTY",
"name": "Ben Eficiary",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "EE",
"financialInstitutionId": {
"value": "PARXEE22XXX",
"type": "BIC"
},
"address": {
"street1": "First street 123",
"street2": "Second street 321",
"cityCounty": "Some city",
"stateRegion": null,
"zip": "06777",
"countryCode": "EE",
"addressLine": "First street 123, Second street 321, Some city, EE, 06777",
"addressTypeCode": null
},
"roleCode": "BENEFICIARY",
"partyIdentification": null
},
{
"paymentPartyId": "PAYM-57585",
"typeCode": "OUR_PARTY",
"name": "Test Payer",
"personTypeCode": "P",
"givenName": null,
"surname": null,
"accountNumber": {
"value": "XX46XXXX99999000000000000111011",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "XX",
"financialInstitutionId": {
"value": "ICECLOUDXXX",
"type": "BIC"
},
"address": {
"street1": "Tartu mnt 32-25",
"street2": null,
"cityCounty": "Harjumaa",
"stateRegion": "Tallinn",
"zip": "10115",
"countryCode": "EE",
"addressLine": "Tartu mnt 32-25, Harjumaa, EE, 10115",
"addressTypeCode": null
},
"roleCode": "PAYER",
"partyIdentification": {
"identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
"identificationValue": "314-494-5904"
}
}
],
"fees": [],
"paymentSchemeElements": [],
"fileImportLineNumber": null,
"purposeCode": null,
"labels": [
"COUNTERPARTY_EE"
]
}
} Result
The draft payment has been created with a paymentId : PAYM-21846 and the statusCode : INSERTED.
Possible next steps
After creating a draft payment, you have the following options:
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise
Learn more about the
Copy "typeCode": "OUR_PARTY",
"accountId": "ID-1887"
Copy "typeCode": "COUNTERPARTY",
"name": "Ben Eficiary",
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
Copy "money": {
"amount": "10",
"currencyCode": "DKK" }
Copy "details": "Lunch payment"
Copy "endToEndId": "20240103-E000003",
"chargeBearer": "DEBT" Create outgoing payments In this section, you will find instructions on how to create the following types of outgoing payments:
Make premature termination Use case
Use case data
API parameters with values
...contracts/ID-1696407222/...
.../versions/ID-1696407267/...
The deposit contract is terminated without any of the interest it has accrued during the term period.
Sample API call
To terminate an active contract prematurely, make the following API call.
Sample request
Below is an example request body of the API call for changing deposit contract payout details.
JSON
Copy {
"terminationType": "WITHOUT_INTEREST",
"comment": "Closing contract"
} cURL
Copy curl --location 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/versions/ID-1696407267/prepare-for-termination' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDMtMTVUMTg6MzM6MzYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MTA1Mjc2MTZ9.v5803cMEIrcXdTAnbWPEzODtlb0_YKspKRosMtjNyRg' \
--header 'Content-Type: application/json' \
--data '{
"terminationType": "WITHOUT_INTEREST",
"comment": "Closing contract"
}' Sample response
Below you will find an example response body to the API call above
Copy {
"errors": null,
"validationErrors": null,
"data": {
"headerId": "ID-1696407222",
"personId": "ID-2660",
"accountId": "ID-1012",
"applicationId": null,
"offerId": "ID-1718024051",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"contractNumber": "PR-EE-1000",
"countryCode": "EE",
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"depositClassCode": "PREMIUM_CUSTOMER",
"headerActivationDate": "2026-04-04",
"headerClosingDate": null,
"activeVersion": {
"versionId": "ID-1696407267",
"headerId": "ID-1696407222",
"versionNumber": 1,
"statusCode": "TERMINATING",
"preparationDate": "2026-04-04",
"signingDate": null,
"activationDate": "2026-04-04",
"endDate": "2026-07-04",
"closingDate": null,
"period": 3,
"periodTypeCode": "MONTH",
"interestRate": 0.25,
"interestPaymentFrequencyCode": "MONTH",
"prolongCode": "PRINCIPAL",
"countryCode": "EE",
"cancelReasonCode": null,
"lastCreditReceiveDate": "2026-04-06",
"lastSigningDate": null,
"changeTypeCode": "NEW_CONTRACT",
"components": [
{
"componentId": "ID-1718024140",
"versionId": "ID-1718024026",
"componentTypeCode": "PRI",
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 4995.00,
"currencyCode": "EUR"
},
"calculationMethod": null,
"rateBaseCode": null,
"rate": null,
"accruedUntil": null,
"paymentDay": 4,
"paymentInterval": 1,
"baseInvalidFromDate": null
},
{
"componentId": "ID-1718024141",
"versionId": "ID-1718024026",
"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": "2026-06-04",
"paymentDay": 4,
"paymentInterval": 1,
"baseInvalidFromDate": "2026-06-04"
}
],
"totalInterestMoney": {
"amount": 3.13,
"currencyCode": "EUR"
},
"totalInterestAccruedMoney": {
"amount": 0.25,
"currencyCode": "EUR"
},
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"terminationType": "WITHOUT_INTEREST",
"nextPayoutDate": "2026-07-04",
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"
},
"financialInstitutionId": null,
"referenceNumber": null,
"countryCode": null
}
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false,
"rateBaseCode": null
}
} Result
As a result, the deposit contract is set to the TERMINATING status.
In this example, we will review how to terminate an active contract prematurely (before the contract reaches its end date).
We will use the
The contract header is ID-1696407222. See the
The active contract version is ID-1696407267. See the
deposit-api.sandbox.tuumplatform.com/api/v2/contracts/{headerId}/versions/{versionId}/prepare-for-termination
See more information about the
Copy "terminationType": "WITHOUT_INTEREST" Change payout details Use case
Use case data
API parameters
api/v1/contracts/ID-1696407222...
...versions/ID-1696407267/payout-details
payoutDetails Parameter
The payoutDetails parameter is optional and can only be defined for an active deposit contract.
Supported Account Types
Payout details support the following account number types:
Click on the tabs below to see the formatting for each account number types.
IBAN
Copy "payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN" Parameter validations:
If accountNumber.type is IBAN , financialInstitutionId is not required .
If accountNumber.type is IBAN and financialInstitutionId is provided, then countryCode is required .
BBAN
Copy "payoutDetails": {
"name": "Malloy Harbor",
"accountNumber": {
"type": "BBAN",
"value": "3159584114"
},
"financialInstitutionId": {
"type": "BANK_CODE",
"value": "5051"
},
"countryCode": "DK",
"referenceNumber": null
} Parameter validations:
If financialInstitutionId is provided, type can be one of the following values:
If accountNumber.type is BBAN and financialInstitutionId is ABA_CODE , countryCode can be one of the following:
US (United States of America),
If accountNumber.type is BBAN and financialInstitutionId is SORT_CODE , countryCode is GB (Great Britain)
Default Behavior
If payout details are not specified for a contract version, the payout will automatically be directed to the servicing account. It is not necessary to define the servicing account as the payout account in this case.
Modifying Payout Details
Payout details can be modified or removed. To remove payout details from an active contract version, include the following in the request:
Copy "payoutDetails": null Sample API call
To change the deposit contract payout details, make the following API call.
JSON
Copy {
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"
}
}
} cURL
Copy curl --location --request PUT 'https://deposit-api.sandbox.tuumplatform.com/api/v1/contracts/ID-1696407222/versions/ID-1696407267/payout-details' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEwMDAiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTAtMDdUMTU6MDM6MTAiLCJleHAiOjE3MjgzMTMzOTAsInJvbGVzIjpbIkFETUlOIl19.KloWEzZXTCs6u0HeijjZyqn8Wy_bzhs8hdVsfSlFvS4' \
--header 'Content-Type: application/json' \
--data '{
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"
}
}
}' Sample response
Below you find an example response body to the API call above.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"headerId": "ID-1696407222",
"personId": "ID-2660",
"accountId": "ID-1012",
"applicationId": null,
"offerId": "ID-16964073051",
"depositGroupCode": "TIME_DEPOSIT",
"depositTypeCode": "PREMIUM",
"contractNumber": "PR-EE-1000",
"countryCode": "EE",
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"depositClassCode": "PREMIUM_CUSTOMER",
"headerActivationDate": "2026-04-04",
"headerClosingDate": null,
"activeVersion": {
"versionId": "ID-1718024026",
"headerId": "ID-1718024016",
"versionNumber": 1,
"statusCode": "ACTIVE",
"preparationDate": "2026-04-04",
"signingDate": null,
"activationDate": "2026-04-04",
"endDate": "2026-07-04",
"closingDate": null,
"period": 3,
"periodTypeCode": "MONTH",
"interestRate": 0.25,
"interestPaymentFrequencyCode": "MONTH",
"prolongCode": null,
"countryCode": "EE",
"cancelReasonCode": null,
"lastCreditReceiveDate": "2026-04-06",
"lastSigningDate": null,
"changeTypeCode": "NEW_CONTRACT",
"components": [
{
"componentId": "ID-1718024140",
"versionId": "ID-1718024026",
"componentTypeCode": "PRI",
"initialMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 5000.00,
"currencyCode": "EUR"
},
"calculationMethod": null,
"rateBaseCode": null,
"rate": null,
"accruedUntil": null,
"paymentDay": 4,
"paymentInterval": 1,
"baseInvalidFromDate": null
},
{
"componentId": "ID-1718024141",
"versionId": "ID-1718024026",
"componentTypeCode": "INT",
"initialMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"balanceMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"calculationMethod": {
"daysInMonth": "30",
"daysInYear": 360
},
"rateBaseCode": "FIX",
"rate": 0.25,
"accruedUntil": null,
"paymentDay": 4,
"paymentInterval": 1,
"baseInvalidFromDate": "2026-04-04"
}
],
"totalInterestMoney": {
"amount": 3.13,
"currencyCode": "EUR"
},
"totalInterestAccruedMoney": {
"amount": 0.00,
"currencyCode": "EUR"
},
"channelCode": "BACKOFFICE",
"tenantCode": "MB",
"terminationType": "WITHOUT_INTEREST",
"nextPayoutDate": "2026-05-04",
"payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN"
},
"financialInstitutionId": null,
"referenceNumber": null,
"countryCode": null
}
},
"personTypeCode": "P",
"taxResidencyCountryCode": "EE",
"taxExempt": false
}
} Result
As a result, the deposit contract payout details were updated.
Create SEPA payment Use case
In this scenario, we will create an outgoing SEPA payment - ACC2SEPA payment type.
Sample API call
To initialise the payment, use the following endpoint:
Sample request
The sample request body is as follows:
Sample response
Below you will find the response to the sample request:
Result
The draft payment has been created with a paymentId : PAYM-32706 and the statusCode : INSERTED.
Possible next steps
After creating a draft payment, you have the following options:
Confirm payment After initialising the payment, we need to confirm it to complete the payment.
Use case
Here, we will confirm a payment draft using the payment ID parameter.
Sample API call
To confirm the payment, use the following endpoint:
Sample request
The sample request body is as follows:
Sample response
Below you will find the response to the sample request:
Result
The payment is confirmed with the statusCode WAITING_FOR_AML. You can check the AML-related information using the AML API. You can also manually approve or decline a payment detected by the AML monitoring system.
In this example, we will review how to change the payout details for an active deposit contract.
We will use the
The contract header is ID-1696407222. See the
The active contract version is ID-1696407267. See the
The new payout details.
Note: the payoutDetails parameter is not mandatory. This parameter can be only defined for an active deposit contract. See more information about the payoutDetails parameter
Use case data
API parameters with values
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise
Learn more about the
Use case data
API parameters with values
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/PAYM-47356/confirm
Learn more about the
Copy "payoutDetails": {
"name": "Test Account",
"accountNumber": {
"value": "EE111236525217358748",
"type": "IBAN" Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum account ID-4184.
Copy "typeCode": "OUR_PARTY",
"accountId": "ID-4184"
Copy {
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
} Payment amount and currency.
Copy "money": {
"amount": "25",
"currencyCode": "EUR" }
Copy "details": "Test payment with our party accountId" The payment also includes payment steering data, such as valueDate and ourFee .
Note: the valueDate and ourFee parameters are optional.
Copy "valueDate" : "2024-12-04",
"ourFee": {
"amount": 1.22,
"currencyCode": "EUR"
Copy {
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountId": "ID-4184"
},
{
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
}
}
],
"money": {
"amount": 25,
"currencyCode": "EUR"
},
"details": "Test payment with our party accountId",
"valueDate" : "2024-12-04",
"ourFee": {
"amount": 1.22,
"currencyCode": "EUR"
}
}
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDRUMTQ6MjY6MTkiLCJleHAiOjE3MzMzMjIzNzksInJvbGVzIjpbIkFETUlOIl19.X1C4fpzVoXZnbicLPFW7izPPRLKGs-wGw6xoETGAypE' \
--header 'Content-Type: application/json' \
--data '{
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountId": "ID-4184"
},
{
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
}
}
],
"money": {
"amount": 25,
"currencyCode": "EUR"
},
"details": "Test payment with our party accountId",
"valueDate" : "2024-12-04",
"ourFee": {
"amount": 1.22,
"currencyCode": "EUR"
}
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-32706",
"accountId": "ID-4184",
"directionCode": "OUT",
"statusCode": "INSERTED",
"errorCode": null,
"money": {
"amount": 25.00,
"currencyCode": "EUR"
},
"details": "Test payment with our party accountId",
"referenceNumber": null,
"source": null,
"contractSource": null,
"endToEndId": null,
"valueDate": "2024-12-04",
"postingDate": "2024-12-04",
"insertedDateTime": "2024-12-04T13:28:52.498788Z",
"paymentServiceProviderCode": "SEPA",
"paymentTypeCode": "ACC2SEPA",
"preferredPaymentScheme": null,
"selectedPaymentScheme": "SEPA_INSTANT",
"chargeBearer": null,
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlDeclineReason": null,
"amlMonitoringEnabled": null,
"lastStatusRequestDate": null,
"residencyCountryCode": "GB",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-67504",
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "EE",
"financialInstitutionId": {
"value": "PARXEE22XXX",
"type": "BIC"
},
"address": null,
"roleCode": "BENEFICIARY",
"partyIdentification": null
},
{
"paymentPartyId": "PAYM-67505",
"typeCode": "OUR_PARTY",
"name": "Tuum Thomas",
"personTypeCode": "P",
"givenName": "Tuum",
"surname": "Thomas",
"accountNumber": {
"value": "XX20XXXX99999000000000000021075",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "XX",
"financialInstitutionId": {
"value": "ICECLOUDXXX",
"type": "BIC"
},
"address": {
"street1": "24 Botley Road",
"street2": null,
"cityCounty": "Middleton Hall",
"stateRegion": null,
"zip": "NE71 3LL",
"countryCode": "GB",
"addressLine": "24 Botley Road, Middleton Hall, GB, NE71 3LL",
"addressTypeCode": null
},
"roleCode": "PAYER",
"partyIdentification": {
"identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
"identificationValue": "DD654321C"
}
}
],
"fees": [
{
"feeTypeCode": "ACC2SEPA_FEE",
"feeMoney": {
"amount": 1.22,
"currencyCode": "EUR"
},
"deferredFee": false
}
],
"paymentSchemeElements": [],
"fileImportLineNumber": null,
"purposeCode": null,
"labels": [
"COUNTERPARTY_EE",
"SEPA_INSTANT"
]
}
} The payment ID is taken from the response to the payment initialisation request.
Copy ".../PAYM-47356/confirm"
Copy { "comment": "Confirm payment" }
Copy {
"comment": "Confirm payment"
}
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/PAYM-47356/confirm' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDItMDhUMTY6MTU6NTkiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE3MDc0MDg5NTl9.9ra--2cschOt3BvgdMrq_yrKgVhZrPCiX6ea0IXkX08' \
--header 'Content-Type: application/json' \
--data '"comment": "Confirm payment"'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-47356",
"accountId": "ID-1002",
"directionCode": "OUT",
"statusCode": "WAITING_FOR_AML",
"errorCode": null,
"money": {
"amount": 10.00,
"currencyCode": "EUR"
},
"details": "Lunch payment",
"referenceNumber": null,
"source": null,
"contractSource": null,
"endToEndId": null,
"valueDate": "2026-09-06",
"postingDate": "2026-09-06",
"insertedDateTime": "2024-02-08T14:36:47.339803Z",
"paymentServiceProviderCode": "SEPA",
"paymentTypeCode": "ACC2SEPA",
"preferredPaymentScheme": null,
"selectedPaymentScheme": "SEPA_INSTANT",
"chargeBearer": null,
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlMonitoringEnabled": true,
"lastStatusRequestDate": null,
"residencyCountryCode": "FI",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-115887",
"typeCode": "OUR_PARTY",
"name": "Damara Kai",
"personTypeCode": "P",
"givenName": "Damara",
"surname": "Kai",
"accountNumber": {
"value": "XX10XXXX99999000000000000000012",
"type": "IBAN"
},
"accountNumberCountryCode": "XX",
"financialInstitutionId": {
"value": "ICECLOUDXXX",
"type": "BIC"
},
"address": {
"street1": "Fennstrasse 4",
"street2": "string",
"cityCounty": "Berlin",
"stateRegion": "Berlin",
"zip": "13347",
"countryCode": "DE",
"addressLine": "Fennstrasse 4, string, Berlin, DE, 13347"
},
"nationalIdentificationNumber": null,
"roleCode": "PAYER"
},
{
"paymentPartyId": "PAYM-115888",
"typeCode": "COUNTERPARTY",
"name": "Ben Eficiary",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "EE871275295834652820",
"type": "IBAN"
},
"accountNumberCountryCode": "EE",
"financialInstitutionId": {
"value": "PARXEE22XXX",
"type": "BIC"
},
"address": null,
"nationalIdentificationNumber": null,
"roleCode": "BENEFICIARY"
}
],
"fees": [
{
"feeTypeCode": "ACC2SEPA_FEE",
"feeMoney": {
"amount": 0.05,
"currencyCode": "EUR"
},
"deferredFee": false
}
],
"paymentSchemeElements": [],
"fileImportLineNumber": null
}
} Cancel payment Use case
In this example, we will review how to cancel a payment draft.
Use case data
API parameters with values
We will cancel the PAYM-21736 payment.
...api/v3/payments/PAYM-21736...
Sample API call
To cancel the payment, use the following endpoint:
Sample request
The sample request body is as follows:
JSON
Copy "comment": "Cancel payment" cURL
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/PAYM-21736/cancel' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDJUMTM6MjU6MzEiLCJleHAiOjE3MzMxNDU5MzEsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.W9yv0iAmm3QoQILoCJit9uZbp10kSRQsWoIq9spDG2w' \
--header 'Content-Type: application/json' \
--data '"comment": "Cancel payment"' Sample response
Below you will find the response to the sample request:
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-21736",
"accountId": "ID-12329",
"directionCode": "OUT",
"statusCode": "CANCELLED",
"errorCode": null,
"money": {
"amount": 20.00,
"currencyCode": "GBP"
},
"details": null,
"referenceNumber": null,
"source": null,
"contractSource": null,
"endToEndId": null,
"valueDate": "2029-11-09",
"postingDate": "2029-11-09",
"insertedDateTime": "2024-11-30T01:40:54.048581Z",
"paymentServiceProviderCode": "SWIFT",
"paymentTypeCode": "ACC2SWIFT",
"preferredPaymentScheme": null,
"selectedPaymentScheme": null,
"chargeBearer": null,
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlDeclineReason": null,
"amlMonitoringEnabled": null,
"lastStatusRequestDate": null,
"residencyCountryCode": "GB",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-57290",
"typeCode": "COUNTERPARTY",
"name": "Test Receiver",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "56497232",
"type": "BBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "GB",
"financialInstitutionId": {
"value": "BARCGB22",
"type": "BIC"
},
"address": null,
"roleCode": "BENEFICIARY",
"partyIdentification": null
},
{
"paymentPartyId": "PAYM-57291",
"typeCode": "OUR_PARTY",
"name": "Fianna Penelopa",
"personTypeCode": "P",
"givenName": "Fianna",
"surname": "Penelopa",
"accountNumber": {
"value": "GB55LHVB04030000001875",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "GB",
"financialInstitutionId": {
"value": "LHVBGB2LXXX",
"type": "BIC"
},
"address": {
"street1": "Fennstrasse 4",
"street2": "string",
"cityCounty": "Berlin",
"stateRegion": "Berlin",
"zip": "13347",
"countryCode": "DE",
"addressLine": "Fennstrasse 4, string, Berlin, DE, 13347",
"addressTypeCode": null
},
"roleCode": "PAYER",
"partyIdentification": {
"identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
"identificationValue": "id-919820058"
}
}
],
"fees": [],
"paymentSchemeElements": [],
"fileImportLineNumber": null,
"purposeCode": null,
"labels": [
"COUNTERPARTY_GB"
]
}
} Result
The payment with the paymentId: PAYM-21736 has been set to the CANCELLED status.
Accept deposit offer Use case
In this example, we will review how to accept a deposit offer.
Use case data
API parameters with values
We will accept the deposit offer ID-1696407305.
...v1/offers/ID-1696407305/accept
Sample API call
To accept a deposit offer, make the following API call.
Sample response
Below you find an example response body to the API call above.
Copy {
"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.
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/{paymentId}/cancel
Learn more about the
deposit-api.sandbox.tuumplatform.com/api/v2/offers/{offerId}/accept
See more about the
Copy "comment": "Cancel payment" Create domestic UK payment Use case
In this scenario, we will create a domestic UK payment from Tuum BC (Banking Circle) UK account to another UK account. In this case, the payment will be created with the ACC2LOCAL payment type.
Use case data
API parameters with values
Our party details give the information about the sender of the payment.
In this example, the payment is initialised from the Tuum bank account with 21824474 BBAN.
The payer's account country is the UK.
Note: the payer's bank account financial institution id is the bank's sort code .
The payment receiver account country is the UK. Note: the payment receiver financial institution id is the bank's sort code .
Payment amount and currency.
The payment also includes non-transferrable data, such as contractSource .
Note : the contractSource parameter is optional.
Sample API call
Sample request
The sample request body is as follows:
JSON
Copy {
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "21824474",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "608382"
},
{
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "00001781",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "040300"
}
],
"money": {
"amount": 15,
"currencyCode": "GBP"
},
"details": "Test payment with both parties with BBAN for domestic UK payment",
"contractSource": {
"sourceName": "Test System",
"sourceRef": "1234",
"contractNumber": "test"
}
} cURL
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDVUMTM6MTA6MDciLCJleHAiOjE3MzM0MDQyMDcsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.T2c1I6mazgGm2gT6p3lqaXxb2qj9OTPiluP5XnJr0zU' \
--header 'Content-Type: application/json' \
--data '{
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "21824474",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "608382"
},
{
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "00001781",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "040300"
}
],
"money": {
"amount": 15,
"currencyCode": "GBP"
},
"details": "Test payment with both parties with BBAN for domestic UK payment",
"contractSource": {
"sourceName": "Test System",
"sourceRef": "1234",
"contractNumber": "test"
}
}' Sample response
Below you will find the response to the sample request:
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-21826",
"accountId": "ID-17598",
"directionCode": "OUT",
"statusCode": "INSERTED",
"errorCode": null,
"money": {
"amount": 15.00,
"currencyCode": "GBP"
},
"details": "Test payment with both parties with BBAN for domestic UK payment",
"referenceNumber": null,
"source": null,
"contractSource": {
"sourceName": "Test System",
"sourceRef": "1234",
"contractNumber": "test"
},
"endToEndId": null,
"valueDate": "2029-11-27",
"postingDate": "2029-11-27",
"insertedDateTime": "2024-12-05T12:21:07.149343Z",
"paymentServiceProviderCode": "BC",
"paymentTypeCode": "ACC2LOCAL",
"preferredPaymentScheme": null,
"selectedPaymentScheme": null,
"chargeBearer": null,
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlDeclineReason": null,
"amlMonitoringEnabled": null,
"lastStatusRequestDate": null,
"residencyCountryCode": "FI",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-57538",
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "00001781",
"type": "BBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "GB",
"financialInstitutionId": {
"value": "040300",
"type": "SORT_CODE"
},
"address": null,
"roleCode": "BENEFICIARY",
"partyIdentification": null
},
{
"paymentPartyId": "PAYM-57539",
"typeCode": "OUR_PARTY",
"name": "Daria Core",
"personTypeCode": "P",
"givenName": "Daria",
"surname": "Core",
"accountNumber": {
"value": "DK9189000021824474",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "DK",
"financialInstitutionId": {
"value": "SXPYDKKK",
"type": "BIC"
},
"address": {
"street1": "Maakri",
"street2": null,
"cityCounty": "Tallinn",
"stateRegion": null,
"zip": null,
"countryCode": "EE",
"addressLine": "Maakri, Tallinn, EE",
"addressTypeCode": null
},
"roleCode": "PAYER",
"partyIdentification": {
"identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
"identificationValue": "EE1234567"
}
}
],
"fees": [],
"paymentSchemeElements": [],
"fileImportLineNumber": null,
"purposeCode": null,
"labels": [
"COUNTERPARTY_GB"
]
}
} Result
The draft payment has been created with a paymentId : PAYM-21826 and the statusCode : INSERTED.
Possible next steps
After creating a draft payment, you have the following options:
Create domestic US payment Use case
In this scenario, we will create a domestic US payment - ACC2LOCAL payment type.
Sample API call
Sample request
The sample request body is as follows:
Sample response
Below you will find the response to the sample request:
Result
The draft payment has been created with a paymentId : PAYM-21726 and the statusCode : INSERTED.
Possible next steps
After creating a draft payment, you have the following options:
To initialise the payment, use the following endpoint:
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise
Learn more about the
Use case data
API parameters with values
To initialise the payment, use the following endpoint:
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise
Learn more about the
Copy "typeCode": "OUR_PARTY",
"accountNumber": {
"value": "21824474",
"type": "BBAN"
}
Copy "accountNumberCountryCode": "GB",
"financialInstitutionId": "608382"
Copy "typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "00001781",
"type": "BBAN"
}
Copy "accountNumberCountryCode": "GB",
"financialInstitutionId": "040300"
Copy "money": {
"amount": 15,
"currencyCode": "GBP"
}
Copy "details": "Test payment with both parties with BBAN for domestic UK payment"
Copy "contractSource": {
"sourceName": "Test System",
"sourceRef": "1234",
"contractNumber": "test"
} Our party details gives the information about the sender of the payment.
In this example, the payment is initialised from the Tuum bank account with 190021824474 BBAN.
Copy {
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "190021824474",
"type":
} The payer's account country is the USA.
Note: the payer's bank account financial institution id is the ABA Routing number .
Copy "accountNumberCountryCode": "US",
"financialInstitutionId": "021000018"
Copy "typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "231123456789",
"type": "BBAN" The payer's account country is the USA.
Note: the payer's bank account financial institution id is the ABA Routing number .
Copy "accountNumberCountryCode": "US",
"financialInstitutionId": "021000322" Payment amount and currency.
Copy "money": {
"amount": 17,
"currencyCode": "USD"
}
Copy "details": "Test payment with both parties with BBAN for domestic US payment" The payment also includes payment steering data, such as usageLimitCode .
Note: the usageLimitCode is an optional parameter.
Copy "usageLimitCode": "test"
Copy {
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "190021824474",
"type": "BBAN"
},
"accountNumberCountryCode": "US",
"financialInstitutionId": "021000018"
},
{
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "231123456789",
"type": "BBAN"
},
"accountNumberCountryCode": "US",
"financialInstitutionId": "021000322"
}
],
"money": {
"amount": 17,
"currencyCode": "USD"
},
"details": "Test payment with both parties with BBAN for domestic US payment",
"usageLimitCode": "test"
}
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDVUMTM6NDM6MTAiLCJleHAiOjE3MzM0MDYxOTAsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.03a1hgsWy3yZxxKXl-TpIatf4XAllaA0dquZH4U8a0E' \
--header 'Content-Type: application/json' \
--data '{
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "190021824474",
"type": "BBAN"
},
"accountNumberCountryCode": "US",
"financialInstitutionId": "021000018"
},
{
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
"value": "231123456789",
"type": "BBAN"
},
"accountNumberCountryCode": "US",
"financialInstitutionId": "021000322"
}
],
"money": {
"amount": 17,
"currencyCode": "USD"
},
"details": "Test payment with both parties with BBAN for domestic US payment",
"usageLimitCode": "test"
}'
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-21726",
"accountId": "ID-17598",
"directionCode": "OUT",
"statusCode": "INSERTED",
"errorCode": null,
"money": {
"amount": 17.00,
"currencyCode": "USD"
},
"details": "Test payment with both parties with BBAN for domestic US payment",
"referenceNumber": null,
"source": null,
"contractSource": null,
"endToEndId": null,
"valueDate": "2029-11-01",
"postingDate": "2029-11-01",
"insertedDateTime": "2024-11-28T16:09:32.4368Z",
"paymentServiceProviderCode": "BC",
"paymentTypeCode": "ACC2LOCAL",
"preferredPaymentScheme": null,
"selectedPaymentScheme": null,
"chargeBearer": null,
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlDeclineReason": null,
"amlMonitoringEnabled": null,
"lastStatusRequestDate": null,
"residencyCountryCode": "FI",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-57267",
"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "231123456789",
"type": "BBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "US",
"financialInstitutionId": {
"value": "021000322",
"type": "ABA_CODE"
},
"address": null,
"roleCode": "BENEFICIARY",
"partyIdentification": null
},
{
"paymentPartyId": "PAYM-57268",
"typeCode": "OUR_PARTY",
"name": "Test User",
"personTypeCode": "P",
"givenName": "Test",
"surname": "User",
"accountNumber": {
"value": "DK9189000021824474",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "DK",
"financialInstitutionId": {
"value": "SXPYDKKK",
"type": "BIC"
},
"address": {
"street1": "",
"street2": null,
"cityCounty": "Tallinn",
"stateRegion": null,
"zip": null,
"countryCode": "EE",
"addressLine": "Maakri, Tallinn, EE",
"addressTypeCode": null
},
"roleCode": "PAYER",
"partyIdentification": {
"identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
"identificationValue": "EE1234567"
}
}
],
"fees": [],
"paymentSchemeElements": [],
"fileImportLineNumber": null,
"purposeCode": null,
"labels": [
"COUNTERPARTY_US"
]
}
} Find AML information of a payment 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:
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.
Use case data
API parameters with values
https://aml-api.sandbox.tuumplatform.com/api/v1/aml/process/by-payment?paymentId=PAYM-8834
Learn more about the
The query parameter is the payment ID. The ID is taken from the response to the payment request.
Copy ".../by-payment?paymentId=PAYM-8834"
Copy {
"errors": null,
"validationErrors": null,
"data": {
"processId": "ID-7878",
"paymentId": "PAYM-8834",
"statusCode": "PROCESSED",
"resultCode": "APPROVED",
"source": null,
"providerInfo": null
}
} Create payment template A payment template allows you to save the payment information and create templates for regular payments.
Use case
Here we will create a payment template for outgoing SEPA payments with sample data.
Use case data
API parameters with values
The path parameter is the technical ID of the account to which the payment is being made.
Sample API call
To create the payment template, use the following endpoint:
Sample request
The sample request body is as follows:
JSON
Copy {
"templateName": "Payment template",
"amount": {
"amount": 10,
"currencyCode": "EUR"
},
"paymentTemplateParties": [
{
"typeCode": "COUNTERPARTY",
"name": "Ben",
"surname": "Eficiary",
"personTypeCode": "P",
"accountNumber": {
"value": "EE212227575393349708",
"type": "IBAN"
},
"accountNumberCountryCode": "EE",
"financialInstitutionId": "PARXEE22XXX"
}
]
} cURL
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v2/accounts/ID-1002/payment-templates' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjQtMDItMTRUMTQ6NTc6NDQiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE3MDc5MjI2NjR9.ndC26HBHThoHB88W3q4bktkhUHjXXj4Wp0LJmGRUWwM' \
--header 'Content-Type: application/json' \
--data '{
"templateName": "Payment template",
"amount": {
"amount": 10,
"currencyCode": "EUR"
},
"paymentTemplateParties": [
{
"typeCode": "COUNTERPARTY",
"name": "Ben",
"surname": "Eficiary",
"personTypeCode": "P",
"accountNumber": {
"value": "EE212227575393349708",
"type": "IBAN"
},
"accountNumberCountryCode": "EE",
"financialInstitutionId": "PARXEE22XXX"
}
]
}' Sample response
Below you will find the response to the sample request:
Copy {
"errors": null,
"validationErrors": null,
"data": {
"templateId": "ID-1002",
"templateName": "Payment template",
"paymentTypeCode": null,
"amount": {
"amount": 10.00,
"currencyCode": "EUR"
},
"details": null,
"referenceNumber": null,
"paymentTemplateParties": [
{
"paymentTemplatePartyId": "ID-1002",
"typeCode": "COUNTERPARTY",
"name": "Ben",
"givenName": null,
"surname": "Eficiary",
"personTypeCode": "P",
"accountNumber": {
"value": "EE212227575393349708",
"type": "IBAN"
},
"accountNumberCountryCode": "EE",
"financialInstitutionId": {
"value": "PARXEE22XXX",
"type": "BIC"
},
"address": null
}
]
}
} Result
The payment template is created with a template ID.
https://payment-api.sandbox.tuumplatform.com/api/v2/accounts/ID-1002/payment-templates
Learn more about the
Copy ".../ID-1002/payment-templates"
Copy "templateName": "Payment template"
Copy "amount": {
"amount": 10,
"currencyCode": "EUR" }
Copy "paymentTemplateParties": [
{
"typeCode": "COUNTERPARTY",
"name": "Ben",
"surname": "Eficiary",
"personTypeCode": "P",
"accountNumber": {
"value": "EE212227575393349708",
"type": "IBAN"
},
"accountNumberCountryCode": "EE",
"financialInstitutionId": "PARXEE22XXX"
}
] Initialise FX quote request Initialising an FX quote request refers to creating a request with the amount for the currency pair that you want to use.
Use case
Here we will initialise an FX quote request with sample data.
Use case data
API parameters with values
The path parameter is the technical ID of the account to which the payment is being made.
Tenor refers to the contract durations for trades.
The allowed value is TODAY . This means that the currency exchange rate on the day that the order is executed is applied.
Sample API call
To initialise the FX quote request, use the following endpoint:
Sample request
The sample request body is as follows:
JSON
Copy {
"sellCurrencyCode": "EUR",
"buyCurrencyCode": "GBP",
"money": {
"amount": 30,
"currencyCode": "EUR"
},
"tenor": "TODAY"
} cURL
Copy curl -X 'POST' \
'https://payment-api.sandbox.tuumplatform.com/api/v1/accounts/ID-1026/fx-quotes/initialise' \
-H 'accept: */*' \
-H 'x-channel-code: SYSTEM' \
-H 'x-tenant-code: MB' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMDctMTNUMTE6Mjc6NDMiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHAiOjE2ODkyNDc2NjN9.V62GKGz6hIMFF15n1IGnKpZTWtcTyPF0IC5pGfuToIU' \
-H 'Content-Type: application/json' \
-d '{
"sellCurrencyCode": "EUR",
"buyCurrencyCode": "GBP",
"money": {
"amount": 30,
"currencyCode": "EUR"
},
"tenor": "TODAY"
}' Sample response
Below you will find the response to the sample request:
Copy {
"errors": null,
"validationErrors": null,
"data": {
"quoteRequestId": "ID-1263",
"accountId": "ID-1026",
"accountNumber": {
"value": "DK9189000099106120",
"type": "IBAN"
},
"accountServiceProviderCode": "BC",
"currencyPair": "EURGBP",
"sellCurrencyCode": "EUR",
"buyCurrencyCode": "GBP",
"money": {
"amount": 30,
"currencyCode": "EUR"
},
"tenor": "TODAY",
"comment": null,
"source": null,
"statusCode": "WAITING_QUOTE",
"errorCode": null,
"quoteDtime": "2023-07-13T11:06:14.780047Z",
"tradeDate": "2025-04-07",
"settlementDate": "2025-04-07",
"quoteResponses": [],
"requestReason": "FX"
}
} Result
https://payment-api.sandbox.tuumplatform.com/api/v1/accounts/ID-1026/fx-quotes/initialise
Learn more about the
The quote request is created with a quote request ID and status code. The next step is to
Copy ".../ID-1026/fx-quotes/initialise"
Copy "sellCurrencyCode": "EUR",
"buyCurrencyCode": "GBP"
Copy "amount": {
"amount": 30,
"currencyCode": "EUR" } Change payment Use case
In this example, we will review how to change a payment draft. We will update counterparty and payment amount.
Use case data
API parameters with values
We are going to update the PAYM-21826 payment.
Updated counterparty details. The counterparty name, account information, and financial institution id were updated.
Sample API call
Sample request
The sample request body is as follows:
JSON
Copy {
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "21824474",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "608382",
},
{
"typeCode": "COUNTERPARTY",
"name": "Test Receiver",
"accountNumber": {
"value": "56497232",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "BARCGB22"
}
],
"money": {
"amount": 20,
"currencyCode": "GBP"
}
} cURL
Copy curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/PAYM-21777/change' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTEtMzBUMDI6NDc6MjYiLCJleHAiOjE3MzI5MzQ4NDYsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.aZQf-Tf3Zro6Ri6_FD-izuqQ37MoDJKJmISkWeDyzSo' \
--header 'Content-Type: application/json' \
--data '{
"paymentParties": [
{
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "21824474",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "608382"
},
{
"typeCode": "COUNTERPARTY",
"name": "Test Receiver",
"accountNumber": {
"value": "56497232",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "BARCGB22"
}
],
"money": {
"amount": 20,
"currencyCode": "GBP"
}
}' Sample response
Below you will find the response to the sample request:
Copy {
"errors": null,
"validationErrors": null,
"data": {
"paymentId": "PAYM-21826",
"accountId": "ID-17598",
"directionCode": "OUT",
"statusCode": "INSERTED",
"errorCode": null,
"money": {
"amount": 20.00,
"currencyCode": "GBP"
},
"details": null,
"referenceNumber": null,
"source": null,
"contractSource": null,
"endToEndId": null,
"valueDate": "2029-11-27",
"postingDate": "2029-11-27",
"insertedDateTime": "2024-12-05T12:21:07.149343Z",
"paymentServiceProviderCode": "BC",
"paymentTypeCode": "ACC2LOCAL",
"preferredPaymentScheme": null,
"selectedPaymentScheme": null,
"chargeBearer": null,
"settlementStatusCode": null,
"settlementErrorCode": null,
"settlementDate": null,
"settlementPaymentScheme": null,
"returnStatusCode": null,
"returnReason": null,
"returnComment": null,
"returnSettlementDate": null,
"cancellationRequestStatusCode": null,
"cancelRefuseReason": null,
"cancelReason": null,
"amlDeclineReason": null,
"amlMonitoringEnabled": null,
"lastStatusRequestDate": null,
"residencyCountryCode": "FI",
"counterpartyOriginalIban": null,
"fxPaymentFlag": false,
"fxPayment": null,
"paymentParties": [
{
"paymentPartyId": "PAYM-57542",
"typeCode": "COUNTERPARTY",
"name": "Test Receiver",
"personTypeCode": null,
"givenName": null,
"surname": null,
"accountNumber": {
"value": "56497232",
"type": "BBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "GB",
"financialInstitutionId": {
"value": "BARCGB22",
"type": "BIC"
},
"address": null,
"roleCode": "BENEFICIARY",
"partyIdentification": null
},
{
"paymentPartyId": "PAYM-57543",
"typeCode": "OUR_PARTY",
"name": "Daria Core",
"personTypeCode": "P",
"givenName": "Daria",
"surname": "Core",
"accountNumber": {
"value": "DK9189000021824474",
"type": "IBAN"
},
"accountNumberSubtype": null,
"accountNumberCountryCode": "DK",
"financialInstitutionId": {
"value": "SXPYDKKK",
"type": "BIC"
},
"address": {
"street1": "Maakri",
"street2": null,
"cityCounty": "Tallinn",
"stateRegion": null,
"zip": null,
"countryCode": "EE",
"addressLine": "Maakri, Tallinn, EE",
"addressTypeCode": null
},
"roleCode": "PAYER",
"partyIdentification": {
"identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
"identificationValue": "EE1234567"
}
}
],
"fees": [],
"paymentSchemeElements": [],
"fileImportLineNumber": null,
"purposeCode": null,
"labels": [
"COUNTERPARTY_GB"
]
}
} Result
The payment draft with the paymentId: PAYM-21826 was updated. The payment status remained as INSERTED.
Possible next steps
After updating a payment draft, you have the following options:
Find settled SEPA transaction 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:
Sample response
Below you will find the response to the sample request:
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.
Get FX quote response Use case
We will get the FX quote response ID for a request we created with sample data.
Sample API call
To get the FX response ID, use the following endpoint:
Sample response
Below you will find the response to the sample request:
Result
Payer information.
In this example, the payer details remained the same as in the
To change the payment, use the following endpoint:
https://payment-api.sandbox.tuumplatform.com/api/v3/payments/{paymentId}/change
Learn more about the
Use case data
API parameters with values
https://sepa-api.sandbox.tuumplatform.comapi/v1/batch/PAYM-8813/settlement-transactions
Learn more about the
After
Use case data
API parameters with values
https://payment-api.sandbox.tuumplatform.com/api/v1/accounts/ID-1026/fx-quotes/ID-1263
Learn more about the
We get the FX quote response ID along with other details. Next, we will READY .
Copy ...v3/payments/PAYM-21826/change
Copy {
"typeCode": "OUR_PARTY",
"accountNumber": {
"value": "21824474",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "608382"
}
Copy {
"typeCode": "COUNTERPARTY",
"name": "Test Receiver",
"accountNumber": {
"value": "56497232",
"type": "BBAN"
},
"accountNumberCountryCode": "GB",
"financialInstitutionId": "BARCGB22"
}
Copy "money": {
"amount": 20,
"currencyCode": "GBP"
} The path parameter is the payment ID. The ID is taken from the response to the payment request.
Copy ".../PAYM-8813/settlement-transactions"
Copy {
"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"
}
]
} The first path parameter is the technical ID of the account to which the payment is being made.
Copy ".../ID-1026/fx-quotes/..." The second path parameter is the FX quote request ID that we got from initialising the request.
Copy {
"errors": null,
"validationErrors": null,
"data": {
"quoteRequestId": "ID-1263",
"accountId": "ID-1026",
"accountNumber": {
"value": "DK9189000099106120",
"type": "IBAN"
},
"accountServiceProviderCode": "BC",
"currencyPair": "EURUSD",
"sellCurrencyCode": "EUR",
"buyCurrencyCode": "USD",
"money": {
"amount": 30,
"currencyCode": "EUR"
},
"tenor": "TODAY",
"comment": null,
"source": null,
"statusCode": "READY",
"errorCode": null,
"quoteDtime": "2023-07-20T10:32:15.18642Z",
"tradeDate": "2025-05-08",
"settlementDate": "2025-05-08",
"quoteResponses": [
{
"quoteRequestId": "ID-1263",
"quoteResponseId": "ID-1217",
"buyMoney": {
"amount": 34.76,
"currencyCode": "USD"
},
"sellMoney": {
"amount": 30,
"currencyCode": "EUR"
},
"marginMoney": {
"amount": 0.35,
"currencyCode": "USD"
},
"feeMoney": null,
"quoteProviderResponseId": "ID-1217",
"exchangeRate": 1.158594,
"fixedSide": "SELL"
}
],
"requestReason": "FX"
}
} Here, you can find one of the examples of how to create a draft payment using the
Here, you can find one of the examples of how to create a draft payment using the
Here, you can find one of the examples of how to create a draft payment using the
Here, you can find one of the examples of how to create a draft payment using the
