Skip to main content

Match rate monitor

This recipe shows how to monitor the reconciliation match rate over time with trend analysis and rule-level breakdown. Match rate is the key KPI for reconciliation accuracy and directly impacts operational efficiency.

Endpoint​

GET /v1/reconciliations/match-rate

Returns a time-series summary of match rates with the chosen granularity and dimension.

Prerequisites​

  • A valid tenantId and bearer JWT.
  • The user must have at least one of: tenant_admin, tenant_analyst, tenant_lead.

Request​

curl -X GET "https://api.falconveritas.com/v1/reconciliations/match-rate?fromDate=2026-08-01&toDate=2026-08-22&granularity=daily&dimension=rule" \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json"

Response​

{
  "granularity": "daily",
  "dimension": "rule",
  "from_date": "2026-08-01",
  "to_date": "2026-08-22",
  "overall_match_rate": 0.984,
  "series": [
    {
      "date": "2026-08-01",
      "rule_id": "rule-001",
      "rule_name": "Bank-to-GL cash match",
      "total_count": 4523,
      "auto_matched_count": 4455,
      "analyst_review_count": 52,
      "exception_count": 16,
      "match_rate": 0.985
    }
  ],
  "by_rule": [
    {
      "rule_id": "rule-001",
      "rule_name": "Bank-to-GL cash match",
      "match_rate": 0.985,
      "trend_7d": 0.001
    },
    {
      "rule_id": "rule-002",
      "rule_name": "Crypto on-ramp match",
      "match_rate": 0.892,
      "trend_7d": -0.012
    }
  ],
  "alerts": [
    {
      "rule_id": "rule-002",
      "alert_type": "match_rate_decline",
      "current_rate": 0.892,
      "previous_rate": 0.904,
      "deviation": -0.012,
      "recommendation": "Review rule-002 thresholds; consider tightening tolerance"
    }
  ]
}

Dimensions​

DimensionDescription
ruleBreak down by reconciliation rule
accountBreak down by account
sourceBreak down by ingestion source
counterpartyBreak down by counterparty
currencyBreak down by transaction currency

Alert types​

Alert typeDescription
match_rate_declineMatch rate dropped below the rolling 7-day average by more than 2%
match_rate_lowMatch rate below the configured threshold (default 0.85)
rule_outlierOne rule's match rate deviates significantly from the others

Use cases​

  • Operations monitoring — track match rate as the primary reconciliation KPI.
  • Rule tuning — identify rules that need threshold adjustments.
  • Anomaly investigation — investigate sudden drops in match rate.
  • Vendor benchmarking — compare match rates across ingestion sources.

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 rate = await fvi.reconciliations.matchRate({
  fromDate: '2026-08-01',
  toDate: '2026-08-22',
  granularity: 'daily',
  dimension: 'rule',
});

console.log(`Overall match rate: ${(rate.overall_match_rate * 100).toFixed(1)}%`);

for (const alert of rate.alerts ?? []) {
  console.log(`Alert: ${alert.alert_type} for ${alert.rule_id} — ${alert.recommendation}`);
}

Python​

from falconveritas import FVI

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

rate = client.reconciliations.match_rate(
  from_date="2026-08-01",
  to_date="2026-08-22",
  granularity="daily",
  dimension="rule",
)
print(f"Overall match rate: {rate.overall_match_rate * 100:.1f}%")

for alert in rate.alerts or []:
  print(f"Alert: {alert.alert_type} for {alert.rule_id} — {alert.recommendation}")

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