Create rule

This recipe shows how to create a deterministic reconciliation rule that pairs transactions from two sources based on field mappings and matching conditions.

Endpoint

POST /v1/rules

Creates a new reconciliation rule in the tenant. Rules are evaluated in priority order during reconciliation runs.

Prerequisites

• A valid tenantId and bearer JWT.
• The user must have the tenant_admin or tenant_rule_author role.
• Idempotency key is required.

Request body

curl -X POST https://api.falconveritas.com/v1/rules \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bank-to-GL cash match",
    "description": "Match bank statement transactions to GL cash entries by date and amount",
    "rule_type": "deterministic",
    "priority": 100,
    "field_mappings": [
      {"left_field": "transaction_date", "right_field": "posting_date", "match_type": "exact", "tolerance": null},
      {"left_field": "amount", "right_field": "amount", "match_type": "exact", "tolerance": 0.01},
      {"left_field": "currency", "right_field": "currency", "match_type": "exact", "tolerance": null},
      {"left_field": "reference", "right_field": "memo", "match_type": "fuzzy", "tolerance": 0.85}
    ],
    "auto_match_threshold": 0.92,
    "analyst_review_threshold": 0.70,
    "idempotency_key": "rule-fvi-$RANDOM"
  }'

Response

{
  "id": "rule-001",
  "tenant_id": "f1a4e6e2-4b3e-4d2e-9b9c-3a2e9b1f4d5a",
  "name": "Bank-to-GL cash match",
  "description": "Match bank statement transactions to GL cash entries by date and amount",
  "rule_type": "deterministic",
  "priority": 100,
  "field_mappings": [...],
  "auto_match_threshold": 0.92,
  "analyst_review_threshold": 0.70,
  "status": "active",
  "created_at": "2026-08-22T15:00:00Z",
  "created_by": "user:alice"
}

Field mapping reference

Match type	Description	Tolerance
exact	Field values must match exactly	N/A
numeric	Numeric comparison with tolerance	Tolerance in source currency units
fuzzy	String similarity (Levenshtein)	Tolerance 0-1, default 0.85
regex	Regular expression match	N/A
date_window	Date within N days	Tolerance in days

Threshold reference

Threshold	Default	Description
auto_match_threshold	0.92	Confidence above this triggers automatic match
analyst_review_threshold	0.70	Confidence between this and auto-match triggers analyst review
Below analyst_review_threshold	N/A	Confidence below this triggers exception queue

Use cases

• Initial rule setup — create the first reconciliation rules after tenant onboarding.
• New asset class — add rules for a new transaction type (e.g., crypto, FX).
• A/B testing — clone an existing rule and adjust thresholds for experimentation.

Code samples

TypeScript

import { FVI } from '@falconveritas/sdk';

const fvi = new FVI({
  baseUrl: 'https://api.falconveritas.com',
  bearer: process.env.FVI_JWT!,
  tenantId: process.env.FVI_TENANT_ID!,
});

const rule = await fvi.rules.create({
  name: 'Bank-to-GL cash match',
  ruleType: 'deterministic',
  priority: 100,
  fieldMappings: [
    { leftField: 'transaction_date', rightField: 'posting_date', matchType: 'exact' },
    { leftField: 'amount', rightField: 'amount', matchType: 'exact', tolerance: 0.01 },
  ],
  autoMatchThreshold: 0.92,
  analystReviewThreshold: 0.70,
  idempotencyKey: `rule-fvi-${Date.now()}`,
});

console.log('Rule created:', rule.id);

Python

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  tenant_id=os.environ["FVI_TENANT_ID"],
)

rule = client.rules.create(
  name="Bank-to-GL cash match",
  rule_type="deterministic",
  priority=100,
  field_mappings=[
    {"left_field": "transaction_date", "right_field": "posting_date", "match_type": "exact"},
    {"left_field": "amount", "right_field": "amount", "match_type": "exact", "tolerance": 0.01},
  ],
  auto_match_threshold=0.92,
  analyst_review_threshold=0.70,
  idempotency_key=f"rule-fvi-{int(time.time())}",
)
print("Rule created:", rule.id)

Related articles

• List reconciliations
• Match rate monitor
• Rules API
• Authentication

Last updated: 2026-08-22 · Page owner: Documentation · Source: src/lib/api/rules.ts.