### Example Tuum Authentication API URL

Source: https://developer.tuumplatform.com/getting-started

This is an example of a specific Tuum API endpoint, showing the authentication API in the shared sandbox environment.

```text
https://auth-api.sandbox.tuumplatform.com
```

--------------------------------

### Example x-channel-code Header

Source: https://developer.tuumplatform.com/getting-started

This shows an example of the x-channel-code header, used to specify the type of authenticated user making the API call. It can be 'SYSTEM' for application identity or 'SELFSERVICE' for customer identity.

```json
{
  "x-channel-code": "SYSTEM"
}
```

--------------------------------

### Card Product Statuses

Source: https://developer.tuumplatform.com/getting-started

This section details the possible statuses a card product can have and their implications.

```APIDOC
## Card Product Statuses

### Description
This endpoint provides information about the different statuses a card product can possess, along with a description of each status.

### Parameters
None

### Response
#### Success Response (200)
- **statuses** (array) - A list of card product statuses.
  - **status** (string) - The name of the status (e.g., Inactive, Active, Restricted, Closed).
  - **description** (string) - A detailed explanation of the status.

#### Response Example
```json
{
  "statuses": [
    {
      "status": "Inactive",
      "description": "By default, the new card products are created in an inactive state. Therefore, to start using the card product, you need to activate it."
    },
    {
      "status": "Active",
      "description": "The card product is activated and can be used for issuing new cards."
    },
    {
      "status": "Restricted",
      "description": "The card product cannot be used for issuing new cards."
    },
    {
      "status": "Closed",
      "description": "The card product is closed."
    }
  ]
}
```
```

--------------------------------

### Example Notification Payload

Source: https://developer.tuumplatform.com/getting-started

This JSON payload represents an example notification generated for a 'loan application accepted' event. It includes details such as notification ID, type, destination, and specific data related to the application.

```json
{
    "notificationId": "ID-0001"
    "notificationTypeCode": "LOAN_APPLICATION_ACCEPTED",
    "destination": "https://hooks.example.com/example",
    "data": {
        "applicationId":"ID-1600",
        "personId":"ID-1000",
        "statusCode": "ACCEPTED",
        "messageDTime":"2021-04-30T09:04:37.108561Z",
        "bankingDate":"2021-05-12"
    }
}
```

--------------------------------

### Account Limit Setup API - Create Account Limit

Source: https://developer.tuumplatform.com/getting-started

This endpoint creates an individual account limit, applying a specific limit type and amount to an account or user.

```APIDOC
## POST /account/limit/setup/limit

### Description
Creates an individual account limit for a specific account or user.

### Method
POST

### Endpoint
/account/limit/setup/limit

### Parameters
#### Request Body
- **limitTypeId** (string) - Required - The `limitTypeId` generated by the create account limit type endpoint.
- **accountId** (string) - Optional - The ID of the account to which the limit applies.
- **userId** (string) - Optional - The ID of the user to whom the limit applies.
- **limitAmount** (number) - Required - The limit amount.
- **currencyCode** (string) - Required - The currency code for the limit amount (e.g., "USD").

### Request Example
```json
{
  "limitTypeId": "limit-type-abc456",
  "accountId": "acc-987654",
  "limitAmount": 5000.00,
  "currencyCode": "USD"
}
```

### Response
#### Success Response (200)
- **limitId** (string) - The unique identifier for the created account limit.
- **limitTypeId** (string) - The limit type ID associated with this limit.
- **accountId** (string) - The account ID if applicable.
- **userId** (string) - The user ID if applicable.
- **limitAmount** (number) - The specified limit amount.
- **currencyCode** (string) - The currency code for the limit.

#### Response Example
```json
{
  "limitId": "account-limit-def789",
  "limitTypeId": "limit-type-abc456",
  "accountId": "acc-987654",
  "userId": null,
  "limitAmount": 5000.00,
  "currencyCode": "USD"
}
```
```

--------------------------------

### Card API - Introduction

Source: https://developer.tuumplatform.com/getting-started

Provides an overview of the Card API's capabilities and the card lifecycle stages it supports.

```APIDOC
## Card API - Introduction

The Card API is a set of endpoints that allow managing issued cards. Using the Card API, you can activate, modify cards settings, and change card status.

The card lifecycle includes the following steps:
  * Activating the card
  * Modifying the card settings
  * Blocking the card
  * Unblocking the card
  * Closing the card
  * Reopening the card
  * Replacing the card
```

--------------------------------

### Finding FX Orders

Source: https://developer.tuumplatform.com/getting-started

Endpoints for retrieving FX order information.

```APIDOC
## Get FX Orders by Account ID and Quote Request ID

### Description
Retrieves FX orders associated with a specific account ID and quote request ID.

### Method
GET

### Endpoint
/accounts/{accountId}/fx-orders?quoteRequestId={quoteRequestId}

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the account.
#### Query Parameters
- **quoteRequestId** (string) - Required - The ID of the quote request.

### Response
#### Success Response (200)
- **fxOrders** (array) - A list of FX orders matching the criteria.

### Response Example
```json
{
  "fxOrders": [
    {
      "fxOrderId": "fxo_abc123",
      "status": "COMPLETED"
    }
  ]
}
```

## Get FX Orders by Order ID

### Description
Retrieves a specific FX order using its unique order ID.

### Method
GET

### Endpoint
/fx-orders/{orderID}

### Parameters
#### Path Parameters
- **orderID** (string) - Required - The ID of the FX order to retrieve.

### Response
#### Success Response (200)
- **fxOrderId** (string) - The unique identifier for the FX order.
- **status** (string) - The current status of the FX order.

### Response Example
```json
{
  "fxOrderId": "fxo_abc123",
  "status": "COMPLETED"
}
```
```

--------------------------------

### Loan Offer API

Source: https://developer.tuumplatform.com/getting-started

Manages the creation, modification, acceptance, and declination of loan offers.

```APIDOC
## Introduction to Loan Offer API

Loan offer management involves calculating financial parameters, presenting them, and negotiating with the borrower. The Loan Offer API facilitates these actions.

### Loan Offer Lifecycle Steps:
  * Creating loan offer
  * Calculating the financial terms of the loan offer
  * Modifying the loan offer
  * Calculating the Annual Percentage Rate (APR)
  * Reviewing and validating the offer
  * Negotiating the offer conditions with the borrower
  * The borrower deciding to accept or to decline the offer
```

--------------------------------

### Example x-auth-token Header

Source: https://developer.tuumplatform.com/getting-started

This demonstrates the format of the x-auth-token header, which contains a JSON Web Token (JWT) for authenticating API calls. The token includes expiry information, roles, and other identity details.

```json
{
  "x-auth-token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMTAtMDRUMTM6MTI6MzYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTY0MjUxNTZ9.jelwZ8DCr9qBhJ0IBy_3i6Ki0Yc0-Clq92FDubiZQ4c"
}
```

--------------------------------

### Account Limit Setup API - Create Account Limit Type

Source: https://developer.tuumplatform.com/getting-started

This endpoint is used to create a new account limit type, defining the scope, period, and calculation method for limits.

```APIDOC
## POST /account/limit/setup/type

### Description
Creates a new account limit type. This defines the configuration for an account limit or a default rule.

### Method
POST

### Endpoint
/account/limit/setup/type

### Parameters
#### Request Body
- **scopeTypeCode** (string) - Required - Defines the limit scope. Allowed values: ACCOUNT, ACCOUNT_USER, ACCOUNT_OWNER.
- **periodTypeCode** (string) - Required - Specifies the period when the limit type is active. Allowed values: YEARLY, MONTHLY, WEEKLY, DAILY.
- **calcTypeCode** (string) - Required - Defines the calculation type. Allowed values: CROSS_CURRENCY, PER_CURRENCY.
- **limitCode** (string) - Optional - The **code** generated by the account limit code creation call. Required only for customized limits; otherwise, it should be null.

### Request Example
```json
{
  "scopeTypeCode": "ACCOUNT",
  "periodTypeCode": "MONTHLY",
  "calcTypeCode": "CROSS_CURRENCY",
  "limitCode": "TRANSACTION_LIMIT_CODE"
}
```

### Response
#### Success Response (200)
- **limitTypeId** (string) - The unique identifier for the created account limit type.
- **scopeTypeCode** (string) - The scope type code.
- **periodTypeCode** (string) - The period type code.
- **calcTypeCode** (string) - The calculation type code.
- **limitCode** (string) - The limit code used.

#### Response Example
```json
{
  "limitTypeId": "limit-type-xyz789",
  "scopeTypeCode": "ACCOUNT",
  "periodTypeCode": "MONTHLY",
  "calcTypeCode": "CROSS_CURRENCY",
  "limitCode": "TRANSACTION_LIMIT_CODE"
}
```
```

--------------------------------

### Account Limit Setup API - Create Account Limit Code

Source: https://developer.tuumplatform.com/getting-started

This endpoint is used to create a new account limit code, which serves as a unique identifier for account limit types. It allows for custom naming and descriptions.

```APIDOC
## POST /account/limit/setup/code

### Description
Creates a new account limit code. This is an optional step used to define a specific subtype for limits.

### Method
POST

### Endpoint
/account/limit/setup/code

### Parameters
#### Request Body
- **name** (string) - Required - The name of the limit code. Must follow specific naming rules (uppercase letters, numbers, underscores, not starting/ending with underscore, no double underscores).
- **description** (string) - Optional - A description for the limit code.
- **enabled** (boolean) - Required - Set to true to enable the account limit code.

### Request Example
```json
{
  "name": "TRANSACTION_LIMIT_CODE",
  "description": "Code for general transaction limits",
  "enabled": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created account limit code.
- **name** (string) - The name of the account limit code.
- **description** (string) - The description of the account limit code.
- **enabled** (boolean) - Indicates if the account limit code is enabled.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "TRANSACTION_LIMIT_CODE",
  "description": "Code for general transaction limits",
  "enabled": true
}
```
```

--------------------------------

### Account Limit Setup API - Create Default Limit Rule

Source: https://developer.tuumplatform.com/getting-started

This endpoint creates a default limit rule, connecting an account limit type to a default limit amount for new balances.

```APIDOC
## POST /account/limit/setup/default_rule

### Description
Creates a default limit rule, linking an account limit type to a default limit amount.

### Method
POST

### Endpoint
/account/limit/setup/default_rule

### Parameters
#### Request Body
- **limitTypeId** (string) - Required - The `limitTypeId` generated by the create account limit type endpoint.
- **limitAmount** (number) - Required - The default limit amount.
- **currencyCode** (string) - Required - The currency code for the limit amount (e.g., "EUR").

### Request Example
```json
{
  "limitTypeId": "limit-type-xyz789",
  "limitAmount": 10000.00,
  "currencyCode": "EUR"
}
```

### Response
#### Success Response (200)
- **defaultRuleId** (string) - The unique identifier for the created default limit rule.
- **limitTypeId** (string) - The limit type ID associated with this rule.
- **limitAmount** (number) - The default limit amount.
- **currencyCode** (string) - The currency code for the limit.

#### Response Example
```json
{
  "defaultRuleId": "default-rule-abc123",
  "limitTypeId": "limit-type-xyz789",
  "limitAmount": 10000.00,
  "currencyCode": "EUR"
}
```
```

--------------------------------

### Card API - Activate Card

Source: https://developer.tuumplatform.com/getting-started

Explains the process of activating a card, which is initially in an 'Open' or 'Wallet' status.

```APIDOC
## Card API - How to activate a card

By default, all new cards are created in an inactive state in the **Open** or **Wallet** statuses. The status of the new card depends on the card product settings.

If the card product:
  * _Is not allowed_ to be used before delivery to the cardholder, it is set to the Open status;
  * _Is allowed_ to be used before the delivery to the cardholder, it is set to the Wallet status.

Therefore, you need to activate the card before using it.
__
If the cardholder does not want to use an issued card, you can close the card in the Open or Wallet status without activating it.
```

--------------------------------

### API Call Essentials

Source: https://developer.tuumplatform.com/getting-started

Details on constructing the base URL for Tuum API calls, including environment and domain specifications.

```APIDOC
## API Call Essentials

To make an API call to any Tuum environment, you must use the appropriate HTTP path. The generic Tuum HTTP path structure looks as follows:

```
https://{{tuum-api}}.{{env}}.{{domain}}
```

### HTTP Path Components

| Component | Description |
|---|---|
| **tuum-api** | The name of the respective Tuum API you want to call (e.g., `auth-api`, `person-api`). |
| **env** | The environment where the target API is located (e.g., `sandbox`, `dev`, `test`). |
| **domain** | The web address where the target API is located (e.g., `tuumlatform.com`). |

### Example Endpoint

The HTTP path to the authentication API in the Tuum shared sandbox looks as follows:

```
https://auth-api.sandbox.tuumplatform.com
```
```

--------------------------------

### Account Limit Setup API - Update Account Limit Code

Source: https://developer.tuumplatform.com/getting-started

This endpoint allows enabling an existing account limit code that was previously created without being enabled.

```APIDOC
## PUT /account/limit/setup/code/{id}

### Description
Updates an existing account limit code. Primarily used to enable a disabled limit code.

### Method
PUT

### Endpoint
/account/limit/setup/code/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the account limit code to update.

#### Request Body
- **enabled** (boolean) - Required - Set to true to enable the account limit code.

### Request Example
```json
{
  "enabled": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the updated account limit code.
- **name** (string) - The name of the account limit code.
- **description** (string) - The description of the account limit code.
- **enabled** (boolean) - Indicates if the account limit code is enabled.

#### Response Example
```json
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "TRANSACTION_LIMIT_CODE",
  "description": "Code for general transaction limits",
  "enabled": true
}
```
```

--------------------------------

### Loan Application API - Introduction

Source: https://developer.tuumplatform.com/getting-started

Provides an overview of the Loan Application API, its purpose in managing loan applications from request to offer.

```APIDOC
## Introduction to Loan Application API

Loan application management is a process when a borrower applies for a loan, and a lender processes the loan application and evaluates the risks. Using the Loan Application API, you can create, accept or decline the application for the loan.

### Lifecycle Steps:

1.  Requesting the loan through the lender’s UI
2.  Creating the loan application in Tuum
3.  Preparing an asset for the collateral if the borrower applied for a secured loan
4.  Reviewing the loan application
5.  Modifying the loan application
6.  Validating the changes
7.  Scoring the loan application if the application was not scored by your company
8.  Reviewing the loan scoring
9.  Declining the application if the application score does not match the requirements
10. Creating a loan offer if the application score matches the requirements
```

--------------------------------

### Authorization Headers

Source: https://developer.tuumplatform.com/getting-started

Details on the required HTTP headers for authorized API calls: `x-auth-token` and `x-channel-code`.

```APIDOC
## Authorisation Headers

### Description

Authorisation means allowing authenticated users to access the resources they have the right to engage. For authorised API calls, you must use the `x-auth-token` and `x-channel-code` HTTP header parameters in each API call.

### `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

```json
{
    "x-auth-token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMTowN0QxMTo1Ny40MTdaIiwicm9sZXMiOlsiQURNSU4iXSwibmFtZSI6IkpvaG4gT2ZmaWNlciIsImVtcGxveWVlSWQiOiIxIiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwIjoxNjk2NDI1Mzk3fQ.zYjY0ZGRhNTRiYmM5MDI4NWJkNjE4NTRhNzM5OGI2ZTY3ZWE5NjA4NmFlZjIzNjI0ZjBhMmUyODc4ZGVlYWRjNQ"
}
```

__
To refresh the expired x-auth-token, call the authentication refresh API endpoint.

### `x-channel-code`

For the HTTP header parameter `x-channel-code`, use the following values:
  * **SYSTEM** - to perform API calls with the `x-auth-token` of the digital identity of your application.
  * **SELFSERVICE** - to perform API calls with the `x-auth-token` of the digital identity of the authenticated customer.

#### Example

```json
{
    "x-channel-code": "SYSTEM"
}
```

__
Please ignore examples in the API reference where the deprecated header parameter `x-tenant-code` is present. We will update examples in the API reference shortly.
```

--------------------------------

### Loan Contract Notifications

Source: https://developer.tuumplatform.com/getting-started

Setting up and managing webhook notifications for loan contract events.

```APIDOC
## Loan Contract Notifications (Webhooks)

### Description
Configure webhook notifications to monitor changes in loan contracts. Supported notification types include contract creation, acceptance, activation, replacement, import, blocking, and cancellation.

### Setup Steps
1. Enable notification.
2. Subscribe to a webhook.

### Supported Notification Types
- **LOAN_CONTRACT_CREATED**: Sends information when a new loan contract is created.
- **LOAN_CONTRACT_ACCEPTED**: Sends information when a loan contract is accepted.
- **LOAN_CONTRACT_ACTIVATED**: Sends information when a loan contract is activated.
- **LOAN_CONTRACT_REPLACED**: Sends information when a contract is replaced.
- **LOAN_CONTRACT_IMPORTED**: Sends information when a contract is imported.
- **LOAN_CONTRACT_BLOCKED**: Sends information when a loan contract is blocked.
- **LOAN_CONTRACT_CANCELED**: Sends information when a contract is cancelled.

### To Stop Notifications
Unsubscribe from the webhook and disable the notification configuration.
```

--------------------------------

### Loan Contract Management

Source: https://developer.tuumplatform.com/getting-started

Actions to manage the lifecycle of a loan contract including cancellation, acceptance, and disbursement.

```APIDOC
## Loan Contract Actions

### Description
Manages the lifecycle of a loan contract through cancellation, acceptance, or disbursement.

### Cancel Loan Contract

#### Method
POST (example, actual method may vary)

#### Endpoint
`/contracts/{contractId}/cancel`

#### Description
Terminates the loan origination flow. Can only be performed if the contract status is DRAFT, WAITING_FOR_SIGNATURE, or WAITING_FOR_ACTIVATION.

### Accept Loan Contract

#### Method
POST (example, actual method may vary)

#### Endpoint
`/contracts/{contractId}/accept`

#### Description
Accepts the loan contract, typically performed by the lender if required by the product configuration.

### Disburse Loan Contract

#### Method
POST (example, actual method may vary)

#### Endpoint
`/contracts/{contractId}/disburse`

#### Description
Transfers loan funds to the borrower's account or initializes manual disbursement. Applicable for credit lines.
```

--------------------------------

### Loan Application Notifications

Source: https://developer.tuumplatform.com/getting-started

Allows setting up webhooks to receive notifications for loan application events.

```APIDOC
## Webhook Notifications for Loan Applications

### Description
Set up notifications via webhooks to track loan application events. This involves enabling notifications and subscribing to a webhook.

### Notification Types:
- **LOAN_APPLICATION_ACCEPTED**: Notifies when a loan application is accepted by Tuum.
- **LOAN_APPLICATION_DECLINED**: Notifies when a loan application is cancelled by Tuum.

### Setup Steps:
1. Enable notification configuration.
2. Subscribe to the webhook with the desired notification types.

### To Stop Notifications:
1. Unsubscribe from the webhook.
2. Disable notification configuration.
```

--------------------------------

### Loan Contract Management API

Source: https://developer.tuumplatform.com/getting-started

This section details the APIs for managing loan contracts, including creation, versioning, and activation.

```APIDOC
## Introduction to Loan Contract API

Loan contract management is a process that automatically starts when the borrower accepts the loan offer. During that period, the lender prepares the contract for signing, activation and loan disbursement. Using the Loan Contract API, you can accept the loan contract and disburse the loan.

The contract activation steps include the following:
  * Creating loan contract;
  * Generating loan documents;
  * Signing loan contract;
  * Binding loan with collateral if the borrower applies for a secured loan;
  * Reviewing loan contract;
  * Creating an overdraft account if the borrower requests an overdraft loan;
  * Activating loan contract;
  * Disbursing the loan.

## How to create loan contract

The loan contract is a third step of the loan origination process after the loan offer. A new loan contract is automatically created when the borrower accepts the loan offer. Each loan contract has the following parameters:
  * **contract number** - a unique number,
  * **header ID** - the group ID number that relates the initial loan contract with its versions.

A contract can have unlimited versions and only one draft version at a time.

## Loan contract versions

Loan contract versions allow making changes to the loan contract. The loan contract versions have a defined lifecycle. It consists of the following:
  * Creating a new draft contract version;
  * Modifying a new draft contract version;
  * Activating a new contract version;
  * Cancelling a draft contract version.

### How to create loan contract versions

To create a new contract version, you can use the Loan Contract Change APIs. Note that a new version is saved as a draft. Each loan contract version has a **version ID** and a **version number**.

You can create new loan contract versions with different parameters:
  * new loan period,
  * payment free months,
  * specific payment day,
  * repayment amount,
  * repayment conditions,
  * loan limit,
  * interest rate,
  * temporary fee conditions.

Also, you can create a top-up contract version that allows you to disburse an additional amount under an existing loan contract. With the top-up, the loan principal balance increases by the amount of the additional top-up amount disbursement. And the system re-calculates the repayment schedule.

### How to find loan contract versions

You can find the components of the contract version in the following ways:
  * You can find the contract version with the header ID.
  * You can get the latest activated version of a contract for the given contract header ID. If the contract hasn't been activated, then the endpoint returns the version for which the activation is pending.
  * Also, there is a dedicated endpoint to find the contract version schedule.

### How to manage loan contract versions

To manage the contract draft versions, you can:
  * Modify draft contract version - to update the contract draft version.
  * Activate contract version - to replace the current contract version with the new one.
  * Cancel contract version - to update the status of the contract version to the **CANCELLED** status.

The initial contract created by the system has a version number set to 1.
Once the initial version of the loan contract is created, you can search the contract and contract parameters.

## How to find loan contract

There are different ways how you can find loan contracts:
  * header ID,
  * person ID,
  * version ID,
  * multiple criteria.

You can find the following contract parameters:
  * loan interest,
  * loan accrued interest,
  * loan contract schedule,
  * contract payouts,
  * loan contract deductions,
  * contract fee components available for editing,
  * repayment status,
  * balance history,
  * action history,
  * all loan contract parameters.

Also, you can query the top-up version parameters if you have an existing contract top-up version.
```

--------------------------------

### Loan Origination Parameters

Source: https://developer.tuumplatform.com/getting-started

Describes loan origination flags that configure the loan process flow, including options for manual input.

```APIDOC
## Loan Origination Parameters

Loan origination flags define the configuration of the loan process flow. By enabling some of the parameters, you can specify if the loan flow requires manual input or not. To modify the loan origination parameters, use the Update loan product endpoint.

### Parameters

*   **Application change** (boolean) - Can the loan application be updated after being reviewed and presenting an offer?
*   **Scoring review** (boolean) - Should the lender manually review the results of the application scoring?
*   **Payment instructions** (boolean) - Should the lender specify the details of the outgoing payment defining the beneficiary account and payment details?
*   **Application review** (boolean) - Should the lender review the loan application data after submitting it to the Tuum system?
*   **Offer review** (boolean) - Can the lender review the loan offer before the offer is presented to the borrower?
*   **Contract review** (boolean) - Should the lender review the loan contract before the activation?
*   **File generation** (boolean) - Should the system generate the loan documentation printouts?
*   **Signature** (boolean) - Should the loan contract be signed before being activated?
*   **Collateral** (boolean) - Is the collateral review required? Note: collateral is only required for secured types of loans.
*   **Overdraft account** (boolean) - Should an overdraft account be created? Note: this is only valid for overdraft loans.
*   **Account sweep** (boolean) - Is account sweep required? Note: account sweep connects a loan contract to a current account. This account automatically transfers all funds to the loan contract.
```

--------------------------------

### Card API - Card Statuses

Source: https://developer.tuumplatform.com/getting-started

Details the possible statuses a card can have within the system.

```APIDOC
## Card API - Card Statuses

A card can have one of the following statuses:

| Status | Description |
|---|---|
| Open | The card is issued but not activated yet. |
| Active | The card is activated and can be used for financial operations. |
| Blocked | The card is blocked to disable the card usage temporarily. |
| Closed | The card is closed when it is lost or stolen. |
| Wallet | The card can be used virtually before the plastic card is delivered to the cardholder. |
```

--------------------------------

### Manage Loan Offer Lifecycle

Source: https://developer.tuumplatform.com/getting-started

Allows lenders to perform actions on a loan offer, including reviewing, approving, declining, or cancelling it.

```APIDOC
## POST /offers/{offerId}/actions

### Description
Performs lifecycle actions on a loan offer, such as review, approve, decline, or cancel.

### Method
POST

### Endpoint
/offers/{offerId}/actions

### Parameters
#### Path Parameters
- **offerId** (string) - Required - The ID of the loan offer.

#### Request Body
- **action** (string) - Required - The action to perform (e.g., "REVIEW", "APPROVE", "DECLINE", "CANCEL").
- **comment** (string) - Optional - Additional comments regarding the action.

### Request Example
```json
{
  "action": "APPROVE",
  "comment": "Offer meets all criteria."
}
```

### Response
#### Success Response (200)
- **offerId** (string) - The ID of the loan offer.
- **status** (string) - The new status of the loan offer after the action.
- **message** (string) - Confirmation message of the action.

#### Response Example
```json
{
  "offerId": "offer_101jkl",
  "status": "APPROVED",
  "message": "Loan offer approved successfully."
}
```
```

--------------------------------

### Card API - Find Cards

Source: https://developer.tuumplatform.com/getting-started

Describes how to search for cards using various parameters.

```APIDOC
## Card API - How to find cards

Find cards by:
  * multiple search parameters
  * card id

Also, you can find some of the card parameters such as:
  * Personal Identification Number (PIN)
  * Card Verification Value (CVV)
```

--------------------------------

### POST /api/v2/persons

Source: https://developer.tuumplatform.com/getting-started

Creates a new private person record in the system.

```APIDOC
## POST /api/v2/persons

### Description
Creates a new private person record in the system, including identification and address details.

### Method
POST

### Endpoint
https://person-api.sandbox.tuumplatform.com/api/v2/persons

### Parameters
#### Request Body
- **personTypeCode** (string) - Required - The type code for the person (e.g., 'P' for private).
- **surname** (string) - Required - The surname of the person.
- **givenName** (string) - Required - The given name of the person.
- **identificationNumber** (object) - Required - Identification details.
  - **idNumber** (string) - Required - The identification number.
  - **idCountryCode** (string) - Required - The country code for the identification number.
- **addresses** (array) - Required - A list of addresses for the person.
  - **addressTypeCode** (string) - Required - The type code for the address (e.g., 'R' for registration).
  - **countryCode** (string) - Required - The country code of the address.
  - **cityCounty** (string) - Required - The city or county of the address.
  - **street1** (string) - Required - The first line of the street address.
  - **zip** (string) - Required - The postal code.

### Request Example
```json
{
    "personTypeCode": "P",
    "surname": "Thomas",
    "givenName": "Tuum",
    "identificationNumber": {
        "idNumber": "DQ654321C",
        "idCountryCode": "GB"
    },
    "addresses": [
        {
            "addressTypeCode": "R",
            "countryCode": "GB",
            "cityCounty": "Middleton Hall",
            "street1": "24 Botley Road",
            "zip": "NE71 3LL"
        }
    ]
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains details of the created person.
  - **personId** (string) - The unique identifier for the created person.
  - **statusCode** (string) - The status code of the person record.
  - **creationDate** (string) - The date the person record was created.
  - **personalInfo** (object) - Personal information of the person.
    - **personTypeCode** (string) - The type code for the person.
    - **givenName** (string) - The given name of the person.
    - **surname** (string) - The surname of the person.

#### Response Example
```json
{
  "errors": null,
  "validationErrors": null,
  "data": {
      "personId": "ID-1038",
      "statusCode": "ACTIVE",
      "source": null,
      "tenantCode": "MB",
      "forgotten": false,
      "creationDate": "2023-03-09",
      "personalInfo": {
          "personTypeCode": "P",
          "givenName": "Tuum",
          "middleName": null,
          "surname": "Thomas"
      }
  }
}
```
```

--------------------------------

### Notification Types API

Source: https://developer.tuumplatform.com/getting-started

Retrieve a list of available notification types for products to subscribe to updates.

```APIDOC
## GET /notification-types

### Description
Retrieves a list of all available notification types. This is useful for understanding what events you can subscribe to.

### Method
GET

### Endpoint
/notification-types

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **notificationTypes** (array) - A list of notification type codes.
  - **code** (string) - The unique code for the notification type (e.g., "LOAN_APPLICATION_ACCEPTED").
  - **description** (string) - A human-readable description of the notification type.

#### Response Example
{
  "notificationTypes": [
    {
      "code": "ACCOUNT_CREATED",
      "description": "Account Creation"
    },
    {
      "code": "LOAN_APPLICATION_ACCEPTED",
      "description": "Loan Application Accepted"
    }
  ]
}
```

--------------------------------

### Header Parameters

Source: https://developer.tuumplatform.com/getting-started

Optional header parameters for controlling API behavior, such as language and request idempotency.

```APIDOC
## Header Parameters

### Accept-Language

Using the **Accept-Language** optional header parameter, you can define the translation of the explanatory text in error messages. For the parameter value, use a two-character language code in lowercase (ISO 639-1), such as **fi** for **Finnish**.

**Example:**
```
"Accept-Language": "fi"
```

If an error message has no translation in a requested language, it appears in English.

### x-request-id

You can use the **x-request-id** optional header parameter to avoid sending duplicate POST requests. Simply assign it a value in a universally unique identifier (UUID, RFC 4122) format.

**Example:**
```
"x-request-id": "63354623-d264-443a-9d47-09e7b356ef11"
```

The duplication check with Tuum works as follows:
* If the header parameter **x-request-id** is not present, has no value, or is **null**, no duplication check will be performed. Each POST request will be treated as a new one.
* If you make several POST calls with the same **x-request-id** value and the same or different payload, Tuum will always return the same HTTP status and payload as it did in the first request.
* If you make several POST calls with unique **x-request-id** values and the same or different payload, Tuum will treat each request separately and will respond accordingly.
```

--------------------------------

### Manage Loan Application Lifecycle

Source: https://developer.tuumplatform.com/getting-started

Provides endpoints for managing the lifecycle of a loan application, including modifying, accepting, declining, and canceling.

```APIDOC
## PUT /loan/application/{applicationId}

### Description
Modifies an existing loan application. This action is allowed until a loan offer is created.

### Method
PUT

### Endpoint
/loan/application/{applicationId}

### Parameters
#### Path Parameters
- **applicationId** (string) - Required - The ID of the loan application to modify.

#### Request Body
- **amount** (number) - Optional - The updated loan amount.
- **term** (integer) - Optional - The updated loan term.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the application was updated.

#### Response Example
```json
{
  "message": "Loan application updated successfully."
}
```

## POST /loan/application/{applicationId}/accept

### Description
Accepts a loan application after review. This moves the application to the next stage, such as scoring or offer creation.

### Method
POST

### Endpoint
/loan/application/{applicationId}/accept

### Parameters
#### Path Parameters
- **applicationId** (string) - Required - The ID of the loan application to accept.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the application was accepted.

#### Response Example
```json
{
  "message": "Loan application accepted."
}
```

## POST /loan/application/{applicationId}/decline

### Description
Declines a loan application after review. This terminates the loan origination process.

### Method
POST

### Endpoint
/loan/application/{applicationId}/decline

### Parameters
#### Path Parameters
- **applicationId** (string) - Required - The ID of the loan application to decline.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the application was declined.

#### Response Example
```json
{
  "message": "Loan application declined."
}
```

## POST /loan/application/{applicationId}/cancel

### Description
Cancels a loan application initiated by the borrower. This terminates the loan origination process.

### Method
POST

### Endpoint
/loan/application/{applicationId}/cancel

### Parameters
#### Path Parameters
- **applicationId** (string) - Required - The ID of the loan application to cancel.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the application was cancelled.

#### Response Example
```json
{
  "message": "Loan application cancelled."
}
```
```

--------------------------------

### Authentication API

Source: https://developer.tuumplatform.com/getting-started

Information on how to authenticate with Tuum APIs to obtain a JSON Web Token (JWT) for authorized access.

```APIDOC
## Authentication API

### Description

Authentication is verifying your digital identity. To authenticate, call the authentication API endpoint. You will get a JSON Web Token (JWT) in the response for the authorised access to the other Tuum APIs.

To get the credentials for authentication, please get in touch with the Tuum Team through the contact form available on the Tuum webpage.

### Method

POST

### Endpoint

`/oauth/token` (Example, actual endpoint may vary)

### Request Body

*   **client_id** (string) - Required - Your application's client ID.
*   **client_secret** (string) - Required - Your application's client secret.
*   **grant_type** (string) - Required - Typically `client_credentials` for service-to-service authentication.

### Request Example

```json
{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
}
```

### Response

#### Success Response (200 OK)

*   **access_token** (string) - The JWT token for authorized access.
*   **token_type** (string) - The type of token (e.g., `Bearer`).
*   **expires_in** (integer) - The time in seconds until the token expires.

#### Response Example

```json
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHBpcnlEVGltZSI6IjIwMjMtMTAtMDRUMTM6MTI6MzYiLCJyb2xlcyI6WyJBRE1JTiJdLCJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHAiOjE2OTY0MjUxNTZ9.jelwZ8DCr9qBhJ0IBy_3i6Ki0Yc0-Clq92FDubiZQ4c",
    "token_type": "Bearer",
    "expires_in": 3600
}
```

__
To refresh the expired x-auth-token, call the authentication refresh API endpoint.
```

--------------------------------

### Account API

Source: https://developer.tuumplatform.com/getting-started

Manages customer bank accounts, including creation, updating, status changes, and closing.

```APIDOC
## Account Management API

### Description
This API allows for the creation and management of customer bank accounts within the Tuum environment. The account lifecycle includes creation, updating information, changing status (e.g., blocking, reactivating), and closing accounts.

### Account Types
- **Currency**: Holds balances in multiple currencies, supports fees and interest.
- **Internal**: A bank's technical account linked to a General Ledger (GL) account.
- **Virtual**: A customer account with a number for payments, does not store its balance; requires a master account ID.
- **Shadow**: A hidden customer account related to credit contract disbursements/repayments when currency accounts are not used.
- **Saving**: A customer account for setting aside funds and earning interest.

### Common Operations
- **Creating an account**: Establishing a new bank account.
- **Updating an account**: Modifying account details or overdraft limits.
- **Changing account status**: Blocking or reactivating an account.
- **Closing an account**: Setting the account status to closed.

### Example Use Cases
This documentation provides explanatory use cases based on the account lifecycle described above.
```

--------------------------------

### Receivables API

Source: https://developer.tuumplatform.com/getting-started

Manages contract-related repayments and invoicing, including invoice creation, repayment allocation, and credit notes.

```APIDOC
## Receivables API Overview

### Introduction
Receivables functionality enables the management of contract-related repayments through periodic invoicing. It handles the creation of invoices, allocation of customer payments, and management of exceptions. The process also includes the possibility of reversing repayments and crediting invoices.

### Receivables Structure
Receivables consist of **invoices** and **funds**.

- **Invoices**: Commercial documents issued by a lender detailing the amount and due date for customer payments. Each invoice line has an amount, balance (unpaid before due date), and debt (unpaid after due date).
- **Funds**: Money received as repayment or disbursed to a customer's account.

### Invoice Classification
- **PERIODIC**: Invoices generated according to the contract schedule with a fixed due date.
- **ONE_TIME**: Invoices generated for specific events like termination or after a customer's death.
- **PREMATURE_REPAYMENT**: Automatically created when a customer makes a payment exceeding the total debt plus the balance of all periodic or one-time invoices, and premature repayments are permitted.
```