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

# Orchestration Rules

> Automate verification decisions with a flexible rules engine.

Orchestration Rules let you define conditional logic that automatically evaluates verification data and triggers actions -- approve, decline, escalate, or route sessions -- without writing backend code.

## How It Works

<Steps>
  <Step title="Define conditions">
    Create rules using conditions that evaluate session data: risk scores, document types, country of origin, AML results, and more.
  </Step>

  <Step title="Set actions">
    Assign actions that fire when conditions are met: approve, decline, flag for review, send a webhook, or trigger a follow-up step.
  </Step>

  <Step title="Prioritize rules">
    Rules are evaluated in priority order. The first matching rule's action is applied. If no rules match, the default action is used.
  </Step>

  <Step title="Monitor outcomes">
    View rule execution logs in the dashboard to understand which rules fired and why.
  </Step>
</Steps>

## Creating a Rule

Create rules via the API or in **Dashboard > Orchestration > Rules**.

```json theme={null}
POST /v1/orchestration/rules
{
  "name": "Block high-risk countries",
  "description": "Decline sessions from sanctioned jurisdictions",
  "priority": 10,
  "enabled": true,
  "conditions": [
    {
      "field": "document.issuing_country",
      "operator": "in",
      "value": ["KP", "IR", "SY", "CU"]
    }
  ],
  "action": {
    "type": "decline",
    "reason": "Sanctioned jurisdiction"
  }
}
```

## Conditions

Each condition evaluates a field against a value using an operator.

| Field      | Type   | Description                               |
| ---------- | ------ | ----------------------------------------- |
| `field`    | string | The data field to evaluate (dot notation) |
| `operator` | string | Comparison operator                       |
| `value`    | mixed  | The value to compare against              |

### Available Fields

| Field Path                 | Type    | Description                                             |
| -------------------------- | ------- | ------------------------------------------------------- |
| `risk_score`               | integer | Overall session risk score (0-100)                      |
| `document.type`            | string  | Document type: `passport`, `id_card`, `drivers_license` |
| `document.issuing_country` | string  | ISO 3166-1 alpha-2 country code                         |
| `aml.status`               | string  | AML result: `clear`, `match`, `pending`                 |
| `aml.highest_score`        | number  | Highest AML match score (0-1)                           |
| `liveness.score`           | number  | Liveness score (0-100)                                  |
| `device.risk_score`        | integer | Device fingerprint risk score (0-100)                   |
| `device.fraud_signals`     | array   | Detected fraud signals                                  |
| `person.age`               | integer | Calculated age from date of birth                       |
| `person.nationality`       | string  | Nationality ISO code                                    |

### Operators

| Operator   | Description           | Example                                       |
| ---------- | --------------------- | --------------------------------------------- |
| `eq`       | Equals                | `"operator": "eq", "value": "passport"`       |
| `neq`      | Not equals            | `"operator": "neq", "value": "clear"`         |
| `gt`       | Greater than          | `"operator": "gt", "value": 75`               |
| `gte`      | Greater than or equal | `"operator": "gte", "value": 18`              |
| `lt`       | Less than             | `"operator": "lt", "value": 50`               |
| `lte`      | Less than or equal    | `"operator": "lte", "value": 30`              |
| `in`       | Value in list         | `"operator": "in", "value": ["US", "GB"]`     |
| `not_in`   | Value not in list     | `"operator": "not_in", "value": ["KP", "IR"]` |
| `contains` | Array contains value  | `"operator": "contains", "value": "bot"`      |
| `exists`   | Field exists          | `"operator": "exists", "value": true`         |

### Combining Conditions

Multiple conditions within a rule are combined with AND logic. All conditions must be true for the rule to match.

```json theme={null}
{
  "conditions": [
    { "field": "risk_score", "operator": "gt", "value": 70 },
    { "field": "aml.status", "operator": "eq", "value": "match" }
  ]
}
```

## Actions

| Action Type | Description                             |
| ----------- | --------------------------------------- |
| `approve`   | Automatically approve the session       |
| `decline`   | Automatically decline the session       |
| `review`    | Flag the session for manual review      |
| `escalate`  | Assign to a specific reviewer or team   |
| `webhook`   | Send a custom webhook notification      |
| `step`      | Trigger an additional verification step |

### Action Examples

```json Escalate to compliance team theme={null}
{
  "action": {
    "type": "escalate",
    "assign_to": "compliance-team",
    "reason": "High AML match score requires manual review"
  }
}
```

```json Trigger additional step theme={null}
{
  "action": {
    "type": "step",
    "step": "video_kyc",
    "reason": "Document from high-risk country requires video verification"
  }
}
```

## Rule Templates

Verilock provides built-in templates for common use cases:

| Template                | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `high_risk_country`     | Decline or escalate sessions from high-risk jurisdictions |
| `age_restriction`       | Enforce minimum age requirements                          |
| `aml_auto_decline`      | Auto-decline sessions with strong AML matches             |
| `device_fraud`          | Block sessions with critical device fraud signals         |
| `low_risk_auto_approve` | Auto-approve low-risk sessions that pass all checks       |

Apply a template:

```json theme={null}
POST /v1/orchestration/rules/from-template
{
  "template": "aml_auto_decline",
  "overrides": {
    "priority": 5,
    "conditions": [
      { "field": "aml.highest_score", "operator": "gt", "value": 0.85 }
    ]
  }
}
```

## Rule Evaluation Flow

```
Session submitted
    |
    v
Rules evaluated in priority order (lowest number = highest priority)
    |
    +-- Rule 1: conditions met? --> YES --> execute action, stop
    |                           --> NO  --> continue
    +-- Rule 2: conditions met? --> YES --> execute action, stop
    |                           --> NO  --> continue
    +-- ...
    |
    v
No rules matched --> apply default action (manual review)
```

## API Response

```json theme={null}
GET /v1/orchestration/rules
{
  "data": [
    {
      "id": "rule_a1b2c3d4",
      "name": "Block high-risk countries",
      "priority": 10,
      "enabled": true,
      "conditions": [...],
      "action": { "type": "decline", "reason": "Sanctioned jurisdiction" },
      "executions_total": 142,
      "last_executed_at": "2026-03-18T09:15:00Z",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}
```

| Field              | Type    | Description                                |
| ------------------ | ------- | ------------------------------------------ |
| `id`               | string  | Unique rule identifier                     |
| `name`             | string  | Human-readable rule name                   |
| `priority`         | integer | Evaluation order (lower = higher priority) |
| `enabled`          | boolean | Whether the rule is active                 |
| `conditions`       | array   | List of conditions to evaluate             |
| `action`           | object  | Action to execute when conditions match    |
| `executions_total` | integer | Total number of times the rule has fired   |
| `last_executed_at` | string  | ISO 8601 timestamp of last execution       |

<Tip>
  Start with a few high-priority rules (e.g., sanctioned countries, bot detection) and add more granular rules as you refine your verification workflow.
</Tip>