Lucinity API (3.3)

Download OpenAPI specification:Download

Welcome to the Lucinity API!

Lucinity is an API-first SaaS solution for AML: our platform ingests your data to make integration and data publishing simple and seamless. Our modular approach separates the functionality of the user interface centered around customer use cases, but the backend APIs are unified so the system can scale with your needs.

Quickstart Guide

Use this section to get familarized with the Lucinity API's syntax, payload, and data structures.

Following the steps detailed below, you'll be able to ingest data in the Lucinity platform and get started to Make Money Good.

The hidden power of your data

One of the highlights of Lucinity’s AML platform is the actionable insights that show how much information you can gain from the data you already have today.

We understand that data integration projects can be intimidating. When designing Lucinity’s APIs, we set out to make our data ingestion as integration-friendly as possible, while providing innovative and robust data analysis methodologies at the same time.

To get started, you can connect basic data to get you familiar with the integration quickly and easily. As your familiarity and confidence grows, Lucinity is capable to extend and accept even more data to unlock its full potential.

Behavioral AML Detection and Actor Intelligence follow the same data model and request information on your customers (Actors) and their Accounts, Transactions, and the mapping between Actors and Accounts.

Going deeper, you can provide Actor Associates, entities you know are linked to your customer, and additional Risk Assessments you might have.

The Lucinity Case Manager is integrated through Observation data and meta data belonging to a case surfaced by your legacy system.

You can bring all this data into the Lucinity platform using a rich but simple to use set of APIs. The APIs ingest and return JSON-encoded requests and response structure, and use HTTP response codes to present the result of your request allowing you to track and respond efficiently.

Access

As an AML solution intended for highly regulated financial institutions, Lucinity’s APIs rest (no pun intended) on secure access through an API key.

Lucinity Admin Portal

You can use the Administration Portal to manage your Lucinity Products. It allows you to manage API keys, system access, what behaviors are monitored, workflows, and all other configurations for the Lucinity Platform.

Lucinity API Keys

Lucinity authenticates your API requests using your account's API Keys: your API key is used to make API calls on behalf of your account, and allows you to interact with the Lucinity platform.

Get your API key

API Keys are generated via the Lucinity Platform by approved users. Please get in touch with your Customer Success Team for more information.

API Key

Treat your secret API key as, or more carefully, you would treat your password. We recommend keeping it out of any version control system you may be using. Grant access only to those who need it or secure them their own API credentials.

Lucinity stores your API keys in the Administration Portal. You can sign in to retrieve and manage your keys.

Using your API key

API keys have full access to your account and are owned by the account owner. Therefore, all actions are tied to a specific account. A single account can have multiple API keys you can share or rotate if needed.

See Authentication on how to use the API Key to authenticate your access.

Adding data

To use the Transaction Monitoring and Actor Intelligence modules of Lucinity, you need to add data for the relevant customers(actors), accounts, and transactions.

The eight simple steps below walk you through the process of using the Lucinity APIs to publish data to the platform and get your instance of Transaction Monitoring or Actor Intelligence modules up and running.

You can send the data in any order. However, to make it easier and more organized for data integration projects, we have structured data ingest around Actors, Accounts and Transactions.

1. Get Your API Keys Ready

Make sure you have your API Keys ready to authenticate with the Lucinity platform.

2. Ingest Actor Data

Collect your customer data and follow the data structure outlined below to ingest it to the Lucinity Platform.

The sidebar code snippets reflect the required data points for initializing the system, see Transaction Monitoring and Actor Intelligence for all available fields.

NOTE: There is a slight difference in the required fields between individuals and legal entities to ingest data. See the sidebar examples on how to ingest both actor types.

Transmitting Customer Data - Individual

const unirest = require("unirest");
unirest
.post("https://<your environment>/api/actors")
.headers({
  "X-Api-Key": "<Secret API Key>",
});
.send({
  id: "ACT985002241",
  asOfDate: "2019-08-24",
  status: "ACTIVE",
  type: "INDIVIDUAL",
  monitored: "YES",
  displayName: "Samantha Jones",
  name: "Samantha Jane Jones",
  dateOfBirth: "1966-01-21",
  gender: "FEMALE",
  addresses: [
    {
      type: "HOME",
      line1: "123 Bond Street",
      line2: "Mayfair",
      postcode: "W1S 1EJ",
      city: "London",
      country: "UK",
    },
  ],
  nationality: "UK",
  dataSource: "source-name"
});
.then((response) => {
  console.log(response.body);
})
.catch((err) => {
  console.log(err);
});

Transmitting Customer Data - Legal Entity

const unirest = require("unirest");
unirest
.post("https://<your environment>/api/actors")
.headers({
  "X-Api-Key": "<Secret API Key>",
});
.send({
  id: "ACT985002242",
  asOfDate: "2019-08-24",
  status: "ACTIVE",
  type: "LEGAL_ENTITY",
  monitored: "YES",
  displayName: "Vortexecurity",
  name: "Vortexecurity",
  legalEntity:
    {
      dateOfRegistration: "1991-01-09",
      type: "PARTNERSHIP_LIMITED",
      industry: [{
        code: "561621",
        type: "NAICS",
      }]
    },
  addresses: [
    {
      type: "HOME",
      line1: "123 Bond Street",
      line2: "Mayfair",
      postcode: "W1S 1EJ",
      city: "London",
      country: "UK",
    },
  ],
  nationality: "UK",
  dataSource: "source-name"
});
.then((response) => {
  console.log(response.body);
})
.catch((err) => {
  console.log(err);
});

3. Ingest Account Data

Collect your customer’s account data and follow the data structure outlined below to ingest it to the Lucinity Platform.

The sidebar code snippet reflects the account data fields required for initializing the system. See Transaction Monitoring and Actor Intelligence for all available fields.

Transmitting Accounts Data

const unirest = require("unirest");
unirest
    .send("https://<your environment>/api/accounts")
    .headers({
        "X-Api-Key": "<Secret API Key>",
    })
    .post({
        id: "ACC99140294",
        asOfDate: "2019-08-24",
        accountType: "CURRENT",
        currencyCode: "GBP",
        openedDate: "2019-08-24",
        terminationDate: null,
        accountNumber: "2340-234-234234",
        status: "ACTIVE",
        monitored: "YES",
        dataSource: "source-name",
    })
    .then((response) => {
        console.log(response.body);
    })
    .catch((err) => {
        console.log(err);
    });

4. Ingest Actor Account Mapping

Collect your customer’s and customer’s account data and follow the data structure outlined below to map Actors to Accounts in the Lucinity Platform.

Use the provided code snippet to try it out.

Transmitting Actor-Account Mapping

const unirest = require("unirest");
unirest
    .post("https://<your environment>/api/accounts/<Account ID>/actors")
    .headers({
        "X-Api-Key": "<Secret API Key>",
    })
    .send({
        asOfDate: "2019-08-24",
        actors: [
            {
                id: "ACT985002241",
                role: "OWNER",
            },
        ],
    })
    .then((response) => {
        console.log(response.body);
    })
    .catch((err) => {
        console.log(err);
    });

5. Ingest Balance on Accounts Data

Collect your customer’s account balance data and follow the data structure outlined below to ingest it to the Lucinity Platform.

The following code snippet reflects the required account balance data fields for initializing the system, see Actor Intelligence for all available fields.

Transmitting Account Balance Data

const unirest = require("unirest");
unirest
    .send("https://<your environment>/api/accounts/<Account ID>/balances")
    .headers({
        "X-Api-Key": "<Secret API Key>",
    })
    .post({
        asOfDate: "2019-08-24",
        currency: "USD",
        current: 5000,
        available: 4000,
        type: "CLOSING",
    })
    .then((response) => {
        console.log(response.body);
    })
    .catch((err) => {
        console.log(err);
    });

6. Ingest Transaction Data

Collect your customer’s transactions data and follow the data structure outlined below to ingest it to the Lucinity Platform.

The sidebar code snippet reflects the required transaction data fields for initializing the system, see Transaction Monitoring and Actor Intelligence for all available fields.

Transmitting Transaction Data

const unirest = require("unirest");
unirest
    .post("https://<your environment>/api/v2/transactions")
    .headers({
        "X-Api-Key": "<Secret API Key>",
    })
    .send({
        id: "TXN949000250",
        created_at: 1697470699,
        direction: "OUTBOUND",
        status: "COMPLETED",
        description: "Transfer for bill xx",
        channel: "ONLINE",
        account_id: "ACC99140294",
        amount: {
            value: 100.15,
            currency: "USD",
        },
        standardized_amount: 200.25,
        account_balance: 4000.05,
        account_owner_id: "ACT985002241",
        method: "WIRE_TRANSFER",
        purpose: "BILL_PAYMENT",
        counterparty: {
            object: "LEGAL_ENTITY",
            id: "CPid",
            name: "Vortexecurity",
            account_info: {
                account_number: "123-45-6789",
                iban: "GB61xxxxxxxxxxxxxxxxxxxx",
                country: "GBR",
            },
            industry: {
                classification_identifier: "NAICS",
                code: "561621",
            },
            metadata: {
                identifiable_as_actor: "true",
            },
        },
        metadata: {
            international: "false",
        },
    })
    .then((response) => {
        console.log(response.body);
    })
    .catch((err) => {
        console.log(err);
    });

7. Actor Associates & Risk Assessment (Optional)

You can enrich the data with any additional information about your customers to get a better risk overview, such as entities linked to customers, internal or external risk assessments, etc. Follow the data structure outlined below.

Use the provided code snippet to try it out.

Transmitting Actor Associates

const unirest = require("unirest");
unirest
    .post("https://<your environment>/api/actors/<Actor ID>/associates")
    .headers({
        "X-Api-Key": "<Secret API Key>",
    })
    .send({
        asOfDate: "2019-08-24",
        actorAssociates: [
            {
                id: "AA842099",
                name: "Fred Patricks",
                type: "REPRESENTATIVE",
                customer: false,
                dataSource: "source-name",
            },
        ],
    })
    .then((response) => {
        console.log(response.body);
    })
    .catch((err) => {
        console.log(err);
    });

Transmitting Risk Assesment

const unirest = require("unirest");
unirest
    .post("https://<your environment>/api/actors/<Actor ID>/riskAssessments")
    .headers({
        "X-Api-Key": "<Secret API Key>",
    })
    .send([
        {
            asOfDate: "2019-08-24",
            type: "PEP",
            value: "1",
        },
    ])
    .then((response) => {
        console.log(response.body);
    })
    .catch((err) => {
        console.log(err);
    });

8. Initialize Your Data Batch

With all relevant data sent in steps 2-6, you need to evoke the initialize method to get the batch running and analyzed.

The initialization method you use depends on whether you want to run Transaction Monitoring or Actor Intelligence:

for Transaction Monitoring set the processType parameter to AML
for Actor Intelligence set the processType parameter to ACTOR

For more information see Initialize Batch

Use the code examples in the sidebar to get you started.

Initializing the batch for Transaction Monitoring.

const unirest = require("unirest");
unirest.post("https://<your environment>/api/detection/initialize");
.headers({
  "X-Api-Key": "<Secret API Key>",
})
.send({
  closeOfBusinessDate: "2020-02-01",
  lineOfBusiness: "INDIVIDUAL",
  processType: "AML",
})
.then((response) => {
  console.log(response.body);
})
.catch((err) => {
  console.log(err);
});

Further information

Refer to documentation for Transaction Monitoring and Actor Intelligence for information about how to use some of Lucinity’s advanced capabilities through APIs.

Make Money Good

That’s it! Expected more steps? Sorry to disappoint.

Congratulations, you are ready to Make Money Good with Lucinity. Have fun, and don't hesitate to reach out to us if you need assistance.

Authentication

Lucinity uses API Keys to authenticate your access to the environment. Authentication is performed via HTTP(S) with an Api key schema.

ApiKeyAuth

The client must send the key in an x-api-key header when making request to protected resources.

Authenticating

headers = { "x-api-key": "{API_KEY}" };

Core Data

Core Data represents the data points you add to Lucinity from sources like your KYC pipeline, transactions, etc.

After ingested, it is then used by the Lucinity platform to calculate risk scores and other operations that gives the AML team intelligent insight into customer behavior.

Actors

Add Actor

Add actor to Lucinity.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

The Actor to be added to Lucinity.

id required	string Primary identifier for the entity. If the entity type is transaction, it should be unique and consistent across entries.
dataSource	string An identifier that represents the system from which the record is originated.
	Array of objects (Reference) Reference attribute
ingestDate	string <date-time> Date time for when the object was ingested
	object (Classification) Deprecated Reference attribute
	object (AccessClassification) Deprecated Reference attribute
	object (Metadata) Reference attribute
type required	object (ActorType) Enum: "INDIVIDUAL" "LEGAL_ENTITY" Set of ActorTypes for the actor
subType	Array of strings (ActorSubType) Items Enum: "EMPLOYEE" "CUSTOMER" Set of ActorSubTypes for the actor
gender	string (ActorGender) Enum: "MALE" "FEMALE" "UNSPECIFIED" "OTHER" Gender reference
	object (LegalEntity) legal entity reference
name	string Name of individual or company
displayName	string Full name of individual or company that will be used for display
firstName	string First name of actor, can be individual or full company name
middleName	string Middle name of actor, can be empty if no middle name or company
lastName	string Last name of actor, can be individual or empty if company
isActive	boolean Deprecated Please use status and monitored. Flag for if actor is active (is actor dormant, has actor performed an activity last 60 days)
status	string Enum: "ACTIVE" "TERMINATED" Enumerated values of the actor status.
monitored	string Enum: "YES" "NO" Is Actor monitored? Default value `YES` -- if set to `NO` the Actor will be excluded from Lucinity's Behavioral Monitoring and Rule Engine.
dateOfBirth	string <date> Date of birth of the actor
	Array of objects (address) Address List
	Array of objects (phone) Phone Number List
	Array of objects (emailAddress) Emails List
nationality	string The 2 letter ISO 3116-1 Alpha-2 country code.
domicile	string The 2 letter ISO 3116-1 Alpha-2 country code.
asOfDate required	string <date> The date when this record became valid
	object (Employee) Deprecated Employee reference
	Array of objects (GovernmentId) Government id list for actor
	Array of objects (Link) links to external related objects for actor
validationStatus	string (ValidationStatus) Enum: "UNVALIDATED" "VALIDATED" "DUE_DILIGENCE" "VENDOR_SUPPLIED_DATA" "MANUAL_ENTRY" Validation status for actor data
	object (CustomData) The `customData` property can be used to add data in a key, value `<string,string>` format to the objects. This can e.g. be used for display purposes. CustomData will not be used by Lucinity in any processing. Maximum length of this property is 5000 characters.

Responses

Request samples

Payload

Content type

application/json

Example

Individual

{"id": "LUCINITY_ACTOR_ID_0002221233984",
"dataSource": "Lucinity",
"references": [{"id": "LUCINITY_INTERNAL_ID_123047124890",
"systemName": "LucinityInternalService"
}
],
"metadata": {"someProperty": "SomeValue"
},
"type": "INDIVIDUAL",
"subType": ["EMPLOYEE"
],
"gender": "FEMALE",
"name": "Wendy Byrde",
"displayName": "Wendy Byrde",
"firstName": "Wendy",
"middleName": null,
"lastName": "Byrde",
"status": "ACTIVE",
"monitored": "YES",
"addresses": [{"type": "HOME",
"line1": "6818 Gaines Ferry Rd",
"line2": "",
"postcode": "94109",
"city": "Flowery Branch",
"state": "GA",
"country": "USA"
}
],
"phones": [{"type": "HOME",
"number": "6135854487"
}
],
"emails": [{"type": "HOME",
"address": "[email protected]"
}
],
"nationality": "US",
"domicile": "US",
"taxResidency": "US",
"asOfDate": "2023-01-01",
"govermentIds": [{"id": "9423480129034",
"type": "SSN",
"issuingAuthority": "US",
"expirationDate": null
}
],
"relatedLinks": [{"link": "https://linkedin.com/u/wendy",
"description": "LinkedIn profile"
}
],
"validationStatus": "VALIDATED",
"customData": {"someProperty": "some value",
"otherProperty": "other value"
}
}

Response samples

Content type

application/json

Example

Individual

{"id": "LUCINITY_ACTOR_ID_0002221233984",
"name": "Wendy Byrde",
"type": "INDIVIDUAL",
"emails": [{"type": "HOME",
"address": "[email protected]"
}
],
"gender": "FEMALE",
"phones": [{"type": "HOME",
"number": "6135854487"
}
],
"status": "ACTIVE",
"subType": ["EMPLOYEE"
],
"asOfDate": "2023-01-01",
"domicile": "US",
"lastName": "Byrde",
"metadata": {"someProperty": "SomeValue"
},
"addresses": [{"city": "Flowery Branch",
"type": "HOME",
"line1": "6818 Gaines Ferry Rd",
"line2": "",
"state": "GA",
"country": "USA",
"postcode": "94109"
}
],
"firstName": "Wendy",
"monitored": "YES",
"customData": {"someProperty": "some value",
"otherProperty": "other value"
},
"dataSource": "Lucinity",
"externalId": "LUCINITY_ACTOR_ID_0002221233984",
"ingestDate": "2024-01-26T10:47:17.726442+00:00",
"internalId": "7bc4a334-397a-46f9-871c-0b557ba16318",
"references": [{"id": "LUCINITY_INTERNAL_ID_123047124890",
"systemName": "LucinityInternalService"
}
],
"dateOfBirth": "1954-09-12",
"displayName": "Wendy Byrde",
"legalEntity": {"industry": [{ }
]
},
"nationality": "US",
"relatedLinks": [{"link": "https://linkedin.com/u/wendy",
"description": "LinkedIn profile"
}
],
"classification": {"city": [ ],
"group": [ ],
"domain": [ ],
"region": [ ],
"country": [ ],
"business": [ ],
"department": [ ]
},
"validationStatus": "VALIDATED",
"accessClassification": {"city": [ ],
"group": [ ],
"domain": [ ],
"region": [ ],
"country": [ ],
"department": [ ],
"elevatedPrivilege": [ ]
}
}

Add Actor Associates

Add associates to actors by ID.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Actor ID

Request Body schema: application/json

Associates to be tagged to an actor.

	Array of objects (ActorAssociate) Actor associate name, example would be a full name of individual or representative
asOfDate	string <date> The date when this record became valid

Responses

Request samples

Payload

Content type

application/json

{"actorAssociates": [{"id": "LUCINITY_ACTOR_ID_89012730812411",
"references": [{"id": "LUCINITY_INTERNAL_ID_88614467199170002",
"systemName": "LucinityInternalService"
}
],
"dataSource": "Lucinity Actor Database",
"name": "Jonathan Hawker",
"type": "Parent",
"isCustomer": true
}
],
"asOfDate": "2023-04-22"
}

Response samples

Content type

application/json

{"actorAssociates": [{"id": "LUCINITY_ACTOR_ID_89012730812411",
"references": [{"id": "LUCINITY_INTERNAL_ID_88614467199170002",
"systemName": "LucinityInternalService"
}
],
"dataSource": "Lucinity Actor Database",
"name": "Jonathan Hawker",
"type": "Parent",
"isCustomer": true
}
],
"asOfDate": "2023-04-22"
}

Add Actor RiskAssessment

Add actor risk assessment.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Actor ID

Request Body schema: application/json

Risk Assessment to be added for an actor.

Array

asOfDate required	string <date> Date when record came valid
type required	string Enum: "INTERNAL" "PEP" "SANCTIONS" "ADVERSE_MEDIA" "INTP" "PP" "SAR" Used to specify Risk Assessment type. The type can be any string, depending on organizational guidelines, except for the following which are reserved for specific Risk Assessments: INTERNAL - Internal Risk Assessment of the actor (The risk score that is derived from the CDD process). The value should be numeric on a scale decided in co-operation with Lucinity. PEP - Politically Exposed Person. The value should be "1" for PEPs and "0" otherwise. SANCTIONS - On a sanctions list. The value should be "1" if the actor appears on any sanctions list and "0" otherwise. ADVERSE_MEDIA - Has appeared in an Adverse Media report. Value should be "1" if true and "0" otherwise. INTP - Actor is an intermediary processing entity for transactions. Value should be "1" if true and "0" otherwise. PP - Actor is a payment processor. Value should be "1" if true and "0" otherwise. SAR - Suspicious Activity Report. Value should be the number of SARs the actor has had.
value required	string Value of risk assessment
comment	string reason for risk or related commment

Responses

Request samples

Payload

Content type

application/json

[{"asOfDate": "2019-08-24",
"type": "INTERNAL",
"value": "string",
"comment": "string"
}
]

Response samples

Content type

application/json

[{"asOfDate": "2019-08-24",
"type": "INTERNAL",
"value": "string",
"comment": "string"
}
]

Accounts

Add Account

Add single account to Lucinity. The same API can be used to update accounts as well. The 'ID' property derived from BaseEntity usually maps to the uniquely identifiable record. Lucinity ingests input and emits the same account object for reference.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Account JSON passed in request body.

id required	string Primary identifier for the entity. If the entity type is transaction, it should be unique and consistent across entries.
dataSource	string An identifier that represents the system from which the record is originated.
	Array of objects (Reference) Reference attribute
ingestDate	string <date-time> Date time for when the object was ingested
	object (Classification) Deprecated Reference attribute
	object (AccessClassification) Deprecated Reference attribute
	object (Metadata) Reference attribute
accountType	string (AccountType) Enum: "CURRENT" "SAVINGS" "MONEY_MARKET" "TERM_DEPOSIT" "LOAN" "CREDIT_CARD" "TRADING" "HELD_IN_CUSTODY" "CASH_ON_DELIVERY" "BOTH_HIC_AND_COD" Enumeration values for the type of account.
subType	string Enum: "PERSONAL" "BUSINESS" Subtype of the account
status	string Enum: "ACTIVE" "CLOSED" "TERMINATED" "NO_TRADING" Status of the account
monitored	string Enum: "YES" "NO" Is the Account monitored? EXPERIMENTAL: This field does not have any affect on Lucinity's Behavioral Monitoring or Rule Engine.
accountNumber	string The account number
iban	string The IBAN of the account
productType	string Account Base Product, used for internal reference for products such as loans, etc. Used to display the information in the UI.
currencyCode	string ISO currency of the account
domicile	string The 2 letter ISO 3116-1 Alpha-2 country code.
openedDate	string <date> Date of when account was opened
terminationDate	string <date> Date of when account was terminated
closingBalance	number Balance of account when account was closed
asOfDate required	string <date> The date when this record became valid
bankCode	string Bank code used for the Account
accountAgreementId	string Agreement ID of the account. DEPRECATED.
productId	string Product ID of the account, used for internal reference for products such as loans or other services. Used to link products in the UI.
internal	boolean Indicates that account is owned by the bank
depositable	boolean Indicates that account is depositable
withdrawable	boolean Indicates that account is withdrawable
collateral	boolean Indicates that account is held as collateral
terminated	boolean Indicates that account has been terminated
accountInDefault	boolean Indicates that account is in default or overdraft
accountInDefaultDays	integer Number of days account has been in default or overdraft
	Array of objects (Interest) Indicates the interest of the account has been in default or overdraft
	object (AccountBalance) Account Balance reference
	object (TermDepositFacility) Term Deposit reference
	object (CreditFacility) Credit Facility reference
	object (LoanFacility) Loan facility reference
	object (TradingAccount) Trading Account reference
primaryRepresentativeId	string The id of the primary representative for the account. DEPRECATED.
beneficiaryOwnerId	string The id of the beneficiary owner for the account. DEPRECATED.
name	string The name of the account.
	object (CustomData) The `customData` property can be used to add data in a key, value `<string,string>` format to the objects. This can e.g. be used for display purposes. CustomData will not be used by Lucinity in any processing. Maximum length of this property is 5000 characters.

Responses

Request samples

Payload

Content type

application/json

{"id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
"dataSource": "SWAGGER_API",
"references": [{"id": "7777771-555-4e5a-9ecd-16cb105a6976",
"systemName": "SystemName"
}
],
"ingestDate": "2020-05-03T14:03:41.089Z",
"classification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"business": ["string"
],
"city": ["string"
]
},
"accessClassification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"elevatedPrivilege": ["string"
],
"city": ["string"
]
},
"metadata": {"someProperty": "some value"
},
"accountType": "CURRENT",
"subType": "PERSONAL",
"status": "ACTIVE",
"monitored": "YES",
"accountNumber": "string",
"iban": "string",
"productType": "string",
"currencyCode": "string",
"domicile": "string",
"openedDate": "2019-08-24",
"terminationDate": "2019-08-24",
"closingBalance": 9865,
"asOfDate": "2019-08-24",
"bankCode": "string",
"accountAgreementId": "string",
"productId": "string",
"internal": true,
"depositable": true,
"withdrawable": true,
"collateral": true,
"terminated": true,
"accountInDefault": true,
"accountInDefaultDays": 0,
"interest": [{"interestType": "DEPOSIT",
"interestCode": "string",
"interestForm": "FIXED",
"interestRate": 100000
}
],
"balance": {"depositBalance": 100000,
"depositBalanceLcy": 100000,
"depositDisposableBalance": 100000,
"depositDisposableBalanceLcy": 100000,
"loanBalance": 100000,
"loanBalanceLcy": 100000
},
"termDeposit": {"termDepositType": "NOTICE",
"termDepositPeriod": 0,
"termDepositWithdrawalNotice": true,
"termDepositWithdrawalDate": "2019-08-24"
},
"credit": {"creditType": "CREDIT_CARD",
"creditLimit": 100000,
"creditLimitLcy": 100000,
"creditUnused": 100000,
"creditUnusedLcy": 100000,
"creditIssueDate": "2019-08-24",
"creditFinalDate": "2019-08-24",
"creditCardNumberMasked": "string"
},
"loan": {"loanType": "MORTGAGE",
"loanPrincipal": 1000000,
"loanPrincipalLcy": 100000,
"loanInstallment": 100000,
"loanSecured": true,
"loanPeriodRemaining": 0,
"loanIssueDate": "2019-08-24",
"loanFinalDate": "2019-08-24"
},
"brokerage": {"regulatoryExemptionType": "string",
"settlementInstruction": "string",
"isGiveIn": true,
"isGiveUp": true,
"isWhiteLabel": true,
"isDmaBroker": true,
"isCareBroker": true,
"locateByPass": true,
"shortName": "string",
"primaryDesk": "string",
"aggUnit": "string",
"isFiduciary": true,
"isErisa": "YES",
"is1940ActAccount": "YES",
"tradingDesk": "string",
"brokerName": "string",
"brokerId": "string",
"brokerLocation": "string",
"region": "LN, HK"
},
"primaryRepresentativeId": "string",
"beneficiaryOwnerId": "string",
"name": "Mez's account",
"customData": {"someProperty": "some value",
"otherProperty": "other value"
}
}

Response samples

Content type

application/json

{"id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
"dataSource": "SWAGGER_API",
"references": [{"id": "7777771-555-4e5a-9ecd-16cb105a6976",
"systemName": "SystemName"
}
],
"ingestDate": "2020-05-03T14:03:41.089Z",
"classification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"business": ["string"
],
"city": ["string"
]
},
"accessClassification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"elevatedPrivilege": ["string"
],
"city": ["string"
]
},
"metadata": {"someProperty": "some value"
},
"accountType": "CURRENT",
"subType": "PERSONAL",
"status": "ACTIVE",
"monitored": "YES",
"accountNumber": "string",
"iban": "string",
"productType": "string",
"currencyCode": "string",
"domicile": "string",
"openedDate": "2019-08-24",
"terminationDate": "2019-08-24",
"closingBalance": 9865,
"asOfDate": "2019-08-24",
"bankCode": "string",
"accountAgreementId": "string",
"productId": "string",
"internal": true,
"depositable": true,
"withdrawable": true,
"collateral": true,
"terminated": true,
"accountInDefault": true,
"accountInDefaultDays": 0,
"interest": [{"interestType": "DEPOSIT",
"interestCode": "string",
"interestForm": "FIXED",
"interestRate": 100000
}
],
"balance": {"depositBalance": 100000,
"depositBalanceLcy": 100000,
"depositDisposableBalance": 100000,
"depositDisposableBalanceLcy": 100000,
"loanBalance": 100000,
"loanBalanceLcy": 100000
},
"termDeposit": {"termDepositType": "NOTICE",
"termDepositPeriod": 0,
"termDepositWithdrawalNotice": true,
"termDepositWithdrawalDate": "2019-08-24"
},
"credit": {"creditType": "CREDIT_CARD",
"creditLimit": 100000,
"creditLimitLcy": 100000,
"creditUnused": 100000,
"creditUnusedLcy": 100000,
"creditIssueDate": "2019-08-24",
"creditFinalDate": "2019-08-24",
"creditCardNumberMasked": "string"
},
"loan": {"loanType": "MORTGAGE",
"loanPrincipal": 1000000,
"loanPrincipalLcy": 100000,
"loanInstallment": 100000,
"loanSecured": true,
"loanPeriodRemaining": 0,
"loanIssueDate": "2019-08-24",
"loanFinalDate": "2019-08-24"
},
"brokerage": {"regulatoryExemptionType": "string",
"settlementInstruction": "string",
"isGiveIn": true,
"isGiveUp": true,
"isWhiteLabel": true,
"isDmaBroker": true,
"isCareBroker": true,
"locateByPass": true,
"shortName": "string",
"primaryDesk": "string",
"aggUnit": "string",
"isFiduciary": true,
"isErisa": "YES",
"is1940ActAccount": "YES",
"tradingDesk": "string",
"brokerName": "string",
"brokerId": "string",
"brokerLocation": "string",
"region": "LN, HK"
},
"primaryRepresentativeId": "string",
"beneficiaryOwnerId": "string",
"name": "Mez's account",
"customData": {"someProperty": "some value",
"otherProperty": "other value"
}
}

Add Account Balance

Add balance for an account.

Authorizations:

ApiKeyAuth

path Parameters

required

string

The account id.

Request Body schema: application/json

A balance for the account

asOfDate	string <date> The date when this record became valid
currency required	string/[A-Z]{3}/ ISO currency of the balance
current required	number The balance on the account at the end of day
available	number The available balance on the account at the end of day
type	string (BalanceType) Value: "CLOSING" The type of balance, e.g. CLOSING indicating EOD balance

Responses

Request samples

Payload

Content type

application/json

{"asOfDate": "2019-08-24",
"currency": "USD",
"current": 5000,
"available": 4000,
"type": "CLOSING"
}

Response samples

Content type

application/json

{"accountId": "ACC0001",
"internalId": "a083f3a8-f055-4252-a22d-ed476ca082ed",
"ingestDate": "2019-08-24T14:15:22Z",
"asOfDate": "2019-08-24",
"currency": "USD",
"current": 5000,
"available": 4000,
"type": "CLOSING"
}

Add Actor to Account

Add actor to account by ID. This provides association between the two entities.

Authorizations:

ApiKeyAuth

path Parameters

required

string

The account id to add the actors.

Request Body schema: application/json

The Actor (single or multiple) object that needs to be associated to the account

	Array of objects List of the actors associated with account and their role
asOfDate	string <date> The date when this record became valid

Responses

Request samples

Payload

Content type

application/json

{"actors": [{"id": "string",
"role": "OWNER"
}
],
"asOfDate": "2019-08-24"
}

Response samples

Content type

application/json

{"actors": [{"id": "string",
"role": "OWNER"
}
],
"asOfDate": "2019-08-24"
}

Transactions

Add Transaction Deprecated

Add transaction to Lucinity.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

Transaction object to be added.

id required	string Primary identifier for the entity. If the entity type is transaction, it should be unique and consistent across entries.
dataSource	string An identifier that represents the system from which the record is originated.
	Array of objects (Reference) Reference attribute
ingestDate	string <date-time> Date time for when the object was ingested
	object (Classification) Deprecated Reference attribute
	object (AccessClassification) Deprecated Reference attribute
	object (Metadata) Metadata describing the object. This field is not intended to add additional information to the object, rather add information about the object's attributes. Reserved Metadata Keywords: `exclude_from_monitoring`: When set to `"true"`, this keyword excludes the transaction from Lucinity's Behavioral Monitoring, Rule Engine, and Actor Intelligence. Excluded transactions will only be used for display but not in any calculations or graphs. If this keyword is missing or set to `"false"`, the transaction is included.
activityDate required	string <date-time> The date and time of the activity
	Array of objects (geoTag) An array of all relevant geoTags for the activity.
required	Array of objects (Participant) An array of actors that participate in the transaction. If the entity type is transaction and the intended use is for AML detection or Transaction Monitoring, this array should only include the focal actor as the owner of the transaction. (The counterparty is defined in the counterparty object.)
	Array of objects (IpAddress) An array of all relevant ip addresses for the activity.
status	string (TransactionStatus) Enum: "COMPLETE" "PENDING" "VOID" "FAILED" Reference attribute
currency	string = 3 characters The ISO 4217 currency code of the transaction.
entryDate	string <date-time> The timestamp of the transaction. Should be the same as `activityDate`.
channel	string (ChannelType) Enum: "BRANCH" "ONLINE" "ATM" "POS" "MOBILE" "UNKNOWN" Reference attribute
accountId	string The Account `id` the focal actor used in the transaction.
amountLcy	number Amount converted to the local currency of the financial institution. Important: Use positive amount if the direction is inflowing from the perspective of the Focal Actor, or a negative amount if the direction is outflowing. Example: 3000 (inflowing transaction) or -4000 (outflowing transaction).
amount	number Amount in the currency stated (in the `currency` field) for this transaction. Important: Use positive amount if the direction is inflowing from the perspective of the Focal Actor, or a negative amount if the direction is outflowing. Example: 3000 (inflowing transaction) or -4000 (outflowing transaction).
valueDate	string <date-time> Effective interest date
bookingDate	string <date-time> The datetime the transaction is booked
description	string Free text area, used by the Actor initiating the transaction.
cardNumber	string Card Number
balance	number Balance of the account after the transaction has taken place. Uses the currency of the account, not necessarily of the transaction.
channelLocation	string The unique identifier for the channel location associated with the transaction. Has to match a location code ingested through /ChannelLocations.
checkNumber	string If the transaction's `TransactionMethod` field is CHECK, this field should contain the associated check number.
method	string (TransactionMethod) Enum: "FEE" "INTEREST" "CASH" "CHECK" "PAYMENT" "DIRECT_DEBIT" "STANDING_ORDER" "TRANSFER" "REVERSAL" "CORRECTION" "OTHER" "PREPAID" "CLOSED" "CARD" Reference attribute
categoryPrimary	string The primary category type
categorySecondary	string The secondary category type
internationalTransaction	boolean Indicates if the transaction is an international transaction
	object (Counterparty) Counterparty of a transaction: the entity with which the Focal Actor transacts with.

Responses

Request samples

Payload

Content type

application/json

{"id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
"dataSource": "SWAGGER_API",
"references": [{"id": "7777771-555-4e5a-9ecd-16cb105a6976",
"systemName": "SystemName"
}
],
"ingestDate": "2020-05-03T14:03:41.089Z",
"classification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"business": ["string"
],
"city": ["string"
]
},
"accessClassification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"elevatedPrivilege": ["string"
],
"city": ["string"
]
},
"metadata": {"someProperty": "some value"
},
"activityDate": "2019-08-24T14:15:22Z",
"geoTags": [{"latitude": "string",
"longitude": "string"
}
],
"participants": [{"role": "OWNER",
"id": "string",
"tags": ["string"
],
"type": "ACTOR",
"actorId": "string"
}
],
"ipAddresses": [{"address": "10.0.0.15",
"type": "IPV4",
"description": "Internet Protocol version 4 (IPv4) is the fourth version of the Internet Protocol (IP)."
}
],
"status": "COMPLETE",
"currency": "str",
"entryDate": "2020-05-03T14:03:41.089Z",
"channel": "BRANCH",
"accountId": "string",
"amountLcy": 100000,
"amount": 100000,
"valueDate": "2020-05-03T14:03:41.089Z",
"bookingDate": "2020-05-03T14:03:41.089Z",
"description": "string",
"cardNumber": "string",
"balance": 100000,
"channelLocation": "2828ATM",
"checkNumber": "string",
"method": "FEE",
"categoryPrimary": "string",
"categorySecondary": "string",
"internationalTransaction": true,
"counterparty": {"id": "string",
"type": "string",
"name": "string",
"address": "string",
"bankName": "string",
"bic": "string",
"bankCode": "string",
"accountNumber": "string",
"iban": "string",
"country": "string",
"industry.code": "string",
"industry.type": "string",
"actorId": "string"
}
}

Response samples

Content type

application/json

{"id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
"dataSource": "SWAGGER_API",
"references": [{"id": "7777771-555-4e5a-9ecd-16cb105a6976",
"systemName": "SystemName"
}
],
"ingestDate": "2020-05-03T14:03:41.089Z",
"classification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"business": ["string"
],
"city": ["string"
]
},
"accessClassification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"elevatedPrivilege": ["string"
],
"city": ["string"
]
},
"metadata": {"someProperty": "some value"
},
"activityDate": "2019-08-24T14:15:22Z",
"geoTags": [{"latitude": "string",
"longitude": "string"
}
],
"participants": [{"role": "OWNER",
"id": "string",
"tags": ["string"
],
"type": "ACTOR",
"actorId": "string"
}
],
"ipAddresses": [{"address": "10.0.0.15",
"type": "IPV4",
"description": "Internet Protocol version 4 (IPv4) is the fourth version of the Internet Protocol (IP)."
}
],
"status": "COMPLETE",
"currency": "str",
"entryDate": "2020-05-03T14:03:41.089Z",
"channel": "BRANCH",
"accountId": "string",
"amountLcy": 100000,
"amount": 100000,
"valueDate": "2020-05-03T14:03:41.089Z",
"bookingDate": "2020-05-03T14:03:41.089Z",
"description": "string",
"cardNumber": "string",
"balance": 100000,
"channelLocation": "2828ATM",
"checkNumber": "string",
"method": "FEE",
"categoryPrimary": "string",
"categorySecondary": "string",
"internationalTransaction": true,
"counterparty": {"id": "string",
"type": "string",
"name": "string",
"address": "string",
"bankName": "string",
"bic": "string",
"bankCode": "string",
"accountNumber": "string",
"iban": "string",
"country": "string",
"industry.code": "string",
"industry.type": "string",
"actorId": "string"
}
}

Transactions V2

Create a transaction

Authorizations:

ApiKeyAuth

query Parameters

blocking	string If the screening process is synchronous or asynchronous, currently `blocking=true` is only supported and MUST be set. `example: blocking=true`
operations	string Comma-seperated list of what kind of screening the transaction should return. Supported values FRAUD and SANCTIONS. example: `operations=FRAUD,SANCTIONS`

header Parameters

idempotency-key

string

Example: 96760494-8c70-4279-a7c3-0d11e3c9aa6c

Unique value generated by the client which the resource server uses to recognize subsequent retries of the same request

Request Body schema: application/json

id required	string Primary identifier for the transaction.
created_at required	number The timestamp of when the transaction occurred. Measured in seconds in unix epoch timestamp.
direction required	string Enum: "INBOUND" "OUTBOUND" The direction of a transaction is `OUTBOUND` when funds are sent from the account holder, and `INBOUND` when funds are received by the account holder.
status required	string Enum: "COMPLETED" "PENDING" "CANCELLED" "FAILED" Status or condition of the transaction. Only `COMPLETED` transactions will be included in the Lucinity's Behavioral Monitoring and Rule Engine. Possible values: `COMPLETED` The transaction took place and will be included in Lucinity's Behavioral Monitoring and Rule Engine. `PENDING` The transaction has not yet been fully processed by the merchant. `CANCELLED` The transaction was cancelled or voided before it was settled. `FAILED` The transaction failed to be settled.
description	string Description of the transaction
channel	string Enum: "BRANCH" "ONLINE" "ATM" "POS" "UNKNOWN" The type of channel that was used to initiate the transaction. If this property is not provided it will default to `UNKNOWN`. `BRANCH` Represents a transaction initiated through a physical branch location of the financial institution, where the customer interacts with a bank representative in person. `ONLINE` Represents a transaction initiated through an online channel, typically through a web-based platform or internet banking service provided by the financial institution. `ATM` Represents a transaction initiated through an Automated Teller Machine (ATM). `POS` Represents a transaction initiated through a Point of Sale (POS) system, typically used in retail environments. `UNKNOWN` The channel used to initiate the transaction is unknown or not specified. It can be used when the specific channel information is not available or not applicable.
account_id required	string Primary identifier of the account.
account_owner_id required	string Primary identifier of the owner of the account.
user_name	string User name of the entity performing the transaction.
user_id	string User id of the entity performing the transaction.
required	object (Amount) Amount and currency code of the transaction that occured.
standardized_amount required	number Value of the transaction in the default currency configured in the Lucinity platform.
account_balance	number The current, settled balance of the account in the currency of the account.
method	string Enum: "CARD" "CASH" "CHECK" "VIRTUAL" "WIRE_TRANSFER" Method of the transaction `CARD` A card was used as the payment method for this transaction. `CASH` The transaction involved the use of physical currency. `CHECK` A paper check was used for the transaction. `VIRTUAL` The transaction utilized a virtual currency or digital payment method. `WIRE_TRANSFER` The transaction involved the transfer of funds between bank accounts. Either `Method` or `Purpose` should be set for transaction monitoring to work as intended
purpose	string Enum: "BILL_PAYMENT" "INTRA_ACTOR" "FEE" "PRINCIPAL_PAYMENT" "INTEREST_PAYMENT" "REVERSE" "REFUND" "CHARGEBACK" "CLOSING" purpose of the transaction. `BILL_PAYMENT` Payment of a bill. `INTRA_ACTOR` Movement of funds between internal accounts of the same actor within the clients eco-system. `FEE` Fee charged for a service or transaction. `PRINCIPAL_PAYMENT` Payment of the principal amount owed. `INTEREST_PAYMENT` Payment of accrued interest. `REVERSE` Reversal or cancellation of a previous transaction. `REFUND` Refunding a previous payment. `CHARGEBACK` Chargeback, initiated to reverse a previous payment made by a cardholder. `CLOSING` Closure or finalization of an account or financial arrangement. Either `Method` or `Purpose` should be set for transaction monitoring to work as intended
required	any Enum: "EMPTY" "INDIVIDUAL" "ACCOUNT_INFO" "LEGAL_ENTITY" "NAMED_ENTITY" Counterparty represents the creditor or debtor involved in the transaction and can be one of the following: `EMPTY` Indicates that there is no counterparty for the transaction. `INDIVIDUAL` Represents an individual counterparty, referring to an individual person involved in the transaction. `ACCOUNT_INFO` Represents a counterparty identified by account information, providing details such as bank name, account number, etc. `LEGAL_ENTITY` Represents a legal entity counterparty, referring to a legal entity involved in the transaction. `NAMED_ENTITY` Represents a entity counterparty, referring to a entity involved in the transaction where it's unknown if it's a legal entity or an individual.
	object (schemas-Metadata) Metadata describing the object. This field is not intended to add additional information to the object, rather add information about the object's attributes. Reserved Metadata Keywords: `exclude_from_monitoring`: When set to `"true"`, this keyword excludes the transaction from Lucinity's Behavioral Monitoring, Rule Engine, and Actor Intelligence. Excluded transactions will only be used for display but not in any calculations or graphs. If this keyword is missing or set to `"false"`, the transaction is included. `international`: When set to `"true"` this transaction is marked as an international transaction, `"false"` when it is a domestic transaction. This needs to be set for transaction monitoring to work as intended. `data_source`: An identifier that represents the system from which the record is originated.
	object (schemas-CustomData) The `custom_data` property can be used to add data in a key, value `<string,string>` format to the objects. This can e.g. be used for display purposes. `custom_data` will not be used by Lucinity in any processing. Maximum length of this property is 5000 characters.
	object (Device) Device section contains information on the device which the transaction was performed on.

Responses

Request samples

Payload

Content type

application/json

Example

A transaction where counterparty object is an individual

{"id": "1b9c926d-52d1-4c2f-bc1d-8a1d8f9d5e89",
"created_at": 1654236000,
"direction": "OUTBOUND",
"status": "COMPLETED",
"description": "Payment for goods",
"channel": "ONLINE",
"account_id": "5f1bcb7e-7e39-42e0-9d4c-d10be236cd28",
"amount": {"value": 100.15,
"currency": "USD"
},
"standardized_amount": 200.25,
"account_balance": 500.25,
"account_owner_id": "1deb5316-cd35-4fe9-bce9-08a8bd3933b1",
"method": "CARD",
"purpose": "BILL_PAYMENT",
"metadata": {"international": "true",
"exclude_from_monitoring": "true"
},
"device": {"id": "123e4567-e89b-12d3-a456-426614174000",
"ip_address": "2001:db8:85a3::8a2e:370:7334"
},
"counterparty": {"object": "INDIVIDUAL",
"id": "fa9e7f3c-9b62-45c2-bb64-9a8e06e366be",
"name": "John Doe",
"birth_date": "1985-10-15",
"postal_addresses": [{"lines": ["123 Main Street"
],
"postal_code": "12345",
"city": "Cityville",
"state": "Stateville",
"country": "USA",
"location": "HOME"
}
],
"account_info": {"bank_name": "Bank of America",
"bic": "BOFAUS3N",
"bank_code": "123456",
"account_number": "1234567890",
"iban": "US1234567890"
},
"industry": {"classification_identifier": "MCC",
"code": "1234"
},
"metadata": {"identifiable_as_actor": "false"
}
}
}

Response samples

Content type

application/json

Example

Transaction with no hit

{"transaction_id": "1b9c926d-52d1-4c2f-bc1d-8a1d8f9d5e89",
"request_id": "ccb3f54c-4aa2-47cf-8a0b-c1b34a43a520",
"screening_results": [{"provider_name": "SEON",
"response": "MISS"
},
{"provider_name": "NETERIUM",
"response": "MISS"
}
]
}

Cases

Cases are one of the fundamental features in Lucinity. Cases can be created through the API and associated with observations.

Create a new Case

Create a new Case in the Lucinity platform. The Case will be created with the provided details.

Authorizations:

BearerToken

Request Body schema: application/json

focal_actor_id	string The actor id of the focal actor of the case
observation_ids	Array of strings List of ids for observations that are part of the case
	object (schemas-Metadata) Metadata describing the object. This field is not intended to add additional information to the object, rather add information about the object's attributes. Reserved Metadata Keywords: `external_reference_id`: An identifier that represents the case in the an external system. For instance if an investigation is being tracked in external system. `data_source`: An identifier that represents the system from which the record is originated. `legacy_workflow_id`: Providing the legacy_workflow_id can be used to override the workflow assignment for the case. Warning! This should only be used if user knows exact id of the workflow intended to be used for the case. If the id is not valid, the case might be created but not visible.

Responses

Request samples

Payload

Content type

application/json

{"focal_actor_id": "2928938-29892-92983-923892839",
"observation_ids": ["929298-2929110-11-292-1212"
],
"metadata": {"some_property": "some_value"
}
}

Response samples

Content type

application/json

{"case_id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74"
}

Actor Intelligence

You don’t need to rely solely on static and self-reported KYC to determine your customers’ compliance risk.

With Actor Intelligence, you can sleep easy knowing that your customer risk scores are automatically and continuously updated—based on their actual behavior.

Add Actor Extended Information

Add actor extended information.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Actor ID

Request Body schema: application/json

Summary information on balances, number of products the actor has with the institution and dates when products were acquired

depositsTotalBalanceLcy	number Total balance of deposits
depositsFixedTermBalanceLcy	number The total position of fixed deposits
depositsAvailableBalanceLcy	number Total balance of deposits
loansBalanceLcy	number Total balance of loans
loansPrincipalLcy	number Loan total original value, converted to LCY
loansOverdraftLcy	number Overdraft total balance, converted to LCY
loansCreditLimitLcy	number Total credit limit for loans
securitiesBalanceLcy	number Total balance for securities
derivativesBalanceLcy	number Total balance for derivatives
numberOfBankAccounts	number Number of bank accounts the customer has
numberOfDepositAccounts	number Number of deposit accounts the customer has
numberOfCreditCards	number Number of credit cards the customer has
numberOfLoans	number Number of loans the customer has
numberOfSecuritiesPortfolios	number Securities number of portfolios
numberOfDerivativesPortfolios	number Derivatives number of portfolios
firstProductDate	string <date> The first known product that a customer had
lastProductDate	string <date> Last known product by a customer
asOfDate	string <date> The date when this record became valid

Responses

Request samples

Payload

Content type

application/json

{"depositsTotalBalanceLcy": 100000,
"depositsFixedTermBalanceLcy": 100000,
"depositsAvailableBalanceLcy": 100000,
"loansBalanceLcy": 100000,
"loansPrincipalLcy": 100000,
"loansOverdraftLcy": 100000,
"loansCreditLimitLcy": 100000,
"securitiesBalanceLcy": 100000,
"derivativesBalanceLcy": 100000,
"numberOfBankAccounts": 100000,
"numberOfDepositAccounts": 100000,
"numberOfCreditCards": 100000,
"numberOfLoans": 100000,
"numberOfSecuritiesPortfolios": 100000,
"numberOfDerivativesPortfolios": 100000,
"firstProductDate": "2019-08-24",
"lastProductDate": "2019-08-24",
"asOfDate": "2019-08-24"
}

Response samples

Content type

application/json

{"depositsTotalBalanceLcy": 100000,
"depositsFixedTermBalanceLcy": 100000,
"depositsAvailableBalanceLcy": 100000,
"loansBalanceLcy": 100000,
"loansPrincipalLcy": 100000,
"loansOverdraftLcy": 100000,
"loansCreditLimitLcy": 100000,
"securitiesBalanceLcy": 100000,
"derivativesBalanceLcy": 100000,
"numberOfBankAccounts": 100000,
"numberOfDepositAccounts": 100000,
"numberOfCreditCards": 100000,
"numberOfLoans": 100000,
"numberOfSecuritiesPortfolios": 100000,
"numberOfDerivativesPortfolios": 100000,
"firstProductDate": "2019-08-24",
"lastProductDate": "2019-08-24",
"asOfDate": "2019-08-24"
}

InitializeBatch

Initialize a batch. To initialize a Transaction Monitoring batch, set the "processType" parameter to "AML". To initialize an Actor Intelligence batch, set the "processType" parameter to "ACTOR". If when initializing, the specified batch period fails to contain any valid transactions, the API will respond with a 400 error containing the batch details, along with a "NO_TXN" failure reason.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

closeOfBusinessDate required	string <date> Date that denotes the inclusive right bound of the interval of ingested data to be reviewed. All that happened before this date and has previously not been reviewed will be processed. The "asOfDate" for ingested data will be considered for inclusion in the review.
lineOfBusiness required	string Enum: "INDIVIDUAL" "LEGAL_ENTITY" The line of business for detection batch, must always be provided
processType required	string Enum: "AML" "ACTOR" The type of the pipeline to trigger, eg. AML or ACTOR
useOldConfig	boolean If "useOldConfig" is used then config version from the previous successful run will be used. If there is no previous successful run this flag is ignored.

Responses

Request samples

Payload

Content type

application/json

{"closeOfBusinessDate": "2020-02-01",
"lineOfBusiness": "INDIVIDUAL",
"processType": "AML",
"useOldConfig": false
}

Response samples

Content type

application/json

{"closeOfBusinessDate": "2020-02-01",
"lineOfBusiness": "INDIVIDUAL",
"processType": "AML",
"useOldConfig": false
}

Transaction Monitoring

Lucinity empowers your compliance team to not only observe your customers’ activity, but to understand them for who they are.

Transaction monitoring keeps an eye on your customers’ activity through their transaction network and compare their actions to past behavior and peer group activity, ensuring a leading position in compliance.

Detect

Add Source system

Data from multiple internal client systems may be published to the APIs. Defining these source systems enables maintaining lineage of data.

Authorizations:

ApiKeyAuth

Request Body schema: application/json

name required	string This will also serve as the source system id
urlTemplate required	string <url> For URLs to external systems the activity reference id will be used to replace the {itemId} string

Responses

Request samples

Payload

Content type

application/json

{"name": "system",
"urlTemplate": "http://example.com/{itemId}"
}

Response samples

Content type

application/json

{"name": "system",
"urlTemplate": "http://example.com/{itemId}"
}

InitializeBatch

Authorizations:

ApiKeyAuth

Request Body schema: application/json

closeOfBusinessDate required	string <date> Date that denotes the inclusive right bound of the interval of ingested data to be reviewed. All that happened before this date and has previously not been reviewed will be processed. The "asOfDate" for ingested data will be considered for inclusion in the review.
lineOfBusiness required	string Enum: "INDIVIDUAL" "LEGAL_ENTITY" The line of business for detection batch, must always be provided
processType required	string Enum: "AML" "ACTOR" The type of the pipeline to trigger, eg. AML or ACTOR
useOldConfig	boolean If "useOldConfig" is used then config version from the previous successful run will be used. If there is no previous successful run this flag is ignored.

Responses

Request samples

Payload

Content type

application/json

{"closeOfBusinessDate": "2020-02-01",
"lineOfBusiness": "INDIVIDUAL",
"processType": "AML",
"useOldConfig": false
}

Response samples

Content type

application/json

{"closeOfBusinessDate": "2020-02-01",
"lineOfBusiness": "INDIVIDUAL",
"processType": "AML",
"useOldConfig": false
}

Review

Add observation to Lucinity

Add observation To Lucinity. Observations are vital information to deduce signals.

Authorizations:

ApiKeyAuth

query Parameters

create_case

string

Optional parameter, if create_case=true is set, then attempt will be made to create cases using the provided observations. This may result in a different response structure, particularly if a case is successfully created. Currently this option is available for all observation types except ALERT_AML.

Request Body schema: application/json

The observation object to be sent to Lucinity.

One of

type required	string Value: "ALERT_AML" The type of the observation (alert) which controls what kind of data can be associated with the observation.
	object (Submitter) Defines submitter of the case observation. EXPERIMENTAL, not linked to a system id or username.
id required	string Primary identifier for the observation. It should be unique and consistent across entries.
dataSource	string An identifier that represents the system from which the record is originated.
	Array of objects (Reference) Reference attribute
	object (Metadata) Placeholder object that can carry additional information that are not part of the original schema.
	object (Classification) Deprecated Reference attribute
	object (AccessClassification) Deprecated Reference attribute
date required	number Timestamp at which the transaction took place. Measured in seconds since the Unix epoch.
batchId	string The batchId on the surveillance platform which detected the observation
behaviorId required	string Risk / Concern ID with the observation
behaviorName required	string Risk / Concern Description
version	string Optional version for the model, function or rule that was in effect when the Observation was created. Having this version can help explain why this Observation was raised. It can be a number, an arbitray string or an record identifier for specific revision.
behaviorDescription	string Behavior description
taxonomyDescription	string Higher level of Risk / Concern. Control to which the risk is mapped
priority	string This property is important for real-time detection where a transaction might raise an observation that needs to be reviewed quickly because if the observation is a false positive, the backend systems would want to process the transaction as soon as possible.
btlFlag	boolean (Below The Line) True or false, depending on the threshold setting of the surveillance system on the observation. Eg. If there is confidence threshold that is associated with a surveillance as 80% and exception confidence is 78%, but still gets raised as an exception, BTL would be true. If above cutoff, BTL is false.
score	number [ 0 .. 1 ] The confidence of the detection system on a scale of 0 to 1. 0 or 1 for rules-based systems.
rank	number Risk Ranking of this observation in a homogenous group of such observations.
rule	Array of strings A list of rules triggering the observation.
decisionTree	Array of strings Brief summary of surveillance logic that triggered an exception
businessDateEnd	string <date-time> Timestamp for the end of the the surveillance period
businessDateStart	string <date-time> Timestamp for the start of the the surveillance period
detectionDate	string <date-time> Timestamp for when the exception was discovered by the publishing system
businessDate	string <date> Date when activity/activities occured
label	string Observation label
associatedLegalEntity	Array of arrays
programGroup	string
	object (CustomData) The `customData` property can be used to add data in a key, value `<string,string>` format to the objects. This can e.g. be used for display purposes. CustomData will not be used by Lucinity in any processing. Maximum length of this property is 5000 characters.

Responses

Request samples

Payload

Content type

application/json

Example

AmlObservation

{"type": "ALERT_AML",
"submitter": {"id": "string",
"displayName": "string",
"username": "string"
},
"id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
"dataSource": "SWAGGER_API",
"references": [{"id": "7777771-555-4e5a-9ecd-16cb105a6976",
"systemName": "SystemName"
}
],
"metadata": {"someProperty": "some value"
},
"classification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"business": ["string"
],
"city": ["string"
]
},
"accessClassification": {"domain": ["string"
],
"region": ["string"
],
"country": ["string"
],
"group": ["string"
],
"department": ["string"
],
"elevatedPrivilege": ["string"
],
"city": ["string"
]
},
"date": 1654236000,
"batchId": "string",
"behaviorId": "string",
"behaviorName": "string",
"version": "string",
"behaviorDescription": "string",
"taxonomyDescription": "string",
"priority": "string",
"btlFlag": false,
"score": 0.88,
"rank": 100000,
"rule": ["string"
],
"decisionTree": ["string"
],
"businessDateEnd": "2020-05-03T14:03:41.089Z",
"businessDateStart": "2020-05-03T14:03:41.089Z",
"detectionDate": "2020-05-03T14:03:41.089Z",
"businessDate": "2020-05-03",
"label": "string",
"associatedLegalEntity": [ ],
"programGroup": "string",
"customData": {"someProperty": "some value",
"otherProperty": "other value"
}
}

Response samples

Content type

application/json

Example

CaseCreationResponse

{"caseIds": ["CLC2024030400001378"
],
"observationFailedFinalization": [{"observationId": "string",
"missingReferences": [{"id": "string",
"type": "string"
}
]
}
]
}

Add Actors to Observation

Add actors to observation.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Observation id

Request Body schema: application/json

Actors to be added for a given observation.

Array

actorId required	string An id for an actor that is to be reviewed as part of the observation.
primary	boolean Specify whether the actor id belongs to the primary actor of the observation. Defaults to False.

Responses

Request samples

Payload

Content type

application/json

[{"actorId": "LUCINITY_ACTOR_ID_89012730812411",
"primary": true
}
]

Response samples

Content type

application/json

{"status": "success"
}

Add Activities to Observation

Add activities to observation.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Observation id

Request Body schema: application/json

Activities to be added for a given id.

Array

activityId	string The activityId on the platform which detected the observation.
activityType	string Describes the type of activity used in the ObservationActivities.

Responses

Request samples

Payload

Content type

application/json

[{"activityId": "string",
"activityType": "string"
}
]

Response samples

Content type

application/json

[{"activityId": "string",
"activityType": "string"
}
]

Finalize an Observation

Call when the observation is fully created. This operation validates all the data associated with the observation.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Observation id

Responses

Response samples

Content type

application/json

"string"

Finalize all Observations in Batch

Call when all observations in a batch are fully created. This operation validates all the data associated with the observations.

Authorizations:

ApiKeyAuth

path Parameters

required

string

Batch id

query Parameters

atomic

boolean

Example: atomic=true

When true the batch will be finalized if all observations pass verification of references. When false, observations with missing references are returned as well as the list of caseIds created.

Responses

Response samples

Content type

application/json

{"caseIds": ["CLC2021020400000000",
"CLC2021020400000001"
],
"observationFailedFinalization": [{"observationId": "654681551632065",
"missingReferences": [{"id": "757577483749892394",
"type": "ACTOR"
},
{"id": "363598483565265356",
"type": "TRANSACTION"
}
]
},
{"observationId": "226569451111500",
"missingReferences": [{"id": "141457524124",
"type": "ACTOR"
}
]
}
]
}

Webhooks

Webhooks serve as automated messages sent from one system to another in real-time. Rather than requiring you to constantly request updates from another service (known as "polling"), webhooks work by sending an immediate HTTP POST request to a designated URL—known as the "webhook endpoint"—when a specific event happens.

This means your application can instantly react to events in other systems, making your development process more efficient, scalable, and responsive. You simply configure the endpoint URL in the service sending the event, and then your system will receive real-time updates automatically.

In summary, webhooks offer a straightforward way to enhance your applications through real-time, event-driven communication between services.

Webhook

List registered webhooks

List registered webhooks.

Authorizations:

BearerToken

Responses

Response samples

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
],
"id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
"status": "ACTIVE",
"secret": "%D^u~k:pc<y9Hv",
"created": 1692294086682,
"tenant": "lucinity"
}

Create and register a new Webhook

Authorizations:

BearerToken

Request Body schema: application/json

name required	string The name of the Webhook given by the Webhook creator
url required	string <uri> The target URL for the Webhooks. Typically an endpoint in the customer API that can accept the Lucinity events
events required	Array of strings List of events to subscribe to. If '*' all events will be delivered. If empty, the Webhook will be disabled.

Responses

Request samples

Payload

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
]
}

Response samples

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
],
"id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
"status": "ACTIVE",
"secret": "%D^u~k:pc<y9Hv",
"created": 1692294086682,
"tenant": "lucinity"
}

Retrieve a Webhook by Id

Authorizations:

BearerToken

path Parameters

required

string

Unique Webhook Id

Responses

Response samples

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
],
"id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
"status": "ACTIVE",
"created": 1692294086682,
"tenant": "lucinity"
}

Remove a Webhook by Id

Authorizations:

BearerToken

path Parameters

required

string <uuid>

Unique Webhook Id

Responses

Response samples

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
],
"id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
"status": "ACTIVE",
"created": 1692294086682,
"tenant": "lucinity"
}

Update Webhook

Authorizations:

BearerToken

path Parameters

required

string <uuid>

Unique Webhook Id

Request Body schema: application/json

The status update object. If omitted it will attempt to toggle the status.

name	string The name of the Webhook given by the Webhook creator
url	string <uri> The target URL for the Webhooks. Typically an endpoint in the customer API that can accept the Lucinity events
events	Array of strings List of events to subscribe to. If '*' all events will be delivered. If empty, the Webhook will be disabled.
status	string (WebhookStatus) Enum: "ACTIVE" "INACTIVE"

Responses

Request samples

Payload

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
],
"status": "ACTIVE"
}

Response samples

Content type

application/json

{"name": "My Webhook for handling claimed cases",
"url": "https://my-company.com/api/webhooks/myhook",
"events": ["case.assigned"
],
"id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
"status": "ACTIVE",
"secret": "%D^u~k:pc<y9Hv",
"created": 1692294086682,
"tenant": "lucinity"
}

Test a Webhook

Authorizations:

BearerToken

path Parameters

required

string <uuid>

Unique Webhook Id

Responses

Case Events

Case Assigned Webhook

Request Body schema: application/json

Information about an event in the systems

id	string The id for the event created by Lucinity
name	string Value: "case.assigned" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detail event data for case claimed

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.assigned",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"assignedToUserId": "846d5c88-5296-4972-92bf-cf43730a4184",
"assignedToUserEmail": "string",
"metadata": {"exampleProperty": "example value"
}
}
}

Case Closed Webhook

Request Body schema: application/json

Information about an event in the systems

id	string The id for the event created by Lucinity
name	string Value: "case.closed" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detail event data for case case closed

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.closed",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"resolution": "Suspicious",
"dispositionNarrative": "Summary of the Investigation",
"comment": "This is a comment",
"closeReason": "Manual",
"metadata": {"exampleProperty": "example value"
}
}
}

Case Created Webhook

Request Body schema: application/json

Information about an event in the systems

id	string The id for the event created by Lucinity
name	string Value: "case.created" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detail event data for case case created

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.created",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"processId": "2df50b47-20cc-4b19-b9b5-68eb4bd68620",
"metadata": {"exampleProperty": "example value"
}
}
}

Case Workflow Action Performed Webhook

Request Body schema: application/json

Information about an event in the systems

id	string The id for the event created by Lucinity
name	string Value: "case.workflow.actioned" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detailed event data for when an action on a workflow is performed in a case.

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.workflow.actioned",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"actionName": "SET_ON_HOLD",
"comment": "Setting this case on hold, waiting for external data.",
"metadata": {"exampleProperty": "example value"
}
}
}

Commented on a case event Webhook

Request Body schema: application/json

Information about a comment event in the systems

id	string The id for the event created by Lucinity
name	string Value: "case.commented" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detailed event data for when a comment is added to a case

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.commented",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"comment": "This is a comment",
"metadata": {"exampleProperty": "example value"
}
}
}

Transaction Decision Update Event Webhook

Request Body schema: application/json

Information about an event in the systems

id	string The id for the event created by Lucinity
name	string Value: "case.transaction.decision.updated" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detail event data for transaction decision update

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.transaction.decision.updated",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"decision": "RELEASE"
}
}

Case Observation Feedback Updated Webhook

Request Body schema: application/json

Information about an event in the system

id	string The id for the event created by Lucinity
name	string Value: "case.observations.feedback.updated" The type of the event
createdAt	integer <int64> The timestamp this event was created
	object Detail event data for observation added

Responses

Request samples

Payload

Content type

application/json

{"id": "1",
"name": "case.observations.feedback.updated",
"createdAt": 1711360775327,
"data": {"id": "CLC2020010100000001",
"userId": "95dc44d7-a615-41f3-9bf2-2b8093696dc9",
"userEmail": "[email protected]",
"observationId": "cc00jCLAC00001",
"feedback": "string"
}
}

Audit Logs

Tap into the audit logs from the Lucinity Platform to better grasp how your analysts are using the system to further optimize your workflow.

Get audit logs

Get audit logs within certain criteria.

Authorizations:

ApiKeyAuth

query Parameters

startDate required	string <date-time> Example: startDate=2023-11-21T00:00:00 Is in ISO 8601 datetime format and must proceed endDate.
endDate required	string <date-time> Example: endDate=2023-11-21T23:59:59 Is in ISO 8601 datetime format and must be after startDate.
logType	string (AuditLogType) Enum: "ALL" "READ" "UPDATE" The audit log type. If not provided the default is `ALL`
offset	number Number of rows to skip before returning results. Must be a positive number. If not provided the default is `0`
limit	number Maximum number of retrived entries. Must be a positive number not greater than 1000. If not provided the default is `200`
caseId	string Get audit logs for a single case

Responses

Response samples

Content type

application/json

{"offset": 0,
"limit": 200,
"number_of_values": 10,
"values": [{"json_": {"id": "3c16ebce-7e7b-49ef-b815-3d4cf310aad7",
"notes": "Level: 1 to 2",
"action": "VIEW_CASE",
"caseId": "CLC2023112100000000",
"domain": "CaseManager",
"params": ["string"
],
"userIP": "127.0.0.1",
"userId": "1b08d5b4-defc-4385-afc3-87602adabf0c",
"logType": "ALL",
"newValue": "string",
"objectId": "string",
"oldValue": "string",
"envFields": {"localIP": "127.0.0.1",
"podAuditName": "podName"
},
"timestamp": "2023-11-21T00:00:00",
"objectType": "string",
"systemName": "string",
"userAction": "ESCALATE",
"objectField": "string",
"actionResult": "ALLOWED"
},
"timestamp": "2023-11-21T00:00:00"
}
]
}

Observation Reporting

/observations/getFeedback

Authorizations:

ApiKeyAuth

query Parameters

startDate required	string <date-time> Example: startDate=2023-11-21 Is in ISO 8601 date format and must be after startDate.
endDate required	string <date-time> Example: endDate=2023-11-21 Is in ISO 8601 date format and must be after startDate.

Responses

Response samples

Content type

application/json

[{"observationId": "h9af6CLAC00002",
"observationType": "ALERT_AML",
"observationDate": "2021-01-27T01:00:00+00:00",
"feedback": "SUSPICIOUS",
"typology": "Avoiding reporting requirements",
"behaviorId": "ARR_EFT",
"behaviorName": "Electronic transactions designed to avoid reporting requirements",
"lineOfBusiness": "Individual",
"modelScore": 3.5,
"modelThreshold": 3.5,
"caseId": "CASE202301010001",
"createdTime": "2021-01-27T01:00:00+00:00",
"actorId": "h9a96jf8f99999999",
"dataSource": "Lucinity"
}
]

Glossary

Actor

An Actor is a human or a legal entity involved in a banking transaction: the account holder/customer, bank staff facilitating the transaction or bank database/platform, etc. An Actor can be an originator or Beneficiary when it comes to customers.

Alert

An Alert is a review based on underlying red flags that requires analyst attention.

AML Risk

An AML Risk Assessment measures risk exposure. A money laundering risk assessment is an analytical process applied to a business to measure the likelihood or probability that a person (or legal entity) will unwittingly engage in money laundering or financing terrorism. Key Risk Indicator (KRI) is a metric used to measure the likelihood that the combined probability of an event and its consequence will exceed the organization's risk appetite and have a profoundly negative impact on an organization's ability to be successful.

Many of the sanctions currently imposed by banking regulators contain provisions that require improvements in risk management programs for AML and The Office of Foreign Assets Control (OFAC) compliance. The starting point of a strong AML risk assessment program should be an accurate and comprehensive AML / OFAC risk assessment.

AML risk-score

AML Risk-Scoring identifies the areas where business is most vulnerable to money laundering and terrorist financing risks (ML/TF) and helps take the appropriate preventative measures. Risk-Scoring identifies and monitors high-risk countries, products, accounts, and clients from the FI's entire customer base and helps determine the proper level of customer due diligence (CDD) applicable to adhere to regulations, including the revised FATF (Financial Action Task Force) International Standards.

Financial Action Task Force (FATF) is an international policy-making body that sets anti-money laundering standards and counter-terrorist financing measures worldwide.

AML Taxonomies

AML Taxonomies represent the formal structure of classes or types of objects within the AML domain. A taxonomy follows a hierarchic format and provides names for each object in relation to the other object.

Audit

The Audit function of a bank reports to the audit committee of the board of directors (or similar oversight body). Its role is to independently evaluate the risk management and controls of the bank through periodic assessments, including the adequacy of the bank's controls to mitigate the identified risks, the effectiveness of the bank's staff's execution of the controls, the efficacy of the compliance oversight and quality controls and the effectiveness of the training.

Behavior

Behavior is the customer's way of transacting and is lined with historical or expected transactions. During their day-to-day activities, first-line employees may observe unusual or potentially suspicious behavior exhibited by customers. According to policies and procedures, first-line employees are required to be vigilant in their identification, escalation, and reporting of potentially suspicious and or unusual activities.

Behavior Detection

Behaviors Detection replaces the rule-based approach with an actor-based approach. While a rule-based detection uses singular, expertly chosen data points to flag potentially suspicious activities, Behavior Detection considers the actor's context: the actors' past activity, their peer group, their expected transaction prole, and how the data interplays to conclude. Behavior Detection provides insights on why a case is suspicious, rather than putting this burden on investigators.

Behavior Risk

Behavior Risk determines the risks associated with the behavior of the customer. Simply knowing a customer's occupation or the banking products they use does not necessarily add predictive value to a model. More telling is whether the customer's transaction behavior is in line with what would be expected given the stated occupation or how the customer uses a product.

Evidence shows that customers with deeper banking relationships tend to be lower risk, which means customers with a checking account and other products are less likely to be high risk. The number of in-person visits to a bank might also help determine more accurately whether a customer with a checking account posed a high risk, as would his or her transaction behavior—the number and value of cash transactions and any cross-border activity.

Beneficiary

The Beneficiary is the person (or legal entity) who benefits from a transaction, for example, receiving the proceeds of a wire or a payout from an insurance policy.

Case

In a Case, the analyst is looking at the parties, accounts, and transactions involved and any outside parties or transactions that might be relevant. Anti-money laundering (AML) Case Management is the critical step where analysts at financial institutions review suspicious activity. The detection rules in an AML system flag all the transactions that meet specific criteria. Then, analysts review those transactions to determine whether they might be criminal activity. Lastly, it files the SAR directly with the Financial Crimes Enforcement Network (FinCEN).

Case Management

Anti-money laundering (AML) Case Management is the critical step where analysts at financial institutions review suspicious activity. The detection mechanisms in an AML system flag all the transactions that meet specific criteria. Then, analysts review those transactions to determine whether they might be criminal activity. The Case Manager provides a dashboard overview of customer KYC, transaction history, and any investigations undertaken or regulatory filings filed on a customer.

Case Summary

After gathering and organizing evidence and evaluating it, the investigator consistently documents the relevant evidence as a Case Summary that includes all the red flags identified in the case.

Champion Challenger Models

Champion and Challenger Models expose the underlying settings, parameters, and code. Though the system is creating the pipeline for the user, the model development process is not a black box and is editable.

False Positive

A False Positive refers to a hit identified during the screening process as a possible alert. However, when reviewed, it is found not to match a target named on a sanctions list, high-risk profile, or outside of a typical transaction.

Geographic Risk

The Geographic Risk measures the risk exposure by countries. It comprises three financial crime-relevant risk parameters:

Criminal indicators such as corruption indices, political risk maps, countries considered tax havens, countries susceptible to terrorism, etc.
Political factors such as political stability, the rule of law, civil liberties, etc.
The regulatory expectations and requirements of various countries. Based on ML risk perspectives or FATF Mutual Evaluation Reports.

Investigation

An Investigation is a process of obtaining, evaluating, recording, and storing information about an individual or legal entity with whom one is conducting business in response to an alert indicating a possible sanctions violation. Investigations often begin with simple checks before progressing to further analysis, such as account review, customer outreach, and possible escalation to the compliance function.

Knowledge graph

A Knowledge Graph is a semi-structured data model characterized by three components:

a (ground) extensional component (EDB, extensional database), with constructs, namely facts, to represent data in terms of a graph or a generalization thereof;
an intentional component (IDB, intentional database), with reasoning, rules over the facts of the ground extensional component;
a derived extensional component, the reasoning component, produced in the reasoning process, which applies rules on the ground facts reasoning on a knowledge graph concerns the different ways to traverse it while answering queries, reaching all the interlinked involved entities along different paths, possibly requiring the creation of new parts of the graph: creating new knowledge.

Knowledge Graphs have emerged as an essential tool for AML and transaction monitoring. As money laundering involves cash flow relationships between entities, Knowledge Graphs can capture financial transactions. Examples of graph analytics techniques are clustering and label propagation. Clustering enables focus on investigating specific high-risk sectors while simultaneously reducing the focus on low-risk sectors, providing an efficient allocation of analyst resources, and reducing false positives. Label propagation helps find previously unknowable patterns that may have been missed by analysts in the transaction monitoring process, thereby reducing false negatives.

KYC Risk

A KYC Risk rating calculates risk: either posed by a specific customer or an institution faces based on its customer portfolio. Most institutions calculate both of these risk ratings as each of them is equally important.

Poor data quality is the single most significant contributor to the poor performance of customer risk-rating models. Incorrect Know-Your-Customer (KYC) information, missing information on company suppliers, and erroneous business descriptions impair the effectiveness of screening tools and needlessly raise the workload of investigation teams. In many institutions, over half the cases reviewed have been labeled high risk simply due to insufficient data quality.

KYC Sources

The first pillar of a KYC compliance policy is the Customer Identification Program (CIP). CIPs verify the customer's identity using credentials like their name, date of birth, address, social security number, or other documents.

The second pillar of KYC compliance policy is Customer Due Diligence (CDD). CDD is a KYC process in which all of a customer's credentials are collected to verify their identity and evaluate their risk profile.

The third pillar of KYC compliance policy is Continuous Monitoring. Checking a customer once isn't sufficient to ensure security. Understanding a customer's typical account activity and monitoring the activity is necessary to catch irregularities and eliminate risks as they arise.

Narration

The Narration is a well-structured summary of research findings to help analysts analyze cases more efficiently. The Narration includes five essential elements of information – Who? What? When? Where? and Why?

Network Association Risk

Network analytics examines the connections between related entities to better illuminate relationships. Instead of analyzing an individual, subcomponents of the network are reviewed for similarity to known methods of money laundering and atypical customer behavior. Networks are formed by links between customers and related activity. These (sometimes inferred) links can be internal data, such as account transfers or joint ownership, or external data, such as a shared address or common use of the same ATM.

Network analytics complements existing machine learning and fuzzy logic-based approaches that many banks use for AML monitoring. Network statistics can improve the accuracy of customer risk rating or transaction monitoring models. Fuzzy logic-based methods that resolve customer identities can also be enhanced by looking at how closely accounts are connected. In addition to improving the effectiveness of existing techniques, network analytics provides investigators with new capabilities. For example, community detection algorithms can identify customer groups that could indicate criminal behavior.

Noise vs. Signal

The greatest opportunity for application is in the money laundering and terrorist financing transaction monitoring process. Traditional systems detect specific typologies that can be circumvented. Furthermore, the results from these models contain more noise than 'signals of risk' as the net is often cast wide not to miss a potentially suspicious activity.

Observation

An Observation is an element of an institution's anti-money laundering program to identify unusual or suspicious patterns, trends, or outlying transactions that do not fit a typical pattern.

Originator

The Originator is the account holder or, where there is no account, the person (or legal entity) who places the order with the financial institution to perform the wire transfer.

Peer group

Peer Group Analysis, in layperson's terms, is the grouping of like businesses and entities for the purpose of comparison. From this grouping of like entities, various ratios and statistical methodologies can be applied to determine outliers. Once outliers have been isolated, analysis of these outliers is integral to learn more about the entity and its activity. Ultimately, the goal is to learn more about the business sector or determine whether the outlying activity is a consequence of suspicious activity. Once suspicious activity is determined, the associated data can provide a basis for developing behavioral typologies to find other potentially suspicious activity.

PEP Risk

The definition of a politically exposed person (PEP) is an individual with a high-profile political role or who has been entrusted with a prominent public function. They present a higher risk of money laundering or terrorist financing because of their position.

According to FATF's International Standards on Combating Money Laundering and the Financing of Terrorism & Proliferation (2012), there are two types of politically exposed persons (PEPs).

Foreign PEPs: Individuals who are or have been entrusted with prominent public functions by a foreign country (e.g., heads of state or government; senior politicians; senior government, judicial or military officials; senior executives of state-owned corporations, and important political party officials).

Domestic PEPs: Individuals who are or have been entrusted domestically with prominent public functions (e.g., heads of state or government; senior politicians; senior government, judicial or military officials; senior executives of state-owned corporations, and important political party officials).

Product Risk

The Product Risk assessment measures the risk associated with products or services offered to customers. Some products and services offered may have a higher risk assigned, depending on the nature of the product and service, e.g., because they may facilitate anonymity or handling with high volumes of currency.

Reputation Risk

Reputation Risk relates to the potential loss of public confidence in an organization's integrity due to unlawful or unethical business practices, whether accurate or not. A money-laundering scandal could even result in banks' customers stopping doing business with them, thereby impacting the bottom line.

Review Feedback

The Review Feedback is the process of reviewing the information or facts retrieved through the investigation. As per the investigator's research, the alerted case can be closed, escalated for further review, or reported as false positive.

SAR

A Suspicious Activity Report (SAR) is a document that financial institutions, and those associated with their business, must file with the Financial Crimes Enforcement Network (FinCEN) whenever there is a suspected case of money laundering or fraud.

Suspicious Activity

Suspicious Activity refers to irregular or questionable customer behavior or action potentially related to money laundering or other criminal offense or the financing of terrorist activity. It may also refer to a transaction that is inconsistent with a customer's known legitimate business, personal activities, or the expected level of activity for that kind of business or account.

Systemic Risk

Systemic Risk is the disruption to the flow of financial services that is (i) caused by an impairment of all or parts of the financial system, and (ii) has the potential to have serious negative consequences for the real economy.

Workflow (Case)

A Case Management Workflow is a method of managing and processing a case. It breaks down the tasks needed to resolve a case and maps out their execution from beginning to end.

A typical case workflow used in incident management can have the following steps:

The incident report is received.
The incident is evaluated. If false-positive, end workflow. If valid, proceed to step three.
Email or a ticket is sent to the team in charge.
The team deliberates and decides on the incident report.
The team proposes and applies a solution.
If the solution works, the workflow is completed. If it needs further review, go back to step three four.

This type of case management workflow is highly dynamic and depends on many different factors. It relies on the knowledge worker, the data that emerges, and other unpredictable events. It often requires collaboration between team members, and steps might need repetition frequently.