Operational data and master data in APIs

This page explains the concepts of data you will encounter in Akkuro Lending APIs and how to use them correctly in integrations.

Operational and master data

Business entities in Akkuro Lending (for example, an agreement or a counterparty) can exist in two forms:

Operational data: A live, in-progress version used during a process
Master data: The single, finalized version used across the platform

Operational data

Operational data represents business entities created and updated during an active lending process (for example, loan origination, loan review, or loan management). It is dynamic and can change frequently.

In an operational (in-process) entity, the process field looks like this:

{
    "process": {
        "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
        "isClosed": false,
        "closedOn": null,
        "isSuccessful": null
    },
    ...
}

An active process is a workflow that is still running in the platform. During this workflow, users can make changes, such as updating counterparty details or adjusting facilities. These changes remain within the process and are not written to master data until the process reaches a final status and is closed and successful.

When the process is closed successfully, the entity’s process field looks like this:

{
    "process": {
        "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
        "isClosed": true,
        "closedOn": "2019-08-24T14:15:22Z",
        "isSuccessful": true
    },
    ...
}

Master data

Master data represents business entities that are stable and used as reference data across the system. It acts as the system's source of truth.

You can typically identify master data by the fact that it isn’t tied to a process. For master data entities, the process field is null.

{
    "process": null
}

Since master data is referenced across the platform, any change can affect every system or integration that reads it. For example, changing a counterparty’s registered name or address may impact business workflows, reporting, and integrations that rely on counterparty data. Instead, changes are handled through new processes with approval workflows and audit trails, rather than direct edits. Master data is created or updated only when a process reaches a final status and closes successfully.

info

To learn how master data is created, refer to New process with new data. This section shows how a new entity becomes master data.

Data state

When you are familiar with the concepts of operational data and master data, you can start using Akkuro Lending APIs more effectively.

When using Akkuro Lending APIs, you can determine which version of the entity you are reading and whether the entity is master data or operational data. This information is indicated by the dataSource field included in each entity.

The dataSource field can contain the following values:

Master: The stable, finalized version of the data. This state indicates that the entity is master data.
Start: The state of the data at the beginning of the process. The start state represents an initial baseline copy of the master data captured at the time the process was created (typically by importing master data). The start state does not change during the process and is useful for traceability and comparisons.
Current: The current state represents the latest values of operational data at the current time. This state reflects the live operational data right now, including any changes made so far during the process.

info

You can compare the start state (original values) with the current state to check what has changed.
You can retrieve the Start and Current data state in the path parameter for a specific process when you call an operational API. You can take a look at this Counterparty Query Operational API as an example.
Streaming APIs also include a dataSource field in the streaming response to indicate which type of data the stream contains.

Lifecycle of data

There are two common data lifecycle scenarios in Akkuro Lending:

A process is created with new data
A process is created from existing master data

New process with new data

Some processes start from scratch with entirely new data and entities. For example, a loan origination process may be created with entirely new counterparty information. In these cases, the process creates its own operational dataset.

When a process is created, it generates its own current operational data.

For example, when a loan application is submitted, a loan origination process is created with its new data, such as counterparty, collateral, and other relevant details.

In the following example, dataSource: Current indicates that the data represents the current state.

{
  "tenantReferenceId": "ALFA",
  "whitelabelReferenceId": "YOURBANK",
  "referenceId": "401faf0c-a52a-493b-9853-536771bd886c",
  "preferredCommunicationLanguage": "en-GB",
  "emailAddress": "example@topicus.nl",
  "isActive": true,
  "lifecycleStatus": "Counterparty",

  "process": {
    "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
    "isClosed": false,
    "closedOn": null,
    "isSuccessful": null
  },

  "organisationName": "Organisation 2 BE - all fields",
  "legalFormCode": "54M6",
  "mainSectorCode": {
    "code": "62.02",
    "type": "SBI"
  },

  "dataSource": "Current",
}

The process progresses through multiple statuses while decisions and updates are made. While the process is active, all changes remain operational.

When the process reaches a final status and is successfully closed, the finalized outcome becomes master data.

In this example, all data, such as counterparty, from the loan origination process is saved as master data in the system.

{
  "tenantReferenceId": "ALFA",
  "whitelabelReferenceId": "YOURBANK",
  "referenceId": "401faf0c-a52a-493b-9853-536771bd886c",
  "preferredCommunicationLanguage": "en-GB",
  "emailAddress": "examplemaster@topicus.nl",
  "isActive": true,
  "lifecycleStatus": "Counterparty",

  "process": null,

  "organisationName": "Organisation 2 BE - all fields",
  "legalFormCode": "54M6",
  "mainSectorCode": {
    "code": "62.02",
    "type": "SBI"
  },
  "dataSource": "Master",
}

You can identify master data using the following fields:

dataSource is Master.
process is null, which means the data is not associated with a process.

If the process closes unsuccessfully, no master data is created and the operational data becomes read-only.

After the process is closed, its operational data remains available for inspection and audit purposes, but it can no longer be modified and becomes read-only.

New process with existing data

Not every process starts from scratch.

If a process is created for an existing business entity (for example, a loan review for an existing agreement), the system imports the current master data for the new process.

When a process is created, the relevant master data is imported for that process. For example, if you create a process to modify existing counterparty information, the current counterparty master data is imported into the process.

The system imports the relevant master data into the process in two states:

A start state, which is a copy of the master data at the time the process was created.

In the following example, dataSource: Start indicates that the data represents the start state.

{
    "tenantReferenceId": "ALFA",
    "whitelabelReferenceId": "YOURBANK",
    "preferredCommunicationLanguage": "en-GB",
    "emailAddress": "example@topicus.nl",
    "lifecycleStatus": "Counterparty",

    "process": {
        "referenceId": "88d80b1a-a017-4798-baa6-fbb651a13466",
        "isClosed": false,
        "closedOn": null,
        "isSuccessful": null
    },

    "organisationName": "[094139] BV 3 Parts",
    "legalFormCode": "54M6",
    "mainSectorCode": {
        "code": "62.02",
        "type": "SBI"
    },
    "dataSource": "Start",
}

A current state, which represents the operational data that can change as updates are made during the process.

In the following example, dataSource: Current indicates that the data represents the current state.

{
    "tenantReferenceId": "ALFA",
    "whitelabelReferenceId": "YOURBANK",
    "preferredCommunicationLanguage": "en-GB",
    "emailAddress": "example@topicus.nl",
    "lifecycleStatus": "Counterparty",

    "process": {
        "referenceId": "88d80b1a-a017-4798-baa6-fbb651a13466",
        "isClosed": false,
        "closedOn": null,
        "isSuccessful": null
    },
    "organisationName": "[094139] BV 3 Parts",
    "legalFormCode": "54M6",
    "mainSectorCode": {
        "code": "62.02",
        "type": "SBI"
    },
    "dataSource": "Current",
}

During the process, all updates are applied only to the operational current state.

When the process is successfully completed, the approved outcome is updated to the existing master record.

The following example shows counterparty data stored as master data:

{
  "tenantReferenceId": "ALFA",
  "whitelabelReferenceId": "YOURBANK",
  "preferredCommunicationLanguage": "en-GB",
  "emailAddress": "examplemaster@topicus.nl",
  "isActive": true,
  "lifecycleStatus": "Counterparty",

  "process": null,

  "organisationName": "[094139] BV 3 Parts",
  "legalFormCode": "54M6",
  "mainSectorCode": {
    "code": "62.02",
    "type": "SBI"
  },
  "dataSource": "Master",
}

You can identify master data using the following fields:

dataSource is Master.
process is null, which means the data is not associated with a process.

If the process closes unsuccessfully, no changes are written to master data and the operational data becomes read-only.

Operational and master data​

Operational data​

Master data​

Data state​

Lifecycle of data​

New process with new data​

New process with existing data​