Workflow Rules

Workflow rules automate compliance decisions based on risk scores, screening results, and applicant attributes. Rules are evaluated against applicant state and the most recent risk assessment, with the highest-priority matching rule determining the action.

Rule Structure

Each rule has:

• conditions: A flat dictionary of applicant attributes and risk signals to match against
• action: A single action string (auto_approve, manual_review, auto_reject, escalate, or hold)
• priority: Higher priority rules are evaluated first (0-10000)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Auto-approve Low Risk Applicants",
  "description": "Approve when risk is low and no screening hits",
  "conditions": {
    "risk_level": ["low"],
    "has_sanctions_hit": false,
    "has_pep_hit": false
  },
  "action": "auto_approve",
  "priority": 100,
  "is_active": true
}

Creating Rules

Auto-Approve Low Risk

curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto-approve Low Risk Applicants",
    "description": "Approve when risk is low and no screening hits",
    "conditions": {
      "risk_level": ["low"],
      "has_sanctions_hit": false,
      "has_pep_hit": false
    },
    "action": "auto_approve",
    "priority": 100,
    "is_active": true
  }'

Escalate Sanctions Hits

curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Escalate Sanctions Hits",
    "description": "Escalate any applicant with confirmed sanctions hits to senior compliance",
    "conditions": {
      "has_sanctions_hit": true
    },
    "action": "escalate",
    "assign_to_role": "senior_compliance",
    "notify_on_match": true,
    "priority": 1000
  }'

Review High-Risk Countries

curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review High-Risk Countries",
    "description": "Manual review for applicants from FATF grey/black list countries",
    "conditions": {
      "country": ["KP", "IR", "SY", "MM", "AF", "YE"]
    },
    "action": "manual_review",
    "notify_on_match": true,
    "priority": 800
  }'

Request Body Reference

Field	Type	Required	Description
name	string	Yes	Rule name (max 255 chars)
description	string	No	Human-readable description
conditions	object	No	Condition dictionary (see below)
action	string	Yes	One of: auto_approve, manual_review, auto_reject, escalate, hold
assign_to_user_id	UUID	No	Assign matched applicants to specific user
assign_to_role	string	No	Assign to a role (e.g., senior_compliance)
notify_on_match	boolean	No	Send notification when rule matches (default: false)
notification_channels	string[]	No	Channels: email, slack, webhook
priority	integer	No	0-10000, higher = evaluated first (default: 0)
is_active	boolean	No	Enable/disable rule (default: true)

Condition Format

Conditions use a flat dictionary where keys are attribute names and values are what to match against. All conditions must match (AND logic). List values match if the applicant's value is in the list.

Condition Key	Value Type	Description
risk_level	string[]	Match risk levels: low, medium, high, critical
risk_score_min	integer	Minimum risk score (0-100)
country	string[]	Match ISO country codes
has_sanctions_hit	boolean	Whether applicant has sanctions hits
has_pep_hit	boolean	Whether applicant has PEP hits

Example:

{
  "conditions": {
    "risk_level": ["high", "critical"],
    "has_sanctions_hit": false
  }
}

This matches applicants with high or critical risk AND no sanctions hits.

Available Actions

Action	Description
auto_approve	Automatically approve the applicant
manual_review	Route to manual review queue
auto_reject	Automatically reject the applicant
escalate	Escalate to senior reviewer (use with assign_to_role)
hold	Place on hold for further investigation

Listing Rules

curl -X GET "https://api.bytrustgate.com/api/v1/workflows/rules" \
  -H "Authorization: Bearer YOUR_API_KEY"

Optional query parameters:

• is_active (boolean) - Filter by active/inactive
• action (string) - Filter by action type
• sort_by (string) - Sort by: priority, name, created_at
• sort_order (string) - asc or desc

Response

{
  "items": [
    {
      "id": "...",
      "tenant_id": "...",
      "name": "Escalate sanctions hits",
      "description": "...",
      "conditions": {"has_sanctions_hit": true},
      "condition_summary": "has_sanctions_hit=True",
      "action": "escalate",
      "assign_to_user_id": null,
      "assign_to_role": "senior_compliance",
      "notify_on_match": true,
      "notification_channels": [],
      "priority": 1000,
      "is_active": true,
      "times_matched": 12,
      "last_matched_at": "2026-01-15T10:30:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 5
}

Rule Priority

Rules are evaluated in priority order (higher number = evaluated first). The first matching rule determines the action taken.

Default rules seeded for new tenants:

Rule	Priority	Action
Escalate sanctions hits	1000	escalate
Review high-risk countries	800	manual_review
Review high risk	500	manual_review
Auto-approve low risk	100	auto_approve
Default manual review	0	manual_review

You can seed these defaults via:

curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules/seed-defaults \
  -H "Authorization: Bearer YOUR_API_KEY"

Testing Rules

Test a rule against a specific applicant to see if it would match:

curl -X POST https://api.bytrustgate.com/api/v1/workflows/rules/{rule_id}/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "rule_id": "...",
  "rule_name": "Auto-approve Low Risk Applicants",
  "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
  "matches": true,
  "condition_results": {
    "risk_level": {
      "expected": ["low"],
      "actual": "low",
      "matches": true
    },
    "has_sanctions_hit": {
      "expected": false,
      "actual": false,
      "matches": true
    }
  }
}

Risk Assessment

Workflow rules are applied as part of risk assessment. Use the risk endpoints to trigger evaluation:

Get Risk Assessment

curl -X GET "https://api.bytrustgate.com/api/v1/workflows/risk/{applicant_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Recalculate Risk and Apply Rules

curl -X POST "https://api.bytrustgate.com/api/v1/workflows/risk/{applicant_id}/recalculate?apply_workflow=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "applicant_id": "...",
  "overall_level": "low",
  "overall_score": 15,
  "recommended_action": "auto_approve",
  "signals": [
    {
      "category": "aml",
      "signal_name": "no_screening_hits",
      "score": 0,
      "weight": 0.3,
      "description": "No AML screening hits found",
      "details": {}
    }
  ],
  "assessment_time": "2026-01-20T14:30:00Z",
  "applied_rule_name": "Auto-approve low risk",
  "final_action": "auto_approve"
}

---

Next Steps

• Country Risk - Geographic risk configuration
• Risk Factors - Configure scoring factors
• About Risk Scoring - Overview