Routing Rules

Routing rules allow you to automatically assign reviews to specific reviewers based on conditions. This guide explains how to create and manage routing rules.

Open Source
Platform

Open Source uses config-based routing defined in humancheck.yaml. Simple YAML configuration for basic routing needs.

Overview

Routing rules evaluate reviews and assign them to reviewers based on:

Task type
Urgency level
Confidence score
Custom metadata
Priority (rule evaluation order)

Creating Routing Rules

Open Source (Config-Based)

Configure routing rules in humancheck.yaml:

# Default reviewers (used when no rules match)
default_reviewers:
  - alice@example.com
  - bob@example.com

# Routing rules
routing_rules:
  - name: "High-value payments to finance team"
    priority: 100
    conditions:
      task_type: {"operator": "=", "value": "payment"}
      metadata.amount: {"operator": ">", "value": 10000}
    assign_to: "finance@example.com"
    is_active: true
  
  - name: "Urgent reviews to on-call"
    priority: 200
    conditions:
      urgency: {"operator": "=", "value": "critical"}
    assign_to: "oncall@example.com"
    is_active: true

Platform (UI-Based with API)

Advanced routing with UI control, prioritization, and fine-grained ACL is only available in Humancheck Platform.

Via Dashboard UI:

Go to platform.humancheck.dev
Navigate to Routing section
Click Create Rule
Configure conditions, priority, and ACL settings
Assign to users or teams with fine-grained permissions

Via API:

import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://api.humancheck.dev/routing-rules",
        headers={
            "Authorization": "Bearer your-api-key-here",
            "Content-Type": "application/json"
        },
        json={
            "name": "High-value payments to finance team",
            "organization_id": 1,
            "priority": 100,
            "conditions": {
                "task_type": {"operator": "=", "value": "payment"},
                "metadata.amount": {"operator": ">", "value": 10000}
            },
            "assign_to_team_id": 5,  # Finance team
            "is_active": True
        }
    )
    rule = response.json()

Platform Features:

✅ UI Control: Visual rule builder in dashboard
✅ Prioritization: Set rule evaluation order
✅ Fine-grained ACL: Control who can view/edit/execute rules
✅ Team/User Assignment: Assign to specific teams or users
✅ Organization Scoping: Rules scoped to organizations

Rule Structure

Open Source (YAML):

routing_rules:
  - name: "Rule name"
    priority: 100
    conditions:
      task_type: {"operator": "=", "value": "payment"}
      urgency: {"operator": "in", "value": ["high", "critical"]}
    assign_to: "reviewer@example.com"  # Email or identifier
    is_active: true

Platform (JSON):

{
  "name": "Rule name",
  "organization_id": 1,
  "priority": 100,
  "conditions": {
    "task_type": {"operator": "=", "value": "payment"},
    "urgency": {"operator": "in", "value": ["high", "critical"]}
  },
  "assign_to_user_id": 2,
  "assign_to_team_id": 5,
  "is_active": true
}

Condition Operators

Equality

"task_type": {"operator": "=", "value": "payment"}

Comparison

"confidence_score": {"operator": "<", "value": 0.8}
"metadata.amount": {"operator": ">", "value": 10000}

In List

"urgency": {"operator": "in", "value": ["high", "critical"]}
"task_type": {"operator": "in", "value": ["payment", "data_deletion"]}

Contains

"proposed_action": {"operator": "contains", "value": "DELETE"}

Metadata Access

"metadata.amount": {"operator": ">", "value": 10000}
"metadata.user_id": {"operator": "=", "value": 123}

Priority System

Rules are evaluated in priority order (highest first). The first matching rule is used.

# High priority (evaluated first)
{
    "priority": 200,
    "conditions": {"urgency": "critical"}
}

# Medium priority
{
    "priority": 100,
    "conditions": {"task_type": "payment"}
}

# Low priority (catch-all)
{
    "priority": 10,
    "conditions": {}
}

Common Examples

Route by Task Type

{
    "name": "SQL reviews to DBA team",
    "priority": 100,
    "conditions": {
        "task_type": {"operator": "=", "value": "sql_execution"}
    },
    "assign_to_team_id": 4
}

Route by Urgency

{
    "name": "Critical reviews to on-call",
    "priority": 200,
    "conditions": {
        "urgency": {"operator": "=", "value": "critical"}
    },
    "assign_to_user_id": 10  # On-call user
}

Route by Confidence

{
    "name": "Low confidence to senior reviewers",
    "priority": 100,
    "conditions": {
        "confidence_score": {"operator": "<", "value": 0.7}
    },
    "assign_to_team_id": 3  # Senior reviewers team
}

Route by Metadata

{
    "name": "High-value payments to finance",
    "priority": 100,
    "conditions": {
        "task_type": {"operator": "=", "value": "payment"},
        "metadata.amount": {"operator": ">", "value": 10000}
    },
    "assign_to_team_id": 5
}

Catch-All Rule

{
    "name": "Default assignment",
    "priority": 10,
    "conditions": {},  # Matches everything
    "assign_to_team_id": 1  # Default team
}

Platform: UI-Based Routing

In Platform, you can manage routing rules entirely through the dashboard:

Visual Rule Builder: Create rules using drag-and-drop interface
Prioritization: Set rule evaluation order with visual priority controls
Fine-Grained ACL: Control who can view, edit, or execute each rule
Team/User Management: Assign reviews to teams or users with permission controls
Rule Testing: Test rules against sample reviews before activation
Analytics: Monitor rule performance and assignment accuracy

Access the routing management UI at platform.humancheck.dev/routing.

Best Practices

Use priority wisely: Higher priority rules should be more specific
Create catch-all rules: Ensure all reviews get assigned
Test rules: Test rules with sample reviews before going live
Document rules: Use descriptive names and comments
Monitor assignments: Check that reviews are being assigned correctly
Platform: Use UI for complex rule management, API for automation

Next Steps

Learn about Configuration Settings
Explore Multi-tenancy
Check out Dashboard for reviewing

Getting started

Products

Integrations

Use cases

Configuration

Platform Features

Connectors

Dashboard

Overview

Creating Routing Rules

Open Source (Config-Based)

Platform (UI-Based with API)

Rule Structure

Condition Operators

Equality

Comparison

In List

Contains

Metadata Access

Priority System

Common Examples

Route by Task Type

Route by Urgency

Route by Confidence

Route by Metadata

Catch-All Rule

Platform: UI-Based Routing

Best Practices

Next Steps

​Overview

​Creating Routing Rules

​Open Source (Config-Based)

​Platform (UI-Based with API)

​Rule Structure

​Condition Operators

​Equality

​Comparison

​In List

​Contains

​Metadata Access

​Priority System

​Common Examples

​Route by Task Type

​Route by Urgency

​Route by Confidence

​Route by Metadata

​Catch-All Rule

​Platform: UI-Based Routing

​Best Practices

​Next Steps

Overview

Creating Routing Rules

Open Source (Config-Based)

Platform (UI-Based with API)

Rule Structure

Condition Operators

Equality

Comparison

In List

Contains

Metadata Access

Priority System

Common Examples

Route by Task Type

Route by Urgency

Route by Confidence

Route by Metadata

Catch-All Rule

Platform: UI-Based Routing

Best Practices

Next Steps