Rules & Evaluation API

This page covers every public API endpoint for managing transaction monitoring rules and evaluating transactions. For a visual walkthrough of the Rule Builder, see Building rules. Full API endpoint details are available in the API Reference (requires API credentials).

Rule templates

List templates

Endpoint: GET /v1/rule-templates List available pre-built templates with pagination and filtering.

GET /v1/rule-templates?limit=20&page=1

const templates = await corsa.ruleTemplates.listRuleTemplates(
  1,  // page
  20  // limit
);

from corsa_sdk.api.rule_templates.list_rule_templates import _get_kwargs

resp = http.request(**_get_kwargs(limit=20, page=1))
templates = resp.json()

You can filter templates by name, products, or typologies:

GET /v1/rule-templates?search=withdrawal&filter.products=$eq:crypto

Get a template

Endpoint: GET /v1/rule-templates/{id}

GET /v1/rule-templates/template-uuid

const template = await corsa.ruleTemplates.getRuleTemplate("template-uuid");

from corsa_sdk.api.rule_templates.get_rule_template import _get_kwargs

resp = http.request(**_get_kwargs(id="template-uuid"))
template = resp.json()

Copy a template

Endpoint: POST /v1/rule-templates/{id}/copy Copy a template into your workspace as a draft rule that you can customize.

POST /v1/rule-templates/template-uuid/copy

const draftRule = await corsa.ruleTemplates.copyRuleTemplate("template-uuid");

from corsa_sdk.api.rule_templates.copy_rule_template import _get_kwargs

resp = http.request(**_get_kwargs(id="template-uuid"))
draft_rule = resp.json()

The response contains the ruleId of the newly created draft.

Rules

Create a rule

Endpoint: POST /v1/rules Create a rule from scratch with custom conditions and actions. The rule is created in draft status.

POST /v1/rules
Content-Type: application/json

{
  "name": "High-risk withdrawal detection",
  "description": "Alert when high-risk customers make large withdrawals exceeding 50,000 USD in 24 hours",
  "conditions": {
    "all": [
      {
        "entity": "client",
        "property": "riskTier",
        "operator": "equal",
        "value": "HIGH"
      },
      {
        "entity": "transaction",
        "aggregationProperty": "amount",
        "aggregationOperator": "sum",
        "aggregationTimeType": "in_the_last",
        "aggregationTimeValue": 1,
        "aggregationTimePeriod": "days",
        "aggregationFilters": [
          {
            "property": "type",
            "operator": "equal",
            "value": "WITHDRAW"
          }
        ],
        "operator": "greaterThanInclusive",
        "value": 50000
      }
    ]
  },
  "actions": [
    {
      "type": "CREATE_ALERT",
      "config": {
        "category": "TRANSACTION_MONITORING",
        "priority": "HIGH",
        "status": "NEW"
      }
    }
  ]
}

const rule = await corsa.rules.createRule({
  name: "High-risk withdrawal detection",
  description:
    "Alert when high-risk customers make large withdrawals exceeding 50,000 USD in 24 hours",
  conditions: {
    all: [
      {
        entity: "client",
        property: "riskTier",
        operator: "equal",
        value: "HIGH",
      },
      {
        entity: "transaction",
        aggregationProperty: "amount",
        aggregationOperator: "sum",
        aggregationTimeType: "in_the_last",
        aggregationTimeValue: 1,
        aggregationTimePeriod: "days",
        aggregationFilters: [
          { property: "type", operator: "equal", value: "WITHDRAW" },
        ],
        operator: "greaterThanInclusive",
        value: 50000,
      },
    ],
  },
  actions: [
    {
      type: "CREATE_ALERT",
      config: {
        category: "TRANSACTION_MONITORING",
        priority: "HIGH",
        status: "NEW",
      },
    },
  ],
});

from corsa_sdk.api.rules.create_rule import _get_kwargs
from corsa_sdk.models.create_rule_dto import CreateRuleDto

resp = http.request(**_get_kwargs(
    body=CreateRuleDto(
        name="High-risk withdrawal detection",
        description="Alert when high-risk customers make large withdrawals exceeding 50,000 USD in 24 hours",
        conditions={"all": [
            {"entity": "client", "property": "riskTier", "operator": "equal", "value": "HIGH"},
            {"entity": "transaction", "aggregationProperty": "amount", "aggregationOperator": "sum", "aggregationTimeType": "in_the_last", "aggregationTimeValue": 1, "aggregationTimePeriod": "days", "aggregationFilters": [{"property": "type", "operator": "equal", "value": "WITHDRAW"}], "operator": "greaterThanInclusive", "value": 50000},
        ]},
        actions=[{"type": "CREATE_ALERT", "config": {"category": "TRANSACTION_MONITORING", "priority": "HIGH", "status": "NEW"}}],
    ),
))
rule = resp.json()

The CREATE_ALERT action also accepts optional fields for alert routing: subCategory, assigneeId, and dueDateHours. See the conditions reference for the full list.

Rule structure

Field	Required	Description
`name`	Yes	Human-readable rule name.
`conditions`	Yes	Rule conditions using `all` (AND) / `any` (OR) logic. See Conditions reference.
`actions`	Yes	Actions to execute when the rule matches.
`description`	No	Detailed description of the rule’s purpose.

List rules

Endpoint: GET /v1/rules List rules with pagination, sorting, and filtering.

GET /v1/rules?limit=20&page=1&sortBy=updatedAt:DESC

const rules = await corsa.rules.listRules(1, 20);

from corsa_sdk.api.rules.list_rules import _get_kwargs

resp = http.request(**_get_kwargs(limit=20, page=1))
rules = resp.json()

You can filter by status, name, and dates:

GET /v1/rules?filter.status=$eq:active&search=withdrawal

Get a rule

Endpoint: GET /v1/rules/{id} Retrieve a rule by ID. Optionally pass a version query parameter to get a specific version.

GET /v1/rules/rule-uuid?version=2

const rule = await corsa.rules.getRule("rule-uuid");

from corsa_sdk.api.rules.get_rule import _get_kwargs

resp = http.request(**_get_kwargs(id="rule-uuid"))
rule = resp.json()

Update a rule

Endpoint: PUT /v1/rules/{id} Modify a rule’s name, description, conditions, or actions. When updating an active rule, pass an optional reason for the audit log.

PUT /v1/rules/rule-uuid
Content-Type: application/json

{
  "name": "Updated rule name",
  "description": "Modified detection threshold",
  "conditions": {
    "all": [
      {
        "entity": "transaction",
        "property": "amount",
        "operator": "greaterThanInclusive",
        "value": 100000
      }
    ]
  },
  "reason": "Raised threshold after review"
}

const updated = await corsa.rules.updateRule("rule-uuid", {
  name: "Updated rule name",
  description: "Modified detection threshold",
  conditions: {
    all: [
      {
        entity: "transaction",
        property: "amount",
        operator: "greaterThanInclusive",
        value: 100000,
      },
    ],
  },
});

from corsa_sdk.api.rules.update_rule import _get_kwargs
from corsa_sdk.models.update_rule_dto import UpdateRuleDto

resp = http.request(**_get_kwargs(
    id="rule-uuid",
    body=UpdateRuleDto(
        name="Updated rule name",
        description="Modified detection threshold",
        conditions={"all": [{"entity": "transaction", "property": "amount", "operator": "greaterThanInclusive", "value": 100000}]},
    ),
))
updated = resp.json()

Updating an active rule creates a new version. The previous version is preserved in the audit history.

Activate a rule

Endpoint: POST /v1/rules/{id}/activate Activate a draft or disabled rule so it evaluates live transactions.

POST /v1/rules/rule-uuid/activate

const activated = await corsa.rules.activateRule("rule-uuid");

from corsa_sdk.api.rules.activate_rule import _get_kwargs

resp = http.request(**_get_kwargs(id="rule-uuid"))
activated = resp.json()

You can optionally pass a reason in the request body for audit purposes.

Disable a rule

Endpoint: POST /v1/rules/{id}/disable Pause an active rule. Disabled rules do not evaluate transactions but can be re-activated.

POST /v1/rules/rule-uuid/disable

const disabled = await corsa.rules.disableRule("rule-uuid");

from corsa_sdk.api.rules.disable_rule import _get_kwargs

resp = http.request(**_get_kwargs(id="rule-uuid"))
disabled = resp.json()

Only active rules can be disabled. Only draft or disabled rules can be activated.

Delete a rule

Endpoint: DELETE /v1/rules/{id} Soft-delete a non-active (draft or disabled) rule. Active rules must be disabled first.

DELETE /v1/rules/rule-uuid?reason=No+longer+needed

await corsa.rules.deleteRule("rule-uuid", "No longer needed");

from corsa_sdk.api.rules.delete_rule import _get_kwargs

resp = http.request(**_get_kwargs(id="rule-uuid", reason="No longer needed"))

Evaluation

You can also trigger synchronous evaluation during deposit, withdrawal, trade, or transfer ingestion by setting evaluateSynchronously: true on the transaction object. See Halting transactions for details.

Evaluate a transaction

Endpoint: POST /v1/evaluation/evaluate Evaluate a transaction against all active rules on-demand. This is useful for testing or evaluating transactions outside the normal ingestion flow. On-demand evaluation does not save the transaction and does not create alerts. Use the response body to inspect the decision and matching rules.

POST /v1/evaluation/evaluate
Content-Type: application/json

{
  "transactionId": "txn-uuid-123",
  "transactionData": {
    "type": "TRANSFER",
    "amount": { "amount": 75000, "currency": "USD" },
    "convertedAmount": { "amount": 75000, "currency": "USD" },
    "from": {
      "client": { "id": "sender-client-uuid" },
      "bankAccount": { "id": "sender-bank-account-uuid" }
    },
    "to": {
      "client": { "id": "recipient-client-uuid" },
      "bankAccount": { "id": "recipient-bank-account-uuid" }
    },
    "initiatedAt": "2024-06-15T08:30:00Z",
    "currentStatus": { "type": "PENDING", "timestamp": "2024-06-15T08:30:00Z" }
  }
}

const result = await corsa.evaluation.evaluate({
  transactionId: "txn-uuid-123",
  transactionData: {
    type: "TRANSFER",
    amount: { amount: 75000, currency: "USD" },
    convertedAmount: { amount: 75000, currency: "USD" },
    from: {
      client: { id: "sender-client-uuid" },
      bankAccount: { id: "sender-bank-account-uuid" },
    },
    to: {
      client: { id: "recipient-client-uuid" },
      bankAccount: { id: "recipient-bank-account-uuid" },
    },
    initiatedAt: "2024-06-15T08:30:00Z",
    currentStatus: { type: "PENDING", timestamp: "2024-06-15T08:30:00Z" },
  },
});

from corsa_sdk.api.evaluation.evaluate import _get_kwargs
from corsa_sdk.models.evaluation_request_dto import EvaluationRequestDto

resp = http.request(**_get_kwargs(
    body=EvaluationRequestDto(
        transaction_id="txn-uuid-123",
        transaction_data={
            "type": "TRANSFER",
            "amount": {"amount": 75000, "currency": "USD"},
            "convertedAmount": {"amount": 75000, "currency": "USD"},
            "from": {
                "client": {"id": "sender-client-uuid"},
                "bankAccount": {"id": "sender-bank-account-uuid"},
            },
            "to": {
                "client": {"id": "recipient-client-uuid"},
                "bankAccount": {"id": "recipient-bank-account-uuid"},
            },
            "initiatedAt": "2024-06-15T08:30:00Z",
            "currentStatus": {"type": "PENDING", "timestamp": "2024-06-15T08:30:00Z"},
        },
    ),
))
result = resp.json()

For velocity and other client-scoped rules, identify the relevant parties with from.client.id and to.client.id. You can send referenceId instead of id when it is the stable identifier from your system. A flat clientId field does not identify a transfer’s sender and recipient. For bank-account rules, ingest the bank accounts first and send from.bankAccount.id and to.bankAccount.id. Corsa loads bank-account facts from those IDs. Account or routing numbers in the evaluation payload do not replace the account IDs. For aggregation rules, aggregationIncludeCurrentTransaction controls whether the transaction in this request is part of the result. When it is true, Corsa evaluates history plus the current transaction. When it is omitted or false, Corsa evaluates history only.

Evaluation response

Field	Description
`decision`	`ALLOW` if no rules matched with a halt action, `FREEZE` if at least one matched rule includes `HALT_TRANSACTION`.
`triggeredRuleIds`	Array of rule IDs that matched.
`matches`	Detailed match information per rule, including condition results.
`evaluatedAt`	Timestamp of the evaluation.
`latencyMs`	Processing time in milliseconds.

Results by rule

Endpoint: GET /v1/evaluation/rule/{ruleId}/results See all transactions evaluated against a specific rule.

GET /v1/evaluation/rule/rule-uuid/results?page=1&pageSize=20

const results = await corsa.evaluation.getRuleEvaluations(
  "rule-uuid",
  1,  // page
  20  // pageSize
);

from corsa_sdk.api.evaluation.get_rule_evaluations import _get_kwargs

resp = http.request(**_get_kwargs(rule_id="rule-uuid", page=1, page_size=20))
results = resp.json()

Results by transaction

Endpoint: GET /v1/evaluation/transaction/{transactionId}/results See all rules evaluated against a specific transaction. Use the Corsa transaction UUID for {transactionId}, not your integration referenceId.

GET /v1/evaluation/transaction/txn-uuid-123/results?page=1&pageSize=20

const results = await corsa.evaluation.getTransactionEvaluations(
  "txn-uuid-123",
  1,  // page
  20  // pageSize
);

from corsa_sdk.api.evaluation.get_transaction_evaluations import _get_kwargs

resp = http.request(**_get_kwargs(transaction_id="txn-uuid-123", page=1, page_size=20))
results = resp.json()

What’s next?

Ingest operations

Ingest deposits, withdrawals, and trades to be evaluated by your rules.

Manage alerts & cases

Manage alerts created by rule evaluations.

Building rules

Use the no-code Rule Builder to create and test rules visually.

Conditions reference

Full reference for operators, entities, and aggregations.

Transaction Monitoring

API

Intelligence Hub

Rule templates

List templates

Get a template

Copy a template

Rules

Create a rule

Rule structure

List rules

Get a rule

Update a rule

Activate a rule

Disable a rule

Delete a rule

Evaluation

Evaluate a transaction

Evaluation response

Results by rule

Results by transaction

What’s next?

Ingest operations

Manage alerts & cases

Building rules

Conditions reference

​Rule templates

​List templates

​Get a template

​Copy a template

​Rules

​Create a rule

​Rule structure

​List rules

​Get a rule

​Update a rule

​Activate a rule

​Disable a rule

​Delete a rule

​Evaluation

​Evaluate a transaction

​Evaluation response

​Results by rule

​Results by transaction

​What’s next?

Ingest operations

Manage alerts & cases

Building rules

Conditions reference

Rule templates

List templates

Get a template

Copy a template

Rules

Create a rule

Rule structure

List rules

Get a rule

Update a rule

Activate a rule

Disable a rule

Delete a rule

Evaluation

Evaluate a transaction

Evaluation response

Results by rule

Results by transaction

What’s next?