brex-expense-plugin

name	Brex Expense Plugin
description	Connect a Vellum Assistant to a Brex account to read transactions, categorize expenses, detect anomalies, and generate reports. API key based, admin-only setup. Use when the user wants to connect Brex, pull expense data, generate an expense report, categorize spending, or detect unusual charges.
metadata	{"vellum":{"emoji":"💳","display-name":"Brex Expense Plugin","activation-hints":["connect my Brex","set up Brex access","Brex expense report","pull Brex transactions","categorize expenses","detect unusual charges","new vendor alert"],"avoid-when":["user wants help with a non-Brex expense platform (Ramp, Expensify, Amex)","user wants general bookkeeping without a Brex account"],"category":"integrations"}}

What This Plugin Does

Connects a Vellum Assistant to a Brex account using an API key, discovers cards and users, and provides tools for querying transactions, generating expense reports, categorizing spending, and detecting anomalies.

This plugin ships seven tools that handle the full lifecycle:

Connector tools:

• brex_connect — validate and store the Brex API key
• brex_discover — pull cards, users, and build vendor history (90-day baseline)
• brex_query — read transactions with filters (date, card, amount, merchant)
• brex_status — check connection health and account snapshot

Operating tools:

• brex_report — generate expense reports with vendor matching and NEW detection
• brex_categorize — map transactions to GL-style categories
• brex_anomaly — detect new vendors, unusual amounts, duplicates, and recurring patterns

Prerequisites

You need a Brex admin account. Only a Brex admin can generate an API key. If you are not an admin, ask your Brex admin to generate one for you.

1. Go to Brex dashboard > Settings > Developers > API Keys
2. Click Create new key
3. Name it (e.g. "Vellum Assistant")
4. Select Read access for Cards and Transactions
5. Copy the generated API key

You will paste this key into the brex_connect tool. The key is stored securely and never appears in chat after connection.

Step 1: Connect

Call brex_connect with your API key:

brex_connect(api_key: "your-key-here")

Optional: set privacy_restrictions: true to hide per-person spend by default.

The tool validates the key against the Brex API and stores it. If validation fails, check that the key has card read access and was generated by an admin.

Step 2: Discover

Call brex_discover to build a snapshot of your Brex account:

brex_discover(lookback_days: 90)

This pulls:

• All cards (with last 4 digits and names)
• All users (for cardholder resolution)
• Last 90 days of transactions (to establish a vendor baseline)
• Known vendor list (100+ default prefixes shipped in)

The vendor baseline powers new-vendor detection in reports and anomaly scans.

Step 3: Query

Use brex_query to read transactions with filters:

brex_query(start_date: "2026-07-01", end_date: "2026-07-09")
brex_query(card_last_four: "7545", start_date: "2026-07-01")
brex_query(min_amount: 500, wellness_only: true)

Uses posted_at_date (settlement date) as the date field, NOT initiated_at_date.

Step 4: Report

Use brex_report to generate an expense report:

brex_report(date: "2026-07-08")
brex_report(start_date: "2026-07-01", end_date: "2026-07-08", top_n: 10)

Report includes:

• Transaction count and total
• Top-N merchant breakdown table with card labels
• NEW vendor detection (vendor prefix matching against known list)
• Card breakdown summary
• Formatted table output

Step 5: Categorize

Use brex_categorize to map transactions to GL categories:

brex_categorize(start_date: "2026-07-01", end_date: "2026-07-08")

Returns category summary (totals per category) and per-transaction detail. Unclassified transactions are flagged with low confidence for manual review.

Default categories include: AI/LLM API, Software Subscriptions, Meals & Travel, Office/Misc, Wellness. Users can extend the category rules in the source code.

Step 6: Detect Anomalies

Use brex_anomaly to scan for unusual patterns:

brex_anomaly(start_date: "2026-07-01", end_date: "2026-07-08")

Detects:

• New vendors — not in the known prefix list
• Unusual amounts — >3x the vendor's historical average
• Duplicate charges — same merchant + same amount within 48h (configurable)
• Recurring patterns — 3+ charges at consistent intervals

Privacy Restrictions

When privacy_restrictions is enabled (set during connect or in config.json):

• Per-person spend is hidden by default
• Card labels show card name only, not cardholder name
• Individual transaction details are aggregated

Users can toggle this at any time by updating config.json or reconnecting.

Technical Notes

• API key only. No OAuth flow. Simpler than QBO connector.
• posted_at_date is the correct date field. The API accepts start_date/end_date params and returns filtered results; a secondary client-side filter on posted_at_date provides defense in depth.
• Vendor matching uses strict prefix match. Vendors with appended transaction IDs (Amazon.com*JX4R5X) are matched by base prefix.
• Card resolution joins /v2/cards + /v2/users. Cards return last_four (not last4). Owner names come from the users endpoint, not the cards endpoint.
• Pagination requires limit=100 minimum. Lower limits return 0 items.
• All defaults are adjustable. Known vendor prefixes, category rules, and wellness classifier are in src/brex-client.ts.