> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules & Evaluation API

> Manage transaction monitoring rules and evaluate transactions programmatically via REST API and SDKs.

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](/transaction-monitoring/building-rules).

Full API endpoint details are available in the [API Reference](https://api.corsa.finance/api-spec.json) (requires API credentials).

***

## Rule templates

### List templates

**Endpoint:** `GET /v1/rule-templates`

List available pre-built templates with pagination and filtering.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/rule-templates?limit=20&page=1
  ```

  ```typescript Javascript theme={null}
  const templates = await corsa.ruleTemplates.listRuleTemplates(
    1,  // page
    20  // limit
  );
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rule_templates.list_rule_templates import _get_kwargs

  resp = http.request(**_get_kwargs(limit=20, page=1))
  templates = resp.json()
  ```
</CodeGroup>

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

```bash theme={null}
GET /v1/rule-templates?search=withdrawal&filter.products=$eq:crypto
```

### Get a template

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

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/rule-templates/template-uuid
  ```

  ```typescript Javascript theme={null}
  const template = await corsa.ruleTemplates.getRuleTemplate("template-uuid");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rule_templates.get_rule_template import _get_kwargs

  resp = http.request(**_get_kwargs(id="template-uuid"))
  template = resp.json()
  ```
</CodeGroup>

### Copy a template

**Endpoint:** `POST /v1/rule-templates/{id}/copy`

Copy a template into your workspace as a draft rule that you can customize.

<CodeGroup>
  ```bash REST API theme={null}
  POST /v1/rule-templates/template-uuid/copy
  ```

  ```typescript Javascript theme={null}
  const draftRule = await corsa.ruleTemplates.copyRuleTemplate("template-uuid");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rule_templates.copy_rule_template import _get_kwargs

  resp = http.request(**_get_kwargs(id="template-uuid"))
  draft_rule = resp.json()
  ```
</CodeGroup>

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.

<CodeGroup>
  ```json REST API theme={null}
  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"
        }
      }
    ]
  }
  ```

  ```typescript Javascript theme={null}
  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",
        },
      },
    ],
  });
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Tip>The `CREATE_ALERT` action also accepts optional fields for alert routing: `subCategory`, `assigneeId`, and `dueDateHours`. See the [conditions reference](/transaction-monitoring/conditions-reference#create_alert) for the full list.</Tip>

#### Rule structure

| Field         | Required | Description                                                                                                                     |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Yes      | Human-readable rule name.                                                                                                       |
| `conditions`  | Yes      | Rule conditions using `all` (AND) / `any` (OR) logic. See [Conditions reference](/transaction-monitoring/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.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/rules?limit=20&page=1&sortBy=updatedAt:DESC
  ```

  ```typescript Javascript theme={null}
  const rules = await corsa.rules.listRules(1, 20);
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rules.list_rules import _get_kwargs

  resp = http.request(**_get_kwargs(limit=20, page=1))
  rules = resp.json()
  ```
</CodeGroup>

You can filter by status, name, and dates:

```bash theme={null}
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.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/rules/rule-uuid?version=2
  ```

  ```typescript Javascript theme={null}
  const rule = await corsa.rules.getRule("rule-uuid");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rules.get_rule import _get_kwargs

  resp = http.request(**_get_kwargs(id="rule-uuid"))
  rule = resp.json()
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```json REST API theme={null}
  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"
  }
  ```

  ```typescript Javascript theme={null}
  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,
        },
      ],
    },
  });
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

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

### Activate a rule

**Endpoint:** `POST /v1/rules/{id}/activate`

Activate a draft or disabled rule so it evaluates live transactions.

<CodeGroup>
  ```bash REST API theme={null}
  POST /v1/rules/rule-uuid/activate
  ```

  ```typescript Javascript theme={null}
  const activated = await corsa.rules.activateRule("rule-uuid");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rules.activate_rule import _get_kwargs

  resp = http.request(**_get_kwargs(id="rule-uuid"))
  activated = resp.json()
  ```
</CodeGroup>

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.

<CodeGroup>
  ```bash REST API theme={null}
  POST /v1/rules/rule-uuid/disable
  ```

  ```typescript Javascript theme={null}
  const disabled = await corsa.rules.disableRule("rule-uuid");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rules.disable_rule import _get_kwargs

  resp = http.request(**_get_kwargs(id="rule-uuid"))
  disabled = resp.json()
  ```
</CodeGroup>

<Note>Only active rules can be disabled. Only draft or disabled rules can be activated.</Note>

### Delete a rule

**Endpoint:** `DELETE /v1/rules/{id}`

Soft-delete a non-active (draft or disabled) rule. Active rules must be disabled first.

<CodeGroup>
  ```bash REST API theme={null}
  DELETE /v1/rules/rule-uuid?reason=No+longer+needed
  ```

  ```typescript Javascript theme={null}
  await corsa.rules.deleteRule("rule-uuid", "No longer needed");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.rules.delete_rule import _get_kwargs

  resp = http.request(**_get_kwargs(id="rule-uuid", reason="No longer needed"))
  ```
</CodeGroup>

***

## Evaluation

<Tip>You can also trigger synchronous evaluation during deposit, withdrawal, or trade ingestion by setting `evaluateSynchronously: true` on the transaction object. See [Halting transactions](/transaction-monitoring/halting-transactions#synchronous-evaluation-inline-on-ingest) for details.</Tip>

### 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.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/evaluation/evaluate
  Content-Type: application/json

  {
    "transactionId": "txn-uuid-123",
    "transactionData": {
      "amount": 75000,
      "currency": "USD",
      "type": "WITHDRAW",
      "clientId": "client-uuid-123"
    }
  }
  ```

  ```typescript Javascript theme={null}
  const result = await corsa.evaluation.evaluate({
    transactionId: "txn-uuid-123",
    transactionData: {
      amount: 75000,
      currency: "USD",
      type: "WITHDRAW",
      clientId: "client-uuid-123",
    },
  });
  ```

  ```python Python theme={null}
  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={"amount": 75000, "currency": "USD", "type": "WITHDRAW", "clientId": "client-uuid-123"},
      ),
  ))
  result = resp.json()
  ```
</CodeGroup>

#### 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.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/evaluation/rule/rule-uuid/results?page=1&pageSize=20
  ```

  ```typescript Javascript theme={null}
  const results = await corsa.evaluation.getRuleEvaluations(
    "rule-uuid",
    1,  // page
    20  // pageSize
  );
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Results by transaction

**Endpoint:** `GET /v1/evaluation/transaction/{transactionId}/results`

See all rules evaluated against a specific transaction.

<CodeGroup>
  ```bash REST API theme={null}
  GET /v1/evaluation/transaction/txn-uuid-123/results?page=1&pageSize=20
  ```

  ```typescript Javascript theme={null}
  const results = await corsa.evaluation.getTransactionEvaluations(
    "txn-uuid-123",
    1,  // page
    20  // pageSize
  );
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

***

## What's next?

<CardGroup cols={2}>
  <Card title="Ingest operations" icon="arrow-right-arrow-left" href="/api/ingesting-operations">
    Ingest deposits, withdrawals, and trades to be evaluated by your rules.
  </Card>

  <Card title="Manage alerts & cases" icon="list-check" href="/api/managing-alerts-and-cases">
    Manage alerts created by rule evaluations.
  </Card>

  <Card title="Building rules" icon="pen-ruler" href="/transaction-monitoring/building-rules">
    Use the no-code Rule Builder to create and test rules visually.
  </Card>

  <Card title="Conditions reference" icon="code" href="/transaction-monitoring/conditions-reference">
    Full reference for operators, entities, and aggregations.
  </Card>
</CardGroup>