Skip to main content

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, accounts, and transactions.

The seven 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": "qiTgISif4zprgBb5j4hXfp3qhD",
});
.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": "qiTgISif4zprgBb5j4hXfp3qhD",
});
.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": "qiTgISif4zprgBb5j4hXfp3qhD",
  })
  .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/ACC99140294/actors")
  .headers({
    "X-Api-Key": "qiTgISif4zprgBb5j4hXfp3qhD",
  })
  .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/ACC99140294/balances")
  .headers({
    "X-Api-Key": "qiTgISif4zprgBb5j4hXfp3qhD",
  })
  .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": "qiTgISif4zprgBb5j4hXfp3qhD",
  })
  .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/ACT985002241/associates")
  .headers({
    "X-Api-Key": "qiTgISif4zprgBb5j4hXfp3qhD",
  })
  .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/ACT985002241/riskAssessments")
  .headers({
    "X-Api-Key": "qiTgISif4zprgBb5j4hXfp3qhD",
  })
  .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

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": "qiTgISif4zprgBb5j4hXfp3qhD",
})
.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.

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

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

Content type
application/json
{
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "classification": {
    },
  • "accessClassification": {
    },
  • "metadata": {
    },
  • "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": [
    ],
  • "balance": {
    },
  • "termDeposit": {
    },
  • "credit": {
    },
  • "loan": {
    },
  • "brokerage": {
    },
  • "primaryRepresentativeId": "string",
  • "beneficiaryOwnerId": "string",
  • "name": "Mez's account",
  • "customData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "ingestDate": "2020-05-03T14:03:41.089Z",
  • "classification": {
    },
  • "accessClassification": {
    },
  • "metadata": {
    },
  • "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": [
    ],
  • "balance": {
    },
  • "termDeposit": {
    },
  • "credit": {
    },
  • "loan": {
    },
  • "brokerage": {
    },
  • "primaryRepresentativeId": "string",
  • "beneficiaryOwnerId": "string",
  • "name": "Mez's account",
  • "customData": {
    }
}

Add Account Balance

Add balance for an account.

Authorizations:
ApiKeyAuth
path Parameters
id
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

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
id
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

Content type
application/json
{
  • "actors": [
    ],
  • "asOfDate": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "actors": [
    ],
  • "asOfDate": "2019-08-24"
}

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

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

Content type
application/json
Example
{
  • "id": "LUCINITY_ACTOR_ID_0002221233984",
  • "dataSource": "Lucinity",
  • "references": [
    ],
  • "metadata": {
    },
  • "type": "INDIVIDUAL",
  • "subType": [
    ],
  • "gender": "FEMALE",
  • "name": "Wendy Byrde",
  • "displayName": "Wendy Byrde",
  • "firstName": "Wendy",
  • "middleName": null,
  • "lastName": "Byrde",
  • "status": "ACTIVE",
  • "monitored": "YES",
  • "addresses": [
    ],
  • "phones": [
    ],
  • "emails": [],
  • "nationality": "US",
  • "domicile": "US",
  • "taxResidency": "US",
  • "asOfDate": "2023-01-01",
  • "govermentIds": [
    ],
  • "relatedLinks": [],
  • "validationStatus": "VALIDATED",
  • "customData": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "LUCINITY_ACTOR_ID_0002221233984",
  • "name": "Wendy Byrde",
  • "type": "INDIVIDUAL",
  • "emails": [],
  • "gender": "FEMALE",
  • "phones": [
    ],
  • "status": "ACTIVE",
  • "subType": [
    ],
  • "asOfDate": "2023-01-01",
  • "domicile": "US",
  • "lastName": "Byrde",
  • "metadata": {
    },
  • "addresses": [
    ],
  • "firstName": "Wendy",
  • "monitored": "YES",
  • "customData": {
    },
  • "dataSource": "Lucinity",
  • "externalId": "LUCINITY_ACTOR_ID_0002221233984",
  • "ingestDate": "2024-01-26T10:47:17.726442+00:00",
  • "internalId": "7bc4a334-397a-46f9-871c-0b557ba16318",
  • "references": [
    ],
  • "dateOfBirth": "1954-09-12",
  • "displayName": "Wendy Byrde",
  • "legalEntity": {
    },
  • "nationality": "US",
  • "relatedLinks": [],
  • "classification": {
    },
  • "validationStatus": "VALIDATED",
  • "accessClassification": {
    }
}

Add Actor Associates

Add associates to actors by ID.

Authorizations:
ApiKeyAuth
path Parameters
id
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

Content type
application/json
{
  • "actorAssociates": [
    ],
  • "asOfDate": "2023-04-22"
}

Response samples

Content type
application/json
{
  • "actorAssociates": [
    ],
  • "asOfDate": "2023-04-22"
}

Add Actor RiskAssessment

Add actor risk assessment.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Request Body schema: application/json

Risk Assessment to be added for an actor.

Array
asOfDate
string <date>

Date when record came valid

type
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
string

Value of risk assessment

comment
string

reason for risk or related commment

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Transactions

Add Transaction

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

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

Content type
application/json
{
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "classification": {
    },
  • "accessClassification": {
    },
  • "metadata": {
    },
  • "activityDate": "2019-08-24T14:15:22Z",
  • "geoTags": [
    ],
  • "participants": [
    ],
  • "ipAddresses": [
    ],
  • "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": {
    }
}

Response samples

Content type
application/json
{
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "ingestDate": "2020-05-03T14:03:41.089Z",
  • "classification": {
    },
  • "accessClassification": {
    },
  • "metadata": {
    },
  • "activityDate": "2019-08-24T14:15:22Z",
  • "geoTags": [
    ],
  • "participants": [
    ],
  • "ipAddresses": [
    ],
  • "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": {
    }
}

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
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 since the Unix epoch.

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)
standardized_amount
required
number

Value of the transaction in the 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 this 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 this or method should be set for transaction monitoring to work as intended
required
any

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.
object (schemas-CustomData)

Customdata extending the objects. Intended for display purposes.

object (Device)

Device section contains information on the device which the transaction was performed on.

Responses

Request samples

Content type
application/json
Example
{
  • "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": {
    },
  • "standardized_amount": 200.25,
  • "account_balance": 500.25,
  • "account_owner_id": "1deb5316-cd35-4fe9-bce9-08a8bd3933b1",
  • "method": "CARD",
  • "purpose": "BILL_PAYMENT",
  • "metadata": {
    },
  • "device": {
    },
  • "counterparty": {
    }
}

Response samples

Content type
application/json
Example
{
  • "transaction_id": "1b9c926d-52d1-4c2f-bc1d-8a1d8f9d5e89",
  • "request_id": "ccb3f54c-4aa2-47cf-8a0b-c1b34a43a520",
  • "screening_results": [
    ]
}

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
id
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

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

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

Content type
application/json
{}

Response samples

Content type
application/json
{}

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

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. Observation 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. 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
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

object (Classification)
Deprecated

Reference attribute

object (AccessClassification)
Deprecated

Reference attribute

object (Metadata)

Reference attribute

type
string (ObservationType)

Reference attribute

date
required
string <date-time>

Timestamp for when the observation was created in the surveillance system

batchId
string

The batchId on the surveillance platform which detected the observation

behaviorId
required
string

Risk / Concern ID with the observation

behaviorName
string

Risk / Concern Description

behaviorDescription
string

Behavior 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.

taxonomyDescription
string

Higher level of Risk / Concern. Control to which the risk is mapped

rule
Array of strings

A list of rules triggering the observation.

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.

label
string

Observation label

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

object

Defines submitter of the case observation. EXPERIMENTAL, not linked to a system id or username.

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

Content type
application/json
Example
{
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "classification": {
    },
  • "accessClassification": {
    },
  • "metadata": {
    },
  • "type": "ALERT_AML",
  • "date": "2020-05-03T14:03:41.089Z",
  • "batchId": "string",
  • "behaviorId": "string",
  • "behaviorName": "string",
  • "behaviorDescription": "string",
  • "version": "string",
  • "taxonomyDescription": "string",
  • "rule": [
    ],
  • "priority": "string",
  • "btlFlag": false,
  • "score": 0.88,
  • "rank": 100000,
  • "label": "string",
  • "decisionTree": [
    ],
  • "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",
  • "submitter": {
    },
  • "customData": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "ingestDate": "2020-05-03T14:03:41.089Z",
  • "classification": {
    },
  • "accessClassification": {
    },
  • "metadata": {
    },
  • "type": "ALERT_AML",
  • "date": "2020-05-03T14:03:41.089Z",
  • "batchId": "string",
  • "behaviorId": "string",
  • "behaviorName": "string",
  • "behaviorDescription": "string",
  • "version": "string",
  • "taxonomyDescription": "string",
  • "rule": [
    ],
  • "priority": "string",
  • "btlFlag": false,
  • "score": 0.88,
  • "rank": 100000,
  • "feedback": "string",
  • "caseId": "string",
  • "label": "string",
  • "decisionTree": [
    ],
  • "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",
  • "submitterInternalId": "string",
  • "customData": {
    }
}

Add Actors to Observation

Add actors to observation.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Observation id

Request Body schema: application/json

Actors to be added for a given observation.

Array
actorId
string

An id for an actor that is to be reviewed as part of the observation.

primary
boolean

Specify wether the actor id belongs to the primary actor of the observation.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status": "success"
}

Add Activities to Observation

Add activities to observation.

Authorizations:
ApiKeyAuth
path Parameters
id
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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Finalize an Observation

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

Authorizations:
ApiKeyAuth
path Parameters
id
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
id
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": [
    ],
  • "observationFailedFinalization": [
    ]
}

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",
  • "events": [
    ],
  • "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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "events": [
    ],
  • "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
id
required
string

Unique Webhook Id

Responses

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "events": [
    ],
  • "id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
  • "status": "ACTIVE",
  • "created": 1692294086682,
  • "tenant": "lucinity"
}

Remove a Webhook by Id

Authorizations:
BearerToken
path Parameters
id
required
string <uuid>

Unique Webhook Id

Responses

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "events": [
    ],
  • "id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74",
  • "status": "ACTIVE",
  • "created": 1692294086682,
  • "tenant": "lucinity"
}

Update Webhook

Authorizations:
BearerToken
path Parameters
id
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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "events": [
    ],
  • "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
id
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 <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.assigned",
  • "createdAt": 0,
  • "data": {
    }
}

Case Closed Webhook

Request Body schema: application/json

Information about an event in the systems

id
string <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.closed",
  • "createdAt": 0,
  • "data": {
    }
}

Case Created Webhook

Request Body schema: application/json

Information about an event in the systems

id
string <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.created",
  • "createdAt": 0,
  • "data": {
    }
}

Case Workflow Action Performed Webhook

Request Body schema: application/json

Information about an event in the systems

id
string <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.workflow.actioned",
  • "createdAt": 0,
  • "data": {
    }
}

Commented on a case event Webhook

Request Body schema: application/json

Information about a comment event in the systems

id
string <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.commented",
  • "createdAt": 0,
  • "data": {
    }
}

Transaction Decision Update Event Webhook

Request Body schema: application/json

Information about an event in the systems

id
string <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.transaction.decision.updated",
  • "createdAt": 0,
  • "data": {
    }
}

Case Observation Feedback Updated Webhook

Request Body schema: application/json

Information about an event in the system

id
string <uuid>

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

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "case.observations.feedback.updated",
  • "createdAt": 0,
  • "data": {
    }
}

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": [
    ]
}

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
[
  • {
    }
]

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:

  1. The incident report is received.
  2. The incident is evaluated. If false-positive, end workflow. If valid, proceed to step three.
  3. Email or a ticket is sent to the team in charge.
  4. The team deliberates and decides on the incident report.
  5. The team proposes and applies a solution.
  6. 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.