Managing Rules via API and MCP

Every rule capability of the Business Console is also available programmatically: through the Management API with your application API key, and through the Didit MCP for AI agents acting as a signed-in console user. Use them to manage rules from code, keep rule sets in version control, or let an AI assistant build and migrate rules for you.

When to use which surface

Surface	Auth	Best for
Business Console	Console login	Human review of every change; visual rule building and backtesting
Management API	`x-api-key`	Automation from your backend, rule sets in code, CI-managed rule deployments
Didit MCP	Sign in with Didit (OAuth)	AI assistants and agents: the Didit console Copilot, Claude, Cursor, or any MCP client

The endpoints

Endpoint	Purpose
`GET /v3/transactions/rules/`	List rules with filters and performance ordering
`POST /v3/transactions/rules/`	Create a custom rule
`GET /v3/transactions/rules/{rule_uuid}/`	Read one rule with execution counters
`PATCH /v3/transactions/rules/{rule_uuid}/`	Update a custom rule; switch any rule’s mode
`DELETE /v3/transactions/rules/{rule_uuid}/`	Delete a custom rule (permanent)
`POST /v3/transactions/rules/backtest/`	Evaluate a hypothetical rule against your history
`GET /v3/transactions/rules/library/`	Browse the 150+ preset library with install status
`POST /v3/transactions/rules/install/`	Install presets by key or bundle
`DELETE /v3/transactions/rules/install/`	Uninstall presets by key or bundle

The matching MCP tools are didit_transaction_rule_list, didit_transaction_rule_get, didit_transaction_rule_create, didit_transaction_rule_update, didit_transaction_rule_delete, didit_transaction_rule_backtest, didit_transaction_rule_library_list, didit_transaction_rule_install, and didit_transaction_rule_uninstall - see the MCP tool reference. The full schema - the field catalog, all 19 condition operators, velocity windows, grouped conditions, and the six action types - is documented on the Rules & Scoring page and embedded in the API reference.

Create, backtest, activate

The safe rollout pattern for any new rule:

Create the rule in TEST mode

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)",
    "category": "finance",
    "mode": "TEST",
    "evaluation_mode": "ALL",
    "scope": {"transaction_types": ["finance"]},
    "conditions": [{"field": "amount", "operator": "lt", "value": 10000}],
    "aggregation": [{
      "metric": "count", "operator": "gte", "value": 20, "window": "30d",
      "filters": {"direction": "INBOUND", "subject_vendor_data": "__current__"}
    }],
    "actions": [{"type": "add_score", "value": 35}]
  }'

A TEST rule evaluates on every new transaction and records what it would have matched, but never touches the transaction’s score or status.

Backtest against your history

curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "conditions": [{"field": "amount", "operator": "lt", "value": 10000}],
    "aggregation": [{
      "metric": "count", "operator": "gte", "value": 20, "window": "30d",
      "filters": {"direction": "INBOUND", "subject_vendor_data": "__current__"}
    }],
    "period_days": 90
  }'

{ "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }

A surprising matched count means the thresholds need tuning before the rule can act on anything.

Activate

curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "ACTIVE"}'

The rule applies to all new transactions immediately.

Migrating rules from another provider

Because rule creation is a plain API call with a fully documented schema, an AI assistant can translate another provider’s rule export into Didit rules for you.

Export your rules from the current provider - most tools export to CSV or Excel.
Drop the file into the Didit console assistant (or any MCP-connected agent like Claude with the Didit MCP attached). Spreadsheets are converted to text automatically.
The assistant maps each row to the Didit schema - conditions, velocity windows, actions - and shows you the mapping, calling out anything that has no Didit equivalent, before creating anything.
On your go-ahead it creates the rules in TEST mode, backtests them against your own transaction history, and reports created / failed / unmappable rows.
Review the numbers and activate the rules that look right, from the console or with a PATCH {"mode": "ACTIVE"}.

A provider export like this:

Rule Name,Condition,Threshold,Window (days),Action
Structuring - Small Transfers,count of outbound transfers under amount,20 transfers under 10000 EUR,30,Flag for review
High Value Wire,single transaction amount,> 50000 USD,,Decline

becomes rules like this:

{
  "title": "Structuring - Small Transfers",
  "category": "finance",
  "mode": "TEST",
  "conditions": [{"field": "amount", "operator": "lt", "value": 10000}],
  "aggregation": [{
    "metric": "count", "operator": "gte", "value": 20, "window": "30d",
    "filters": {"direction": "OUTBOUND", "subject_vendor_data": "__current__"}
  }],
  "actions": [
    {"type": "add_score", "value": 35},
    {"type": "change_status", "value": "IN_REVIEW"}
  ]
}

Before recreating a provider’s rule as custom, check the rule library: Didit ships 150+ presets covering the common typologies (structuring, velocity, sanctions exposure, device reuse, crypto risk), and installing a preset is one call.

Validation errors are precise on purpose

The create and update endpoints validate conditions, aggregation, and scope values against exactly what the rule engine accepts: unknown operators or metrics, malformed windows ("30days" instead of "30d"), invalid scope directions, contains_any without a list, fuzzy_match without a score, and change_status to AWAITING_USER without a workflow_id all return a 400 naming the index and the problem - instead of storing a rule that silently never matches. Agents and scripts should read the error body and fix the payload. Extra scope keys beyond transaction_types, directions, and action_types are stored but ignored by the engine, matching how the Business Console has always saved them.

Next steps

Rules & Scoring

The full rule schema: fields, operators, velocity windows, actions.

Create Rule API

Endpoint reference with request and response schemas.

Rules library

The 150+ preset catalogue and its bundles.

MCP overview

Connect an AI agent to your Didit workspace.

Getting Started

Features

Reference

Console

When to use which surface

The endpoints

Create, backtest, activate

Migrating rules from another provider

Validation errors are precise on purpose

Next steps

Rules & Scoring

Create Rule API

Rules library

MCP overview

​When to use which surface

​The endpoints

​Create, backtest, activate

​Migrating rules from another provider

​Validation errors are precise on purpose

​Next steps

Rules & Scoring

Create Rule API

Rules library

MCP overview

When to use which surface

The endpoints

Create, backtest, activate

Migrating rules from another provider

Validation errors are precise on purpose

Next steps