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(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
required

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

customerSince
string <date>

Date when the actor first became a customer.

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

Array of objects (Link)

links to related accounts.

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",
  • "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": {
    }
}

Get Actor

Retrieves a single actor by identifier.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Responses

Response 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": {
    }
}

Add Actor Associates

Add associates to actors by ID.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Request Body schema: application/json
required

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. Defaults to today if not provided.

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 Exclusion

Add actor exclusion.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Request Body schema: application/json
required

Exclusion to be added for an actor.

exclusion_type
required
string
Enum: "MONITORED" "NOT_MONITORED" "ON_PERIODIC_REVIEW" "SUPPRESSED"

The type of exclusion.

  • MONITORED - This actor will be monitored in the Lucinity platform (this is the default value for all actors)

  • NOT_MONITORED - This actor will not be monitored in any shape or form.

  • ON_PERIODIC_REVIEW - This actor will be monitored in the Lucinity platform but will not create alerts but stored internally for periodic review when requested.

  • SUPPRESSED - This actor will be monitored in the Lucinity platform but will not create alerts but stored internally.

stored_at
string <date-time>

The datetime when the exclusion was stored defaults to current time.

Responses

Request samples

Content type
application/json
{
  • "exclusion_type": "MONITORED",
  • "stored_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
"ACTOR_ID_100000"

Add Actor RiskAssessment

Add actor risk assessment.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Request Body schema: application/json
required

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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Get Actor RiskAssessment

Get actor risk assessment.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Actor Extended Info

Add actor extended information.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Request Body schema: application/json
required

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. Defaults to today if not provided.

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",
  • "actorId": "string"
}

Get Actor Extended Info

Get actor extended information.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Actor ID

Responses

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",
  • "actorId": "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
required

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

accountType
required
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.

asOfDate
required
string <date>

The date when this record became valid

name
string

The name of the account.

object (Metadata)

Reference attribute

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

bankCode
string

Bank code used for the Account

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)

Interest reference

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

accountAgreementId
string
Deprecated

Agreement ID of the account.

primaryRepresentativeId
string
Deprecated

The id of the primary representative for the account.

beneficiaryOwnerId
string
Deprecated

The id of the beneficiary owner for 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": [
    ],
  • "ingestDate": "2020-05-03T14:03:41.089Z",
  • "classification": {
    },
  • "accessClassification": {
    },
  • "accountType": "CURRENT",
  • "asOfDate": "2019-08-24",
  • "name": "Mez's account",
  • "metadata": {
    },
  • "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,
  • "bankCode": "string",
  • "productId": "string",
  • "internal": true,
  • "depositable": true,
  • "withdrawable": true,
  • "collateral": true,
  • "terminated": true,
  • "accountInDefault": true,
  • "accountInDefaultDays": 0,
  • "interest": [
    ],
  • "balance": {
    },
  • "termDeposit": {
    },
  • "credit": {
    },
  • "loan": {
    },
  • "brokerage": {
    },
  • "accountAgreementId": "string",
  • "primaryRepresentativeId": "string",
  • "beneficiaryOwnerId": "string",
  • "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": {
    },
  • "accountType": "CURRENT",
  • "asOfDate": "2019-08-24",
  • "name": "Mez's account",
  • "metadata": {
    },
  • "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,
  • "bankCode": "string",
  • "productId": "string",
  • "internal": true,
  • "depositable": true,
  • "withdrawable": true,
  • "collateral": true,
  • "terminated": true,
  • "accountInDefault": true,
  • "accountInDefaultDays": 0,
  • "interest": [
    ],
  • "balance": {
    },
  • "termDeposit": {
    },
  • "credit": {
    },
  • "loan": {
    },
  • "brokerage": {
    },
  • "accountAgreementId": "string",
  • "primaryRepresentativeId": "string",
  • "beneficiaryOwnerId": "string",
  • "customData": {
    }
}

Add Account Balance

Add balance for an account.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

The account id.

Request Body schema: application/json
required

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/actors 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
required

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

required
Array of objects

List of the actors associated with account and their role

asOfDate
string <date>

The date when this record became valid. Defaults to today if not provided.

Responses

Request samples

Content type
application/json
{
  • "actors": [
    ],
  • "asOfDate": "2024-01-01"
}

Response samples

Content type
application/json
{
  • "actors": [
    ],
  • "asOfDate": "2024-01-01"
}

Transactions

Add Transaction

Note: Transaction screening is a feature that is configured by Lucinity, and may not be configured for your environment. Please contact Lucinity support for more information.

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
required
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" "CHARGEBACK" "CLOSING" "CORRECTION" "FEE" "FUNDING" "INTRA_ACTOR" "INTEREST_PAYMENT" "PAY_IN" "PAY_OUT" "PRINCIPAL_PAYMENT" "REFUND" "REVERSE" "SETTLEMENT"

purpose of the transaction.

  • BILL_PAYMENT Payment of a bill.
  • CHARGEBACK Chargeback, initiated to reverse a previous payment made by a cardholder.
  • CLOSING Closure or finalization of an account or financial arrangement.
  • CORRECTION Adjustment to rectify an error or discrepancy in a previous transaction.
  • FEE Fee charged for a service or transaction.
  • FUNDING Provision of funds to an account or financial instrument.
  • INTRA_ACTOR Movement of funds between internal accounts of the same actor within the client's ecosystem.
  • INTEREST_PAYMENT Payment of accrued interest.
  • PAY_IN Incoming payment or deposit into an account.
  • PAY_OUT Outgoing payment or withdrawal from an account.
  • PRINCIPAL_PAYMENT Payment of the principal amount owed.
  • REFUND Refunding a previous payment.
  • REVERSE Reversal or cancellation of a previous transaction.
  • SETTLEMENT Finalization or clearing of a transaction or series of transactions.
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

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

Get Transaction

Retrieves a single transaction by identifer.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

The identifier for the transaction.

Responses

Response 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": {
    }
}

Observations

Add Observation

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
required

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

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

Response samples

Content type
application/json
Example
{
  • "caseIds": [
    ],
  • "observationFailedFinalization": [
    ]
}

Get Observation

Retrieves a single observation by identifier.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

The observation ID.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "ALERT_RULE",
  • "title": "string",
  • "transactionIds": [
    ],
  • "score": "string",
  • "id": "568975e1-d16b-4e5a-9ecd-16cb105a6976",
  • "dataSource": "SWAGGER_API",
  • "references": [
    ],
  • "metadata": {
    },
  • "classification": {
    },
  • "accessClassification": {
    },
  • "date": 1654236000,
  • "batchId": "string",
  • "behaviorId": "string",
  • "behaviorName": "string",
  • "behaviorDescription": "string",
  • "version": "string",
  • "actors": [
    ],
  • "rules": [
    ],
  • "custom_data": {
    },
  • "ingestDate": "string",
  • "internalId": "6868d0ce-34a2-4e78-b137-31229ba3e81a",
  • "finalized": true,
  • "caseId": "string",
  • "submitterInternalId": "string",
  • "businessDate": "string",
  • "taxonomyDescription": "string"
}

Add Actors to Observation

Add actors to observation.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Observation id

Request Body schema: application/json
required

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

Content type
application/json
[
  • {
    }
]

Response samples

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

Cases

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
required
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.
Array of objects

List of communications that are part of the case. Each communication should include detailed information such as the type, sender, receiver, subject, and content.

Responses

Request samples

Content type
application/json
{
  • "focal_actor_id": "2928938-29892-92983-923892839",
  • "observation_ids": [
    ],
  • "metadata": {
    },
  • "communications": [
    ]
}

Response samples

Content type
application/json
{
  • "case_id": "5fa9e93b-3a93-4e6a-82cd-6d9dad7b0d74"
}

Update a Case

Update an existing Case in the Lucinity platform. The Case will be updated with the provided details.

Authorizations:
BearerToken
Request Body schema: application/json
required
communication_ids
Array of strings

List of ids of the communications that should be associated with the case

Array of objects

List of communication objects to create and associate with the case

Responses

Request samples

Content type
application/json
{
  • "communication_ids": [
    ],
  • "communications": [
    ]
}

Response samples

Content type
application/json
{
  • "case_id": "CASE25618010303001",
  • "communicationIds": [
    ]
}

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

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": "1",
  • "name": "case.assigned",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "1",
  • "name": "case.closed",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "1",
  • "name": "case.created",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "1",
  • "name": "case.workflow.actioned",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "1",
  • "name": "case.commented",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "1",
  • "name": "case.transaction.decision.updated",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

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

Content type
application/json
{
  • "id": "1",
  • "name": "case.observations.feedback.updated",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

Observation Actioned Event Webhook

Request Body schema: application/json

Information that a event has been actioned, typically a case observation. This event is triggered when an observation is actioned. Currently only supports "WHITELIST" action.

id
string

The id for the event created by Lucinity

name
string
Value: "case.observations.actioned"

The type of the event

createdAt
integer <int64>

The timestamp this event was created

object

Detail event data for observation actioned.

Responses

Request samples

Content type
application/json
{
  • "id": "1",
  • "name": "case.observations.actioned",
  • "createdAt": 1711360775327,
  • "data": {
    }
}

Reporting

The reporting APIs offer customers real time access to various reports pulled from the Lucinity platform. They are grouped into categories and listed out below.

Observation Reporting

Get Observation Feedback

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

Signals Reporting

Get Suppressed Signals

Get signals that were suppressed due to reasons such as, the actor being under periodic review or suppression. Suppressed signals do not generate observations for analyst review.

Authorizations:
ApiKeyAuth
query Parameters
startDate
required
string <date>
Example: startDate=2023-11-21

Is in ISO 8601 date format and must predate or equal endDate.

endDate
required
string <date>
Example: endDate=2023-11-21

Is in ISO 8601 date format and must postdate or equal startDate.

limit
integer
Example: limit=100

The maximum number of suppressed signals that will be returned. The default setting is 100, with a maximum limit of 1000.

offset
integer
Example: offset=0

The offset of the suppressed signals that will be returned. The default setting is 0.

Responses

Response samples

Content type
application/json
{
  • "signals_suppressed": [
    ],
  • "limit": 10,
  • "offset": 0,
  • "number_of_signals": 1
}

Audit Logs

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

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.