Skip to main content
API docs by Redocly

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.

Ingestion

Bulk Ingestion

Bulk Ingestion

This endpoint allows you to submit 1000 entities or 32MB, whichever is reached first, of data in bulk to be ingested into the system asynchronously. It is designed to handle high-throughput data processing, ensuring that large datasets are efficiently processed and stored.

Initial Schema Validation:

Upon submission, the system performs an initial validation of the payload’s schema to ensure that the data is correctly formatted and adheres to the expected structure. If the payload fails this schema validation, the system will respond immediately with an error message detailing the issues found, and the request will be rejected.

Downstream Data Validation:

If the payload passes the initial schema validation, the system responds with a 200 OK status code, indicating successful ingestion of the request. The data then enters the processing pipeline for in-depth validation, which includes verifying required relationships and ensuring consistency with existing data in the system.

Errors that occur during this downstream processing—such as data relation validation errors—are not reflected in the initial API response. The status of the downstream processing will either be exposed via an API or a webhook, this implementation is yet to be determined.

Scalability and Data Integrity:

The endpoint is designed to be scalable and optimized for handling high-load scenarios while ensuring data integrity throughout the ingestion pipeline.

Note: This endpoint is still a work in progress and is subject to change.

Authorizations:
BearerToken
Request Body schema: application/json
required
Array of objects (AccountActor) <= 1000 items

List of account actors relationships to ingest.

Array of objects (Balance) <= 1000 items

List of account balances.

Array of objects (Account) <= 1000 items

List of accounts to ingest.

Array of objects (ActorSegmentationGroup) <= 1000 items

List of actor to segmentation group assignments.

Array of Individual (object) or LegalEntity (object) (Actor) <= 1000 items

List of actors to ingest.

Array of AnalysisCase (object) or FilingCase (object) (Case) <= 1000 items

List of cases to ingest.

Array of objects (Communication) <= 1000 items

List of communications to ingest.

Array of AmlV2Observation (object) or FraudObservation (object) or SanctionsObservation (object) or RuleObservation (object) or GenericObservation (object) (Observation) <= 1000 items

List of observations to ingest.

Array of objects (Transaction) <= 1000 items

List of transactions to ingest.

Responses

Request samples

Content type
application/json
{
  • "account_actors": [
    ],
  • "account_balances": [
    ],
  • "accounts": [
    ],
  • "actors": [
    ],
  • "actor_segmentation_groups": [
    ],
  • "cases": [
    ],
  • "communications": [
    ],
  • "observations": [
    ],
  • "transactions": [
    ]
}

Response samples

Content type
text/plain
OK

Get Bulk Case Ingestion Status

Returns the latest ingestion status for a case. This endpoint is designed for use with the asynchronous ingestion via the Bulk API. Due to its asynchronous nature, not all entities may be processed when a case is being processed.

A case will only be fully processed after all referenced entities have been successfully ingested. The status field, along with the missing_relations field, can be used to determine whether the case has been successfully processed. If there are missing relations, additional ingestion may be required before the case is fully processed.

Lucinity guarantees that this data will be retained for 30 days, after which it will be subject to removal.

Authorizations:
BearerToken
path Parameters
id
required
string

The ID of the case to fetch the ingestion status for.

Responses

Response samples

Content type
application/json
{
  • "status": "COMPLETED",
  • "missing_relations": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "processed_at": "2019-08-24T14:15:22Z",
  • "deferred_until": "2019-08-24T14:15:22Z",
  • "attempts": 0
}

Get Cases in Dead Letter Queue

Returns a list of cases that failed to be properly ingested through the bulk ingestion.

Authorizations:
BearerToken
query Parameters
filter
string

Filtering enables narrowing down API responses based on specific criteria.

Range Filter:

  • Syntax: filter.<field_name>.from=X&filter.<field_name>.to=Y
    • Either from, to, or both can be specified.
    • Inclusive of boundary values.

Examples:

  • Filter transaction.created_at between 2024-11-24 and 2024-11-25:
    • filter.created_at.from=2024-11-24&filter.created_at.to=2024-11-25
  • Filter transaction.amount greater than or equal to 0:
    • filter.amount.value.from=0

Single-Value Filter:

  • Syntax: filter.<field_name>=X.
    • Matches data exactly to the specified value.

Examples:

  • Filter transaction.method for CARD:
    • filter.method=CARD.
limit
number
Example: limit=5

Sets the max number of items returned in the result set for this query

offset
number
Example: offset=35

Sets the offset on the index into the list of items in the result set

sorting
string

Sorting allows API responses to be ordered by one or more fields in a specified direction.

  • Syntax: sort.by=<field>:<direction>[,<field>:<direction>]
    • <field>: Field name in the object, following schema conventions.
    • <direction>: Sorting order, asc (ascending, default) or desc (descending).
  • Multi-column Sorting: Specify multiple fields, separated by commas, to sort by priority.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Path Update

Accounts

Update account

Updates the fields in the newest Account that has the provided ID.

Notes:

  • Updating an array is an additive insert operation, meaning that the new values are appended to the existing array.
  • This endpoint is still a work in progress and is subject to change.
Authorizations:
BearerToken
path Parameters
id
required
string

The Account ID.

Request Body schema: application/json
required
account_number
string

The identifier assigned by the financial institution to the account.

account_type
string (AccountType)
Enum: "CREDIT_CARD" "CURRENT" "E-WALLET" "LOAN" "SAVINGS" "VIRTUAL"

Specifies the type of account (e.g., savings, loan, e-wallet). Used to categorize and determine the nature of the account.

as_of_date
string <date>

The date when this record became valid, in ISO 8601 format.

bank_code
string

The unique identifier assigned to the bank or financial institution where the account resides.

object (CustomData)

The custom data property can be used to add data in a key, value format to the object. This can e.g. be used for display purposes.

iban
string

International Bank Account Number, used for global transactions to identify the account.

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.

name
string

A user-friendly name for the account, making it easier to identify in interfaces and reports.

opened_date
string <date>

The date when the account was first activated, formatted in ISO 8601.

Array of objects (Reference) <= 1000 items
status
string (AccountStatus)
Enum: "ACTIVE" "CLOSED" "LOCKED"

The current operational state of the account (e.g., ACTIVE, CLOSED, LOCKED).

Responses

Request samples

Content type
application/json
{
  • "name": "John's account"
}

Response samples

Content type
text/plain
OK

Actors

Update actor

Updates the fields in the newest Actor that has the provided ID.

Notes:

  • Updating an array is an additive insert operation, meaning that the new values are appended to the existing array.
  • This endpoint is still a work in progress and is subject to change.
Authorizations:
BearerToken
path Parameters
id
required
string

The Actor ID.

Request Body schema: application/json
required
Array of objects (PostalAddress) <= 1000 items

A list of physical or legal addresses associated with the actor.

as_of_date
string <date>

The date when this record became valid, in ISO 8601 format.

object (CustomData)

The custom data property can be used to add data in a key, value format to the object. This can e.g. be used for display purposes.

customer_since
string <date>

Date when the actor first became a customer, in ISO 8601 format.

data_source
string

An identifier that represents the system from which the record is originated.

date_of_birth
string <date>

Date of birth of the actor, in ISO 8601 format.

date_of_registration
string <date>

Date of registration of the actor, in ISO 8601 format

domicile
string

The ISO 3166 alpha-3 country code represents the legal jurisdiction considered an actors's permanent home for legal purposes.

Array of objects (EmailAddress) <= 1000 items

A list of emails associated with the actor.

gender
string (Gender)
Enum: "FEMALE" "MALE" "OTHER" "UNSPECIFIED"

The gender of the individual.

Array of objects (GovernmentId) <= 1000 items

Government id list for actor.

Array of objects (Industry) <= 1000 items

List of industry classifications in which the legal entity operates in.

legal_structure
string (LegalStructure)
Enum: "COMPANY_PRIVATE" "COMPANY_PUBLIC" "GOVERNMENT" "HOLDING" "NONPROFIT" "ORGANIZATION" "OTHER" "PARTNERSHIP_GENERAL" "PARTNERSHIP_LIMITED" "SOLE_PROPRIETORSHIP" "SUBSIDIARY" "TRUST"

Legal structure or form of the legal entity actor

  • COMPANY_PRIVATE - Business is incorporated and privately owned, with shares not traded on a public stock exchange
  • COMPANY_PUBLIC - Business is incorporated and publicly owned, with shares traded on a public stock exchange
  • GOVERNMENT - Organization is formed by a government statute or body
  • HOLDING
  • NONPROFIT
  • ORGANIZATION
  • OTHER
  • PARTNERSHIP_GENERAL - Business is jointly owned by multiple people and governed by a partnership agreement
  • PARTNERSHIP_LIMITED - SOLE_PROPRIETORSHIP - Business is not a separated legal entity from its individual owner
  • SUBSIDIARY
  • TRUST
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.

name
string

Name of individual or company.

nationality
string

The ISO 3166 alpha-3 country code representing the nation-state in which the actor has a legal relationship with.

Array of objects (Phone) <= 1000 items

A list of phone numbers associated with the actor.

Array of objects (Reference) <= 1000 items

List of references to an external system.

Array of objects (Link) <= 1000 items

Links to external resources or objects related to the legal entity.

status
string (ActorStatus)
Enum: "ACTIVE" "TERMINATED"

Enumerated values for the status of the actor.

subtypes
Array of strings (ActorSubType) <= 1000 items
Items Enum: "CLIENT" "CPSP" "CUSTOMER" "EMPLOYEE" "MERCHANT" "PRINCIPAL" "SUB_CLIENT"

Array of subtypes of actor.

Responses

Request samples

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

Response samples

Content type
text/plain
OK

Cases

Get case

Retrieves a single case by identifier.

Authorizations:
BearerToken
path Parameters
id
required
string

The Case ID.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2025-01-06T13:39:659123Z",
  • "updated_at": "2025-01-07T14:44:359729Z",
  • "assignee": {},
  • "workflow": {
    },
  • "actors": [
    ],
  • "observations": [
    ],
  • "tags": [
    ],
  • "metadata": {
    },
  • "resolution": "string",
  • "source": "string",
  • "jurisdiction": "AUS",
  • "type": "ANALYSIS",
  • "narrative": {
    },
  • "property1": "string",
  • "property2": "string"
}

Update case

Updates the fields in the case that has the provided ID. Notes:

  • Updating an array is an additive insert operation, meaning that the new values are appended to the existing array.
  • This endpoint is still a work in progress and is subject to change.
Authorizations:
BearerToken
path Parameters
id
required
string

The Case ID.

Request Body schema: application/json
required
Resolution (string) or Resolution (number) or Resolution (integer) or Resolution (boolean) or Resolution (object) or Array of Resolution (arrays) (Resolution)

Describes the reason behind a case closure. The content and structure of this field are flexible and can vary depending on the context. It is defined through the Custom Properties, which allows for dynamic extension and customization based on specific business needs.

additional property
string or number or integer or boolean or object or Array of arrays

Custom properties whose keys must start with the prefix c__.

Responses

Request samples

Content type
application/json
{
  • "resolution": "Not Suspicious",
  • "c__custom_string_property": "custom_value",
  • "c__custom_number_property": 12345,
  • "c__custom_object_property": {
    }
}

Response samples

Content type
text/plain
OK

Add an actor to a case

Creates a new actor entity and assigns it to the specified case.

Authorizations:
BearerToken
path Parameters
id
required
string

The ID of the case to add the actor to.

header Parameters
lucinity-rfd-id
string <uuid>

The rfd_id used to retrieve information about the request. Include it to complete an rfd item.

Request Body schema: application/json
required
required
Individual (object) or LegalEntity (object) (Actor)
object (CustomData)

The custom data property can be used to add data in a key, value format to the object. This can e.g. be used for display purposes.

type
string (CaseActorType)
Enum: "CONNECTION" "FOCAL"

The role that the actor has in the case.

Defaults to FOCAL.

Responses

Request samples

Content type
application/json
{
  • "type": "CONNECTION",
  • "custom_data": {
    },
  • "actor": {
    }
}

Update multiple case actors

Updates multple case actor relationships in a case. Maximum 1000 actors in each request.

Authorizations:
BearerToken
path Parameters
id
required
string

The ID of the case the actors belong to.

Request Body schema: application/json
required
Array
actor_id
string

The ID of the actor.

object

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Update a case actor

Updates the fields in the case actor that has the provided ID.

Authorizations:
BearerToken
path Parameters
actor_id
required
string

The ID of the actor

case_id
required
string

The ID of the case

Request Body schema: application/json
required
additional property
string or number or integer or boolean or object or Array of arrays or null (CustomProperties)

Custom properties whose keys must start with the prefix c__.

One of
string

Custom properties whose keys must start with the prefix c__.

Responses

Request samples

Content type
application/json
{
  • "c__custom_string_property": "custom_value",
  • "c__custom_number_property": 12345,
  • "c__custom_object_property": {
    }
}

Add a communication to a case

Creates a new communication entity and assigns it to the case.

Authorizations:
BearerToken
path Parameters
id
required
string

The case_id.

header Parameters
lucinity-rfd-id
string <uuid>

The rfd_id used to retrieve information about the request. Include it to complete the rfd item.

Request Body schema: application/json
required
id
required
string <uuid>

The unique identifier for the communication.

content
string

The content of the communication.

object (CustomData)

The custom data property can be used to add data in a key, value format to the object. This can e.g. be used for display purposes.

object (Metadata)

Metadata describing the communication. This field is not intended to add additional information to the communication, rather add information about the communication's attributes.

receiver_id
string

Identifies the receiver uniquely in the system where the communications originates. For example if this is an email it could be the email address, if it is from a messaging system it could be the user handle in that system. Alternatively can be provided as Actor/Entity id, as provided in the Actor endpoint, If so then metadata should be used. metadata.receiver_identifiable_as_actor=true.

sender_id
string

Identifies the sender uniquely in the system where the communications originates. For example if this is an email it could be the email address. If it is from a messaging system it could be the user handle in that system. Alternatively can be provided as Actor/Entity id, as provided in the Actor endpoint. If so then metadata should be used. metadata.sender_identifiable_as_actor=true.

subject
string

The subject title of the message in the communication.

type
string

The type of communication (e.g., email, SMS).

Responses

Request samples

Content type
application/json
{
  • "id": "6f83db65-50e0-4f7c-b42a-61115110a928",
  • "type": "email",
  • "content": "Please update your account information.",
  • "custom_data": {
    },
  • "metadata": {
    },
  • "receiver_id": "[email protected]",
  • "sender_id": "[email protected]",
  • "subject": "Urgent: Update Required"
}

Upload a file to a case

Uploads a file related to a specific case.

File size may not exceed 50MB.

Valid file formats are:

  • Images (JPG, PNG, GIF)
  • Docs (PDF, DOC, DOCX, EXCEL, JSON, TXT, CSV)
Authorizations:
BearerToken
path Parameters
id
required
string

The case_id

header Parameters
lucinity-rfd-id
string <uuid>

The rfd_id used to retrieve information about the request. Include it to complete the rfd item.

Request Body schema: multipart/form-data
required
file
string <binary>

Responses

Observations

Update observation

Updates the fields in the newest Observation that has the provided ID. Notes:

  • Updating an array is an additive insert operation, meaning that the new values are appended to the existing array.
  • This endpoint is still a work in progress and is subject to change.
Authorizations:
BearerToken
path Parameters
id
required
string

The Observation ID.

Request Body schema: application/json
required
One of
actor_ids
Array of strings <= 1000 items

The Actor IDs which this observations applies to.

behavior_description
string

A detailed description of the behavior associated with the observation.

behavior_id
string

A unique identifier used to classify the risk or concern associated with the observation.

created_at
string <date-time>

Timestamp at which the observation was created, in ISO 8601 format.

object (CustomData)

The custom data property can be used to add data in a key, value format to the object. This can e.g. be used for display purposes.

data_source
string

An identifier that represents the system from which the record is originated.

Array of objects (ObservationFeatures)

List of features and values contributing to the observation.

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.

Array of objects (Reference) <= 1000 items
Array of objects (Rule) <= 1000 items

List of objects representing rules that were triggered.

score
string

A score indicator for the result of this rule applying. This could be a numeric value or it could be some qualifier such as 'APPROVE' or 'REJECT', indicating a suggested operation based on this rule applying.

title
string

Summarizes the primary risk or concern identified in the observation.

transaction_ids
Array of strings <= 10000 items

List of transaction ids which apply in this observation.

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.

Responses

Request samples

Content type
application/json
Example
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "actor_ids": [
    ],
  • "transaction_ids": [
    ],
  • "score": "string",
  • "behavior_id": "string",
  • "title": "Transfer to High-Risk Country",
  • "behavior_description": "string",
  • "data_source": "EXTERNAL_DATA_SOURCE",
  • "features": [
    ],
  • "references": [
    ],
  • "version": "string",
  • "rules": [
    ],
  • "metadata": {
    },
  • "custom_data": {
    }
}

Response samples

Content type
text/plain
OK

Transactions

Update transaction

Updates the fields in the newest Transaction that has the provided ID. Notes:

  • Updating an array is an additive insert operation, meaning that the new values are appended to the existing array.
  • This endpoint is still a work in progress and is subject to change.
Authorizations:
BearerToken
path Parameters
id
required
string

The transaction ID.

Request Body schema: application/json
required
account_balance
number

The current, settled balance of the account in the currency of the account.

account_id
string

Primary identifier of the account.

account_owner_id
string

A unique identifier representing the actor who is the owner of the account, expected to be a valid actor_id.

object (Amount)

Amount and currency code of the transaction that occured.

channel
string (Channel)
Enum: "ATM" "BRANCH" "ONLINE" "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.
channel_location_id
string

The unique identifier for the channel location associated with the transaction. Has to match a location code ingested through /channel_locations.

CounterpartyLegalEntity (object) or CounterpartyIndividual (object) or AccountInfo (object) or NamedEntity (object) or Empty (object)

Counterparty represents the creditor or debtor involved in the transaction and can be one of the following:

  • 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.
  • EMPTY Indicates that there is no counterparty for the transaction. This should not be used if the counterparty is unknown, only for cases where there is no counterparty, e.g. for cash withdrawals.
created_at
string <date-time>

The timestamp of when the transaction occurred, in ISO 8601 format.

object (CustomData)

The custom data property can be used to add data in a key, value format to the object. This can e.g. be used for display purposes.

description
string

Description of the transaction.

object (Device)

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

direction
string (Direction)
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.

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.

  • 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.
method
string (Method)
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 (Purpose)
Enum: "BILL_PAYMENT" "CHARGEBACK" "CLOSING" "CORRECTION" "FEE" "FUNDING" "INTEREST_PAYMENT" "INTRA_ACTOR" "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.
standardized_amount
number

Value of the transaction in the default currency configured in the Lucinity platform.

status
string (TransactionStatus)
Enum: "CANCELLED" "COMPLETED" "FAILED" "PENDING"

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.
user_id
string

User id of the entity performing the transaction.

user_name
string

User name of the entity performing the transaction.

Responses

Request samples

Content type
application/json
{
  • "amount": {
    }
}

Response samples

Content type
text/plain
OK

Webhooks

Webhook

List registered webhooks

List registered webhooks.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "url": "https://my-company.com/api/webhooks/myhook",
  • "events": [
    ],
  • "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
events
required
Array of strings

List of events to subscribe to. If '*' all events will be delivered. If empty, the Webhook will be disabled.

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "url": "https://my-company.com/api/webhooks/myhook",
  • "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",
  • "url": "https://my-company.com/api/webhooks/myhook",
  • "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",
  • "url": "https://my-company.com/api/webhooks/myhook",
  • "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.

events
Array of strings

List of events to subscribe to. If '*' all events will be delivered. If empty, the Webhook will be disabled.

name
string

The name of the Webhook given by the Webhook creator

status
string (WebhookStatus)
Enum: "ACTIVE" "INACTIVE"
url
string <uri>

The target URL for the Webhooks. Typically an endpoint in the customer API that can accept the Lucinity events

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "name": "My Webhook for handling claimed cases",
  • "url": "https://my-company.com/api/webhooks/myhook",
  • "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

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for case claimed

id
string

The id for the event created by Lucinity.

name
string
Value: "case.assigned"

The type of the event

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

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for case case closed

id
string

The id for the event created by Lucinity.

name
string
Value: "case.closed"

The type of the event

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

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for case case created.

id
string

The id for the event created by Lucinity.

name
string
Value: "case.created"

The type of the event

Responses

Request samples

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

Case Updated event Webhook

Request Body schema: application/json

Information about an event in the systems.

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Event data for case update.

id
string

The id for the event created by Lucinity.

name
string
Value: "case.updated"

The type of the event

Responses

Request samples

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

Case Creation Failed Webhook

Request Body schema: application/json

Information about an event in the systems.

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Event data for case creation failure.

id
string

The id for the event created by Lucinity.

name
string
Value: "case.creation_failed"

The type of the event

Responses

Request samples

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

Case Workflow Action Performed Webhook

Request Body schema: application/json

Information about an event in the systems

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detailed event data for when an action on a workflow is performed in a case.

id
string

The id for the event created by Lucinity.

name
string
Value: "case.workflow.actioned"

The type of the event

Responses

Request samples

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

Case Workflow Step Transitioned Webhook

Request Body schema: application/json

Information about a workflow transition of case in the system

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for when a workflow transition occurs in a case

id
string

The id for the event created by Lucinity.

name
string
Value: "case.workflow.transitioned"

The type of the event

Responses

Request samples

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

Commented on a case event Webhook

Request Body schema: application/json

Information about a comment event in the systems

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detailed event data for when a comment is added to a case

id
string

The id for the event created by Lucinity.

name
string
Value: "case.commented"

The type of the event

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

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for transaction decision update

id
string

The id for the event created by Lucinity.

name
string
Value: "case.transaction.decision.updated"

The type of the event

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

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for observation added

id
string

The id for the event created by Lucinity.

name
string
Value: "case.observations.feedback.updated"

The type of the event

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.

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object

Detail event data for observation actioned.

id
string

The id for the event created by Lucinity.

name
string
Value: "case.observations.actioned"

The type of the event

Responses

Request samples

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

RFD Events

Request for Data Created Event Webhook

Request Body schema: application/json

Information about an event in the systems

createdAt
integer <int64>

The Unix timestamp (in milliseconds) indicating when this event was created.

object
id
string

The id for the event created by Lucinity.

name
string
Value: "request_for_data.created"

The type of the event

Responses

Request samples

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

Schema Mapping

Add schema mapping for custom_data

This endpoint is for adding a schema mapping for a custom_data property on an entity. The schema mapping describes the property structure and can be as simple as a string or number or as complex as an object or array of objects.

The schema is described using JSON Schema and will be validated by the endpoint. However there are certain keywords from Json schema that will not be supported and will generate a 400 validation error.

The following elements are not supported:

  • $ref to external schemas - if $ref is used it must start with '#/'
  • allOf, anyOf, oneOf - union types are not supported
  • additionalProperties - dynamic properties are not allowed

The entities containing custom_data:

Entity Will apply to the custom_data block on
account Account object
actor Actor object
actor.phones Phone object in the phones array of Actor object
case Case object
case.actors CaseActor object in actors array of Case object
transaction Transaction object
observation Observation object
observation.rules Rule object in rules array of Observation object

Example of schema payload:

To support the following custom_data property my_custom_property in actor object:

{
  ...
  "custom_data": {
    "my_custom_property": {
      "nestedProperty": "value",
      "nestedArrayProperty": ["value1", "value2"]
    }
  }
  ...
}

The following json schema could be provided for the custom_data property:

POST /custom_data_schema_mapping/actor/my_custom_property

{
  "schema": {
    "type": "object",
    "properties": {
      "nestedProperty": {
        "type": "string"
      },
      "nestedArrayProperty": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": ["nestedProperty", "nestedArrayProperty"]
  }
}
Authorizations:
BearerToken
path Parameters
entity
required
string
Example: case

The entity containing the custom_data block.

property
required
string
Example: investigation_origin

The custom_data property name.

Request Body schema: application/json
required
required
object

JSON Schema definition for the custom data.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "schema": { }
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get schema mapping for custom_data property

This endpoint will fetch the schema mapping for a custom_data property on an entity if it has been defined.

Authorizations:
BearerToken
path Parameters
entity
required
string
Example: case

The entity containing the custom_data block.

property
required
string
Example: investigation_origin

The custom_data property name.

Responses

Response samples

Content type
application/json
{
  • "property": "string",
  • "schema": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string"
}

Delete schema mapping for custom_data property

This endpoint will delete the schema mapping for a custom_data property on an entity if it has been defined.

Authorizations:
BearerToken
path Parameters
entity
required
string
Example: case

The entity containing the custom_data block.

property
required
string
Example: investigation_origin

The custom_data property name.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get schema mapping for all custom data properties on an entity

This endpoint will fetch the schema mapping for all custom_data property on an entity that have been defined.

Authorizations:
BearerToken
path Parameters
entity
required
string
Example: case

The entity containing the custom_data block.

Responses

Response samples

Content type
application/json
{
  • "entity": "string",
  • "properties": [
    ]
}

Custom Properties

Retrieves a list of custom properties

This endpoint will fetch the custom properties that have been defined. The custom properties are used to store additional information about the entity.

Currently supported entities are:

  • case
  • case.actor
Authorizations:
BearerToken
query Parameters
filter.entity
string
Example: filter.entity=case

The entity containing the custom property.

filter.name
string
Example: filter.name=c__actor_decision

The custom property name.

limit
number
Example: limit=5

Sets the max number of items returned in the result set for this query

offset
number
Example: offset=35

Sets the offset on the index into the list of items in the result set

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Request for Data

The Request for Data (RFD) feature enables analysts to request additional information from internal systems to support case investigations. This capability streamlines the process of gathering supplementary data, ensuring analysts have what they need to carry out effective reviews and meet regulatory compliance requirements.

RFD flows are highly flexible and can be customized to match your organization’s internal workflows.

Example RFD Flow

  1. An analyst working on a case identifies the need for additional information from an internal system.
  2. The analyst uses the RFD feature to request the necessary data through a form created and designed in collaboration with Lucinity.
  3. Lucinity creates the RFD request and sends a notification a webhook notification (request_for_data.created).
  4. Your internal system receives the RFD request via webhook and processes it according to the defined schema.
  5. Your internal system sends the requested data back to Lucinity, and completes the RFD request by providing the lucinity-rfd-id header with the request that completeded the RFD.
    • If completeing the RFD is not possible, the internal system can send a request to the /request_for_data/{id}/reject and provide a reason for the rejection.
  6. The case has been updated with the received data, allowing the analyst to continue their investigation with the additional information.

Additional Notes

  • Each RFD is linked to a single entity (e.g., a document, actor, or other case items).
  • If a request needs to be made for multiple entities, a separate RFD request should be created for each.

Get RFD by Id

Retrieves an RFD object using its unique Id.

Authorizations:
BearerToken
path Parameters
id
required
string <uuid>

The unique identifier for the RFD.

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "status": "COMPLETED",
  • "request": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

Reject an RFD request.

Cancels the RFD flow and marks the RFD request as rejected. After calling this endpoint, the SLA will be disabled and the case will eventually revert to its previous state before the RFD process was initiated. Note that if you try to reject a RFD that has already been comlpleted you will get a 400 error.

Authorizations:
BearerToken
path Parameters
id
required
string <uuid>

The unique identifier of the RFD.

Request Body schema: application/json
required
reason
string

Reason for rejection.

Responses

Request samples

Content type
application/json
{
  • "reason": "Actor not found."
}

RFD Schema

Create or update an RFD schema.

Defines or updates the schema used for RFD validation.

Since RFDs have a dynamic schema, this endpoint allows submitting a JSON Schema-compliant format. The schema is used by the RFD endpoints to validate incoming payloads as they pass through the system.

To update an existing schema, the entire payload must be resubmitted, including both unchanged values and any modifications.

Authorizations:
BearerToken
Request Body schema: application/json
required
required
object

The schema settings used to validate the request payloads in the RFD service. Must be in JSON schema format.

type
required
string <^[a-zA-Z0-9_-]+$>

A predefined identifier specifying the type of schema to be used in different flows in the RFD service. This type should match the type in the /request_for_data endpoints. Must be only alpabetical symbols, numbers, underscore and hypen.

created_at
string <date-time>

The time and date when the schema was created in ISO 8601.

Responses

Request samples

Content type
application/json
{
  • "type": "ACTOR",
  • "schema": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a list of RFD schems

Fetches a list of all RFD schemas.

Authorizations:
BearerToken
query Parameters
limit
number
Example: limit=5

Sets the max number of items returned in the result set for this query

offset
number
Example: offset=35

Sets the offset on the index into the list of items in the result set

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve RFD schema by type

Fetches a specific request for data schema by type.

Authorizations:
BearerToken
path Parameters
type
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "ACTOR",
  • "schema": {
    },
  • "created_at": "2019-08-24T14:15:22Z"
}
©2021 LucinityPrivacy PolicyCookie Policy