Getting Started with Workflows

Workflow rules let you automate compliance decisions so your team can focus on the cases that matter. Instead of manually reviewing every applicant, you define rules that automatically approve low-risk applicants, escalate sanctions hits, and route edge cases to the right reviewer.

This guide walks you through creating your first rules using both the TrustGate dashboard and the API.

Prerequisites

• A TrustGate account with admin access to the Workflows module (requires admin:workflows permission)
• At least one applicant in the system (for testing rules)
• Your API key (found in Settings > API Keys) if using the API examples

Your First Rule: Auto-Approve Low Risk

The most common starting point is a rule that automatically approves applicants who present low risk and have no screening hits. This eliminates manual review for straightforward cases.

Using the Dashboard

1. Navigate to Risk Engine > Workflow Rules in the sidebar
2. Click Create Rule
3. Fill in the rule details:
   • Name: Auto-approve low risk
   • Description: Automatically approve applicants with low risk and no screening hits
   • Action: Select Auto Approve from the dropdown
   • Priority: 100
4. Under Conditions, add:
   • risk_level equals low
   • has_sanctions_hit equals false
   • has_pep_hit equals false
5. Click Save

Using the API

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",
    "description": "Automatically approve applicants with low risk and no screening hits",
    "conditions": {
      "risk_level": ["low"],
      "has_sanctions_hit": false,
      "has_pep_hit": false
    },
    "action": "auto_approve",
    "priority": 100,
    "is_active": true
  }'

What this does: When a risk assessment runs, the engine evaluates conditions using AND logic -- all conditions must match. Here, the applicant must have a low risk level AND no sanctions hits AND no PEP hits. If all three are true, the applicant is auto-approved without manual intervention.

Note that risk_level accepts an array of values. If you wanted to also auto-approve medium-risk applicants without hits, you would set "risk_level": ["low", "medium"].

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "...",
  "name": "Auto-approve low risk",
  "description": "Automatically approve applicants with low risk and no screening hits",
  "conditions": {
    "risk_level": ["low"],
    "has_sanctions_hit": false,
    "has_pep_hit": false
  },
  "condition_summary": "risk_level in ['low'] AND has_sanctions_hit=False AND has_pep_hit=False",
  "action": "auto_approve",
  "assign_to_user_id": null,
  "assign_to_role": null,
  "notify_on_match": false,
  "notification_channels": [],
  "priority": 100,
  "is_active": true,
  "times_matched": 0,
  "last_matched_at": null,
  "created_at": "2026-02-04T12:00:00Z",
  "updated_at": "2026-02-04T12:00:00Z"
}

Add a Sanctions Screening Rule

Sanctions hits require immediate attention. This rule auto-rejects applicants who match a sanctions list, ensuring your organization never onboards a sanctioned individual.

Using the Dashboard

1. Go to Risk Engine > Workflow Rules and click Create Rule
2. Fill in:
   • Name: Auto-reject sanctions matches
   • Description: Reject any applicant with confirmed sanctions hits
   • Action: Select Auto Reject
   • Priority: 1000
   • Notify on match: Enable this toggle
3. Under Conditions, add:
   • has_sanctions_hit equals true
4. Click Save

Using the API

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-reject sanctions matches",
    "description": "Reject any applicant with confirmed sanctions hits",
    "conditions": {
      "has_sanctions_hit": true
    },
    "action": "auto_reject",
    "notify_on_match": true,
    "notification_channels": ["email"],
    "priority": 1000,
    "is_active": true
  }'

Why priority 1000? This rule must be evaluated before the auto-approve rule (priority 100). The engine evaluates rules from highest priority to lowest and stops at the first match. A sanctioned individual with an otherwise low risk score would be caught by this rule before the auto-approve rule fires.

If your compliance policy requires human review before rejection, use "action": "escalate" instead of "auto_reject" and pair it with "assign_to_role": "senior_compliance". See the next section for an example.

Set Up PEP Escalation

Politically Exposed Persons require enhanced due diligence. Rather than auto-rejecting or auto-approving, escalate PEP hits to a senior compliance officer for manual review.

Using the Dashboard

1. Go to Risk Engine > Workflow Rules and click Create Rule
2. Fill in:
   • Name: Escalate PEP hits
   • Description: Escalate politically exposed persons to senior compliance for enhanced due diligence
   • Action: Select Escalate
   • Assign to role: senior_compliance
   • Priority: 900
   • Notify on match: Enable this toggle
3. Under Conditions, add:
   • has_pep_hit equals true
4. Click Save

Using the API

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 PEP hits",
    "description": "Escalate politically exposed persons to senior compliance for enhanced due diligence",
    "conditions": {
      "has_pep_hit": true
    },
    "action": "escalate",
    "assign_to_role": "senior_compliance",
    "notify_on_match": true,
    "notification_channels": ["email", "slack"],
    "priority": 900,
    "is_active": true
  }'

The escalate action routes the applicant to the role specified in assign_to_role. You can also assign to a specific user by providing assign_to_user_id with their UUID. Enabling notify_on_match sends alerts through the channels listed in notification_channels (supported: email, slack, webhook).

Test a Rule

Before relying on a rule in production, test it against a real applicant to verify it behaves as expected. The test endpoint runs the rule's conditions against the applicant's current risk assessment and returns a detailed breakdown of which conditions matched.

Using the API

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"
  }'

Replace {rule_id} with the UUID of the rule you want to test, and use an actual applicant ID from your system.

Response

{
  "rule_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "rule_name": "Auto-approve low risk",
  "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
    },
    "has_pep_hit": {
      "expected": false,
      "actual": false,
      "matches": true
    }
  }
}

Reading the results:

• matches -- Whether the rule as a whole would fire for this applicant. All conditions must match (AND logic).
• condition_results -- A per-condition breakdown showing what the rule expected, what the applicant's actual value was, and whether that individual condition matched.

If matches is false, look at the individual conditions to see which one failed. This helps you refine conditions without guesswork.

Testing from the Dashboard

On the rule detail page, click Test Rule, select an applicant from the dropdown, and review the condition results in the panel that appears.

Monitor Rule Execution

Once rules are active, you need visibility into which rules are firing and what actions they produce.

Rule Match Statistics

Each rule tracks how many times it has matched and when it last matched. View this from the rules list:

curl -X GET "https://api.bytrustgate.com/api/v1/workflows/rules?sort_by=priority&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

In the response, each rule includes times_matched and last_matched_at fields. A rule with zero matches over time may have conditions that are too restrictive.

Risk Assessment History

To see which rule was applied to a specific applicant and what action resulted:

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

The response includes applied_rule_name (which rule fired) and final_action (the action that was taken). If final_action differs from recommended_action, a workflow rule overrode the default recommendation.

Audit Logs

Every rule creation, update, deletion, and risk recalculation is recorded in the audit log. Navigate to Audit Log in the dashboard, or filter by workflow_rule.created, workflow_rule.updated, workflow_rule.deleted, and risk.recalculated event types.

Rule Priority

Rules are evaluated in descending priority order -- the highest priority number is evaluated first. The first rule whose conditions all match determines the action. Remaining rules are skipped.

Priority values range from 0 to 10,000.

Recommended Priority Ranges

Priority Range	Use Case
900 - 1000	Critical safety rules (sanctions rejection, fraud blocks)
700 - 899	High-risk escalations (PEP hits, high-risk countries)
400 - 699	Moderate risk routing (high risk score, manual review)
100 - 399	Low-risk automation (auto-approve clean applicants)
0	Catch-all default (manual review for anything unmatched)

Default Rules

New tenants can seed a starter set of rules using the seed endpoint:

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

This creates five rules:

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

The seed endpoint only works if no rules exist yet. Delete existing rules first if you want to re-seed.

Priority Conflicts

If two rules have the same priority, evaluation order is not guaranteed. Assign distinct priorities to avoid ambiguous behavior.

Available Conditions

Conditions use a flat dictionary where keys are attribute names and values define what to match. All conditions in a rule use AND logic -- every condition must match for the rule to fire.

For list values, the condition matches if the applicant's actual value appears anywhere in the list.

Condition Key	Value Type	Description
risk_level	string[]	Risk level from assessment. Values: low, medium, high, critical
risk_score_min	integer	Minimum risk score threshold (0-100). Matches if score is at or above value
risk_score_max	integer	Maximum risk score threshold (0-100). Matches if score is at or below value
country	string[]	ISO 3166-1 alpha-3 country codes. Matches against applicant nationality or country of residence
has_sanctions_hit	boolean	Whether the applicant has any sanctions screening hits
has_pep_hit	boolean	Whether the applicant has any PEP (Politically Exposed Person) hits
status	string or string[]	Applicant status. Values: pending, in_progress, review, approved, rejected, withdrawn
nationality	string or string[]	Applicant nationality (ISO 3166-1 alpha-3 code)

Condition Examples

Match high or critical risk applicants:

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

Match applicants from FATF grey/black list countries with a risk score above 60:

{
  "conditions": {
    "country": ["KP", "IR", "SY", "MM", "AF", "YE"],
    "risk_score_min": 60
  }
}

Match low-risk applicants with no hits of any kind:

{
  "conditions": {
    "risk_level": ["low"],
    "has_sanctions_hit": false,
    "has_pep_hit": false
  }
}

Empty Conditions

A rule with an empty conditions object ("conditions": {}) matches every applicant. Use this for catch-all rules at priority 0 to ensure no applicant falls through without an action.

Available Actions

Each rule specifies a single action that is taken when the rule matches.

Action	Description	When to Use
auto_approve	Automatically sets the applicant status to approved	Low-risk applicants with clean screening results
manual_review	Routes the applicant to the manual review queue	Medium-risk cases or when human judgment is needed
auto_reject	Automatically rejects the applicant	Sanctioned individuals, confirmed fraud, policy violations
escalate	Escalates to a senior reviewer or specific role	PEP hits, complex cases requiring senior sign-off. Pair with assign_to_role or assign_to_user_id
hold	Places the applicant on hold for further investigation	Pending additional documentation or external verification

Action Modifiers

Actions can be combined with assignment and notification options:

Field	Type	Description
assign_to_user_id	UUID	Assign the matched applicant to a specific user for review
assign_to_role	string	Assign to a role (e.g., senior_compliance, fraud_analyst)
notify_on_match	boolean	Send notifications when the rule fires (default: false)
notification_channels	string[]	Where to send notifications: email, slack, webhook

Example: Escalate with Assignment and Notification

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 high-risk country applicants",
    "description": "Route applicants from sanctioned jurisdictions to senior compliance with notification",
    "conditions": {
      "country": ["KP", "IR", "SY"]
    },
    "action": "escalate",
    "assign_to_role": "senior_compliance",
    "notify_on_match": true,
    "notification_channels": ["email", "slack"],
    "priority": 800,
    "is_active": true
  }'

---

Next Steps

• About Workflow Builder -- Visual drag-and-drop workflow creation
• Workflow Rules Reference -- Full API reference for the rules endpoints
• About Risk Scoring -- How risk scores are calculated
• Country Risk -- Geographic risk configuration