Skip to main content

API - Transaction

Authentication required

Before calling this API, ensure you have a valid Bearer token. See API Authentication for how to obtain one.

The Transaction API serves as the primary interface for sending transactions to the Transaction Monitoring product, where they are analyzed based on defined business rules. A transaction includes information on the sender, the receiver as well as the value of the transaction itself.

The Transaction API can also be used to update a previously sent transaction, to add or correct information. Updating a transaction will overwrite the previous version of the transaction in the Transaction Monitoring product. Each API call provides a detailed response outlining how the transaction matched against active business rules, including whether and why an alert was triggered.

The API supports receiving 500 concurrent transactions per second.

When a transaction is ingested, the system responds back in under 0.5 second, in which the system does the following:

  • Analyse the transaction with the active business rules and generate alerts, if needed.
  • Send a response back to customer with the rule execution results for the transaction (indicating if any alert was generated).
  • Afterwards, the related alerts are displayed on the system' UI for analysis by the Compliance team.

Specifications of Entities in the Transaction payload​

Each entity in a transaction must be specified in exactly one of two ways:

  1. By CLM reference — use by_external_id with the entity's UUID already registered in CLM.
  2. Inline (embedded) — supply the full entity details using external_entity_type and the matching entity sub-object.

These two approaches are mutually exclusive. Defining both by_external_id and external_entity_type in the same entity object is not allowed.

Entity Specification — by_external_id​

by_external_id is a UUID string that references an entity already registered in CLM. It can be set on sender, receiver, sending_partner, or receiving_partner.

"sender": {
  "by_external_id": "9f9bf4e4-75d5-4de1-b07a-3ce43e2032b1"
}

Validation rules:

  • The value must be a valid UUID v4 format. Non-UUID strings return HTTP 400.
  • The UUID must correspond to an entity that already exists in CLM. Unknown UUIDs return HTTP 400.

Embedded Entity Details​

When by_external_id is not provided, the caller must supply the full entity details inline. This requires:

  • external_entity_type: one of "individual", "business", or "unknown"
  • The matching entity sub-object (individual, business, or unknown) with its fields
"sender": {
  "external_entity_type": "individual",
  "individual": {
    "external_id": "9f9bf4e4-75d5-4de1-b07a-3ce43e2032b1",
    "full_name": "John Doe"
  }
}

Validation rules:

  1. external_entity_type is required when by_external_id is absent.
  2. The sub-object field matching the declared external_entity_type must also be present.
  3. Only one entity-type sub-object may be present — providing both individual and business in the same entity object returns HTTP 400.

modification.created_at Validation​

The created_at field sets the time-series slot for the transaction. It is validated on every ingestion against two configurable limits:

DirectionDefault
Future limit720 hours (30 days)
Past limit1095 days (3 years)

Updating a Transaction​

When updating an existing transaction, all fields in the request may be changed, except modification.created_at. This field plays a critical role in transaction storage and must remain unchanged across updates.

additional_fields Validations​

Additional fields allow tenants to send arbitrary indexed data alongside a transaction. They are validated against expected types configured per tenant.

Supported locations​

additional_fields can be provided in five locations:

  • TransactionEventRequest.additional_fields
  • TransactionEventRequest.sender.<entity>.additional_fields
  • TransactionEventRequest.receiver.<entity>.additional_fields
  • TransactionEventRequest.sending_partner.<entity>.additional_fields
  • TransactionEventRequest.receiving_partner.<entity>.additional_fields

Supported types​

  • string
  • integer
  • number
  • boolean
  • string <date-time> — ISO-8601 timestamp in the format "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
  • array

Validation rules​

  1. Fields present in the payload but absent from the tenant's mapping configuration are accepted (ignored for indexing, no error).
  2. Fields present in the tenant's mapping configuration but with the wrong type return HTTP 400.
  3. Date fields must include a time component — date-only strings (e.g. "2024-01-01") are rejected.
  4. Changing the type of an existing mapped field is not supported and requires creating a new field instead.

Other Validations​

FieldRule
Any numeric fieldNaN values are rejected
Any string fieldEmpty strings are coerced to null
Loading ...