Skip to main content

Break-down analysis

This recipe shows how to break down a reconciliation account by counterparty, currency, transaction type, or sub-ledger. Break-down analysis helps you understand the composition of an account's activity and identify concentration risks or unusual patterns.

Endpoint​

GET /v1/accounts/{id}/breakdown

Returns a hierarchical breakdown of the account's activity for the requested dimension.

Prerequisites​

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

Request​

curl -X GET "https://api.falconveritas.com/v1/accounts/acc-001/breakdown?dimension=counterparty&fromDate=2026-08-01&toDate=2026-08-22" \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json"

Response​

{
  "account_id": "acc-001",
  "dimension": "counterparty",
  "from_date": "2026-08-01",
  "to_date": "2026-08-22",
  "total_count": 12345,
  "total_amount": 12456023.42,
  "currency": "USD",
  "breakdown": [
    {
      "key": "CPTY-001",
      "label": "JPMorgan Chase",
      "count": 4523,
      "amount": 5234567.89,
      "currency": "USD",
      "percentage": 42.0
    },
    {
      "key": "CPTY-002",
      "label": "Citibank",
      "count": 3120,
      "amount": 4123456.78,
      "currency": "USD",
      "percentage": 33.1
    },
    {
      "key": "CPTY-003",
      "label": "Bank of America",
      "count": 4702,
      "amount": 3097998.75,
      "currency": "USD",
      "percentage": 24.9
    }
  ],
  "other": {
    "count": 0,
    "amount": 0,
    "currency": "USD",
    "percentage": 0
  }
}

Dimensions​

DimensionDescription
counterpartyBreak down by counterparty (most common)
currencyBreak down by transaction currency
transaction_typeBreak down by transaction type (wire, ACH, card, etc.)
sub_ledgerBreak down by sub-ledger code
gl_accountBreak down by mapped GL account
channelBreak down by ingestion channel (file, API, stream)
regionBreak down by counterparty region (NA, EMEA, APAC)

Filter parameters​

ParameterTypeDescription
dimensionstringOne of the dimensions above
fromDateISO 8601 dateStart of analysis period
toDateISO 8601 dateEnd of analysis period
limitinteger (1-50, default 20)Maximum top-N groups to return
minAmountnumberMinimum amount threshold for inclusion
currencystring (ISO 4217)Convert to a single display currency

Use cases​

  • Concentration analysis — identify top-N counterparty concentrations for risk reporting.
  • Sub-ledger integrity — verify that the GL account mix matches the expected business mix.
  • Channel mix — track the shift from file-based to API-based ingestion over time.
  • Currency exposure — break down by currency to inform FX hedging decisions.

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 breakdown = await fvi.accounts.getBreakdown('acc-001', {
  dimension: 'counterparty',
  fromDate: '2026-08-01',
  toDate: '2026-08-22',
});

for (const item of breakdown.breakdown) {
  console.log(`${item.label}: ${item.percentage}% (${item.currency} ${item.amount})`);
}

Python​

from falconveritas import FVI

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

breakdown = client.accounts.get_breakdown(
  "acc-001",
  dimension="counterparty",
  from_date="2026-08-01",
  to_date="2026-08-22",
)
for item in breakdown.breakdown:
  print(f"{item.label}: {item.percentage}% ({item.currency} {item.amount})")

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