> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Rule
> Create a CUSTOM transaction-monitoring rule. Titles are unique per application (duplicate -> 400). A `change_status` action targeting `AWAITING_USER` must carry `workflow_id`. Rules created in ACTIVE mode apply to new transactions immediately - the recommended workflow is create in TEST mode, backtest, then switch mode to ACTIVE.
export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
const [copied, setCopied] = React.useState(false);
const handleCopy = e => {
e.stopPropagation();
if (!prompt) return;
navigator.clipboard.writeText(prompt.trim()).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 2000);
});
};
const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
return
{}
{title}
{}
{prompt.trim()}
{}
Paste into
{agents.map(name => {name})}
;
};
400
"description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
"category": "finance", // required: finance, aml_ctf, anomaly_detection, fatf, device_intelligence, crypto_monitoring, travel_rule, responsible_gaming, e_commerce, ...
"mode": "TEST", // required: TEST (recommended start - evaluates, never affects transactions), ACTIVE, DISABLED
"evaluation_mode": "ALL", // ALL = every condition must match, ANY = at least one
"scope": {"transaction_types": ["finance"], "directions": ["INBOUND"]}, // constrains the transaction being evaluated; optional keys: transaction_types, directions (INBOUND/OUTBOUND), action_types
"conditions": [ // read the transaction being evaluated, never the history window
{"field": "currency", "operator": "eq", "value": "EUR"},
{"field": "amount", "operator": "lt", "value": 10000}
],
"aggregation": [ // velocity over the history window: ALL entries must match
{"metric": "count", "operator": "gte", "value": 20, "window": "30d",
"filters": {"direction": "INBOUND", "transaction_type": "finance", "currency": "EUR", "subject_vendor_data": "__current__"}},
{"metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d",
"filters": {"direction": "INBOUND", "transaction_type": "finance", "currency": "EUR", "subject_vendor_data": "__current__"}}
],
"actions": [{"type": "add_score", "value": 35}]
}
Schema essentials:
- Condition operators: eq, ne, gt, gte, lt, lte, in, not_in, contains, not_contains, contains_any (list of strings), regex, fuzzy_match (needs "score" 0-100), exists/is_not_empty/is_not_null, not_exists/is_empty/is_null.
- Condition fields include amount, preferred_currency_amount, direction, action_type, payment_details, subject_vendor_data, counterparty_country, subject_device_fingerprint, subject_payment_method_*, travel_rule_status, tags, and custom_values. for your own custom_properties.
- value_type turns "value" into a List UUID ("list"), another field path ("field"), or a relative date ("relative_date").
- Aggregation windows: m (MINUTES), h, d. A filter value of "__current__" means same-as-the-evaluated-transaction.
- Conditions and aggregation filters are NOT interchangeable. A condition constrains only the transaction being evaluated; an aggregation filter constrains only the historical window, and it compares by equality or list membership - there is no lt/gte filter. Express a range over the window as a max/min aggregation (e.g. max amount lt 10000 with currency pinned to EUR keeps every transaction in that window under 10,000 EUR), and repeat direction/currency/transaction_type on BOTH halves when the rule promises them - otherwise the rule fires on transactions it never meant to cover.
- Actions: add_score {value}, change_status {value, workflow_id (REQUIRED for AWAITING_USER)}, add_tags {tag_uuid|tag_name, tag_color}, add_note {note}, add_to_list {list_id}, open_case {blueprint, grouping, attach_matched_transaction}.
Recommended workflow:
1. Create in mode TEST.
2. POST /v3/transactions/rules/backtest/ with the SAME conditions, aggregation, evaluation_mode and scope to see matches over your history. Omitted conditions, aggregation and scope add no constraints of their own; dropping scope can include directions or transaction types the saved rule skips. Omitted evaluation_mode defaults to ALL (which can reduce matches for an ANY rule), and omitted period_days defaults to 90 days, not unlimited history.
3. PATCH the rule to mode ACTIVE once the numbers look right.
Sandbox fixtures for this example: at least 20 inbound EUR finance transactions for the same subject within 30 days, each with raw amount below 10000. No normalized amount is required. Sandbox ingestion does not evaluate rules; call backtest explicitly.
Failure modes:
- 400 - duplicate title, unknown operator/metric, malformed window, invalid scope direction, contains_any without a list, fuzzy_match without a score, or AWAITING_USER without workflow_id. The body names the exact index and problem.
- 401 - missing or malformed x-api-key.
Full guide: /transaction-monitoring/rules-api.`}
/>
## OpenAPI
````yaml POST /v3/transactions/rules/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/transactions/rules/:
post:
tags:
- Transactions
summary: Create rule
description: >-
Create a CUSTOM transaction-monitoring rule. Titles are unique per
application (duplicate -> 400). A `change_status` action targeting
`AWAITING_USER` must carry `workflow_id`. Rules created in ACTIVE mode
apply to new transactions immediately - the recommended workflow is
create in TEST mode, backtest, then switch mode to ACTIVE.
operationId: createTransactionRule
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRuleCreateRequest'
example:
title: Structuring - inbound (custom)
description: 20+ inbound EUR transfers, all under 10,000 EUR, 30 days
category: finance
mode: TEST
evaluation_mode: ALL
scope:
transaction_types:
- finance
directions:
- INBOUND
conditions:
- field: currency
operator: eq
value: EUR
- field: amount
operator: lt
value: 10000
aggregation:
- metric: count
operator: gte
value: 20
window: 30d
filters:
direction: INBOUND
transaction_type: finance
subject_vendor_data: __current__
currency: EUR
- metric: max
field: amount
operator: lt
value: 10000
window: 30d
filters:
direction: INBOUND
transaction_type: finance
subject_vendor_data: __current__
currency: EUR
actions:
- type: add_score
value: 35
responses:
'201':
description: The created rule.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRuleDetail'
'400':
description: >-
Validation error - duplicate title, unknown operator/metric,
malformed window, invalid scope direction, or AWAITING_USER without
workflow_id.
content:
application/json:
schema:
type: object
example:
title:
- A rule with this name already exists.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X POST 'https://verification.didit.me/v3/transactions/rules/'
\
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"title": "Structuring - inbound (custom)", "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days", "category": "finance", "mode": "TEST", "evaluation_mode": "ALL", "scope": {"transaction_types": ["finance"], "directions": ["INBOUND"]}, "conditions": [{"field": "currency", "operator": "eq", "value": "EUR"}, {"field": "amount", "operator": "lt", "value": 10000}], "aggregation": [{"metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": {"direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR"}}, {"metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": {"direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR"}}], "actions": [{"type": "add_score", "value": 35}]}'
- lang: python
label: Python
source: |-
import os
import requests
rule = {
"title": "Structuring - inbound (custom)",
"description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
"category": "finance",
"mode": "TEST",
"evaluation_mode": "ALL",
"scope": {
"transaction_types": [
"finance"
],
"directions": [
"INBOUND"
]
},
"conditions": [
{
"field": "currency",
"operator": "eq",
"value": "EUR"
},
{
"field": "amount",
"operator": "lt",
"value": 10000
}
],
"aggregation": [
{
"metric": "count",
"operator": "gte",
"value": 20,
"window": "30d",
"filters": {
"direction": "INBOUND",
"transaction_type": "finance",
"subject_vendor_data": "__current__",
"currency": "EUR"
}
},
{
"metric": "max",
"field": "amount",
"operator": "lt",
"value": 10000,
"window": "30d",
"filters": {
"direction": "INBOUND",
"transaction_type": "finance",
"subject_vendor_data": "__current__",
"currency": "EUR"
}
}
],
"actions": [
{
"type": "add_score",
"value": 35
}
]
}
resp = requests.post(
'https://verification.didit.me/v3/transactions/rules/',
headers={'x-api-key': os.environ['DIDIT_API_KEY']},
json=rule,
timeout=15,
)
resp.raise_for_status()
print(resp.json()['uuid'], resp.json()['mode'])
- lang: javascript
label: JavaScript
source: >-
const rule = {
"title": "Structuring - inbound (custom)",
"description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
"category": "finance",
"mode": "TEST",
"evaluation_mode": "ALL",
"scope": {
"transaction_types": [
"finance"
],
"directions": [
"INBOUND"
]
},
"conditions": [
{
"field": "currency",
"operator": "eq",
"value": "EUR"
},
{
"field": "amount",
"operator": "lt",
"value": 10000
}
],
"aggregation": [
{
"metric": "count",
"operator": "gte",
"value": 20,
"window": "30d",
"filters": {
"direction": "INBOUND",
"transaction_type": "finance",
"subject_vendor_data": "__current__",
"currency": "EUR"
}
},
{
"metric": "max",
"field": "amount",
"operator": "lt",
"value": 10000,
"window": "30d",
"filters": {
"direction": "INBOUND",
"transaction_type": "finance",
"subject_vendor_data": "__current__",
"currency": "EUR"
}
}
],
"actions": [
{
"type": "add_score",
"value": 35
}
]
};
const resp = await
fetch('https://verification.didit.me/v3/transactions/rules/', {
method: 'POST',
headers: {
'x-api-key': process.env.DIDIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(rule),
});
if (!resp.ok) throw new Error(await resp.text());
const created = await resp.json();
console.log(created.uuid, created.mode);
components:
schemas:
TransactionRuleCreateRequest:
type: object
required:
- title
- category
- mode
properties:
title:
type: string
description: >-
Rule name. Unique per application among non-deleted rules;
duplicates return 400.
description:
type: string
nullable: true
category:
type: string
description: >-
Risk theme used for grouping and reporting, e.g. finance, aml_ctf,
anomaly_detection, fatf, device_intelligence, crypto_monitoring,
travel_rule, responsible_gaming, e_commerce.
mode:
type: string
enum:
- ACTIVE
- DISABLED
- TEST
description: >-
ACTIVE evaluates live. TEST evaluates and records rule runs but
never touches score or status - the recommended starting mode.
DISABLED is skipped.
evaluation_mode:
type: string
enum:
- ALL
- ANY
default: ALL
description: >-
Whether every condition must match (ALL) or at least one (ANY).
Ignored when conditions use group_index.
scope:
$ref: '#/components/schemas/TransactionRuleScope'
conditions:
type: array
items:
$ref: '#/components/schemas/TransactionRuleCondition'
aggregation:
type: array
items:
$ref: '#/components/schemas/TransactionRuleAggregation'
actions:
type: array
items:
$ref: '#/components/schemas/TransactionRuleAction'
metadata:
type: object
description: Free-form metadata stored on the rule.
description: >-
Creates a CUSTOM rule. Rules in ACTIVE mode take effect immediately for
new transactions - create in TEST mode and backtest first.
TransactionRuleDetail:
type: object
properties:
uuid:
type: string
format: uuid
title:
type: string
description: >-
Rule name. Unique per application among non-deleted rules;
duplicates return 400.
description:
type: string
nullable: true
category:
type: string
description: >-
Risk theme used for grouping and reporting, e.g. finance, aml_ctf,
anomaly_detection, fatf, device_intelligence, crypto_monitoring,
travel_rule, responsible_gaming, e_commerce.
mode:
type: string
enum:
- ACTIVE
- DISABLED
- TEST
description: >-
ACTIVE evaluates live. TEST evaluates and records rule runs but
never touches score or status - the recommended starting mode.
DISABLED is skipped.
evaluation_mode:
type: string
enum:
- ALL
- ANY
default: ALL
description: >-
Whether every condition must match (ALL) or at least one (ANY).
Ignored when conditions use group_index.
scope:
$ref: '#/components/schemas/TransactionRuleScope'
conditions:
type: array
items:
$ref: '#/components/schemas/TransactionRuleCondition'
aggregation:
type: array
items:
$ref: '#/components/schemas/TransactionRuleAggregation'
actions:
type: array
items:
$ref: '#/components/schemas/TransactionRuleAction'
metadata:
type: object
description: Free-form metadata stored on the rule.
severity:
type: string
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
nullable: true
description: >-
Informational severity carried by library rules; not settable on
custom rules.
source:
type: string
enum:
- PRESET
- CUSTOM
description: >-
PRESET rules come from the library (install/uninstall, mode-only
edits); CUSTOM rules are fully yours.
library_key:
type: string
nullable: true
description: Stable library identifier; null for custom rules.
latest_triggered_at:
type: string
format: date-time
nullable: true
run_count:
type: integer
description: How many transactions matched this rule.
approved_count:
type: integer
reviewed_count:
type: integer
declined_count:
type: integer
awaiting_user_count:
type: integer
approved_pct:
type: number
reviewed_pct:
type: number
declined_pct:
type: number
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
TransactionRuleScope:
type: object
properties:
transaction_types:
type: array
items:
type: string
description: >-
Restrict to transaction types, e.g. finance, kyc, travel_rule,
user_event. Empty or missing = no restriction.
directions:
type: array
items:
type: string
enum:
- INBOUND
- OUTBOUND
description: Restrict to transaction directions (case-insensitive on write).
action_types:
type: array
items:
type: string
description: Restrict to your action_type values, e.g. withdrawal, deposit.
description: >-
Which transactions the rule applies to. Only these three keys are
accepted.
TransactionRuleCondition:
type: object
required:
- field
- operator
properties:
field:
type: string
description: >-
Transaction field path to evaluate. Core fields: amount, currency,
direction, action_type, score, severity, transaction_type,
payment_details, preferred_currency_amount (falls back to
amount_in_default_currency), default_currency_code, subject_country,
counterparty_country, subject_vendor_data, counterparty_vendor_data,
subject_device_fingerprint, counterparty_device_fingerprint,
subject_browser_family, subject_browser_version, subject_platform,
subject_accept_language, subject_session_age_ms, subject_ip_country,
counterparty_ip_country, subject_ip_address,
counterparty_ip_address, subject_payment_method_type,
subject_payment_method_country, subject_payment_method_fingerprint,
subject_payment_method_account_id (and the
counterparty_payment_method_* equivalents), travel_rule_status,
travel_rule_required, travel_rule_obligations_count,
subject_days_since_previous_transaction, tags, and
custom_values. for any key submitted in custom_properties on
transaction create. Country-code fields accept ISO-2 or ISO-3; both
sides are normalized to ISO-3 before comparison.
operator:
type: string
enum:
- eq
- ne
- gt
- gte
- lt
- lte
- in
- not_in
- contains
- not_contains
- contains_any
- regex
- fuzzy_match
- exists
- is_not_empty
- is_not_null
- not_exists
- is_empty
- is_null
description: >-
Comparison operator. in/not_in test membership (value may be a list
or a single scalar). contains/not_contains are case-insensitive
substring checks against a string value. contains_any takes a list
of strings and matches when any is a case-insensitive substring of
the field value. regex matches the value pattern against the field.
fuzzy_match compares against the value string with the required
`score` threshold (0-100). gt/gte/lt/lte never match when either
side is missing. exists/is_not_empty/is_not_null (aliases) and
not_exists/is_empty/is_null (aliases) are presence checks that
ignore `value`.
value:
description: >-
Comparison value. Its shape depends on the operator and value_type;
omit for the presence-check operators.
value_type:
type: string
enum:
- list
- field
- relative_date
description: >-
Optional value interpretation. `list`: value is a List UUID and the
list's entries become the comparison value. `field`: value is
another field path, compared field-to-field. `relative_date`: value
is a relative-date object, e.g. {"direction": "past", "unit":
"days", "amount": 30}.
score:
type: number
minimum: 0
maximum: 100
description: >-
Required when operator is fuzzy_match: the 0-100 similarity
threshold.
group_index:
type: integer
description: >-
Optional grouped logic. When any condition carries group_index,
conditions sharing an index form a group and grouped evaluation
replaces evaluation_mode.
group_logic:
type: string
enum:
- AND
- OR
default: AND
description: How conditions combine WITHIN a group.
groups_logic:
type: string
enum:
- AND
- OR
default: OR
description: >-
How group outcomes combine ACROSS groups. Read from the first
condition.
description: >-
A condition reads only the transaction being evaluated - it never
filters the aggregation window.
TransactionRuleAggregation:
type: object
required:
- value
properties:
metric:
type: string
enum:
- count
- sum
- max
- min
- avg
- distinct_count
default: count
description: >-
How the matching historical transactions are aggregated.
unique_count is accepted as an alias of distinct_count.
field:
type: string
default: amount
description: >-
Field aggregated by sum/max/min/avg/distinct_count. Ignored for
count.
operator:
type: string
enum:
- eq
- ne
- gt
- gte
- lt
- lte
default: eq
description: Comparison applied to the computed metric.
value:
type: number
description: Threshold the computed metric is compared against.
window:
type: string
pattern: ^\d+(m|h|d)$
default: 1d
description: >-
Look-back window ending at the transaction's txn_date: m
(MINUTES, not months), h (hours) or d (days), e.g. 30m, 24h,
7d, 30d.
filters:
type: object
additionalProperties: true
description: >-
Narrows which historical transactions are aggregated. Keys are field
paths from the condition field catalog; a value of "__current__"
resolves to the same field's value on the transaction being
evaluated (e.g. {"subject_vendor_data": "__current__"} scopes the
window to the same subject), and a list value means membership.
Filters compare by equality or membership ONLY - there is no lt/gte
filter, so a range such as "historical transactions under 10,000"
cannot be expressed here. Put the range on the metric instead
(metric max with operator lt keeps every transaction in the window
below the threshold).
description: >-
Velocity check over the application's historical transactions inside the
window. Every aggregation entry must match for the rule to match,
regardless of evaluation_mode. An aggregation constrains only the
window; the transaction being evaluated is constrained by scope and
conditions, so repeat direction, currency or transaction_type on both
halves when the rule promises them.
TransactionRuleAction:
oneOf:
- type: object
required:
- type
- value
properties:
type:
type: string
enum:
- add_score
value:
type: integer
description: Points added to the transaction's risk score. May be negative.
description: >-
Add points to the transaction's cumulative risk score; the total
decides the status via the application's review/decline thresholds.
- type: object
required:
- type
- value
properties:
type:
type: string
enum:
- change_status
value:
type: string
enum:
- APPROVED
- IN_REVIEW
- DECLINED
- AWAITING_USER
description: >-
Status to set immediately, regardless of score. Alias key:
status.
workflow_id:
type: string
format: uuid
description: >-
REQUIRED when value is AWAITING_USER: the verification workflow
the subject is asked to complete. Alias key:
remediation_workflow_id. Didit creates a hosted remediation
session for the subject when the rule fires.
description: >-
Directly set the transaction status. DECLINED always wins across
matched rules.
- type: object
required:
- type
properties:
type:
type: string
enum:
- add_tags
tag_uuid:
type: string
format: uuid
description: Existing application tag to attach.
tag_name:
type: string
description: >-
Tag name to attach; created on first use (stored uppercased).
Provide tag_uuid or tag_name.
tag_color:
type: string
description: 'Hex color used when tag_name creates a new tag, e.g. #007AFE.'
description: Attach an application tag to the matched transaction.
- type: object
required:
- type
- note
properties:
type:
type: string
enum:
- add_note
note:
type: string
description: >-
Note text attached to the transaction (author: Rule Engine).
Alias key: value.
description: Attach an automated analyst note to the matched transaction.
- type: object
required:
- type
- list_id
properties:
type:
type: string
enum:
- add_to_list
list_id:
type: string
format: uuid
description: List to add the subject's vendor_data to.
description: >-
Add the subject's vendor_data to a blocklist, allowlist or custom
list.
- type: object
required:
- type
properties:
type:
type: string
enum:
- open_case
blueprint:
type: string
format: uuid
description: >-
Case blueprint UUID; defaults to the application's default
blueprint.
grouping:
type: string
enum:
- by_applicant
- by_rule_and_applicant
description: >-
Whether repeat matches join one case per applicant or one per
rule+applicant.
attach_matched_transaction:
type: boolean
description: Attach the matched transaction to the case.
description: >-
Open (or add to) an investigation case. Only the first open_case
action on a rule is applied.
description: >-
One rule action. A rule can carry several; all are applied together when
it matches. Rules in TEST mode record what they would have done without
applying any action.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your application's API key, from Developers -> API keys in the Business
Console. The primary key has full access. A named key can be scoped:
none, read or write per resource, limited to some workflows or to
approved sessions, to a list of IP addresses, and to an expiry date. 401
means the key is missing, wrong, revoked or expired; 403 means the key
has no access to this resource or action, or the request came from an
address outside its IP list; 404 on a session route means the session is
outside the key's workflows or statuses. A key without media access
receives image, video and PDF URLs as null, and a key without sessions
write receives session links and tokens as null. See
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.