Brex

Get a card by its ID

Get an expense by its ID

Expand:

• expand: Array of entity types to expand. Use ["RECEIPTS"] to include download_uri and parsed content in receipt objects.

Additional Fields:

• additional_fields: Array of optional fields to include in response. Supported values:
• "TRAVEL_METADATA"
• Includes flight, car rental, lodging, and train travel data
• "LOCATION"
• Includes expense location details (country, city, coordinates, etc.)

Example 1: Getting an expense with expanded receipts: { "id": "expense_123", "expand": ["RECEIPTS"] }

Example 2: Getting an expense with travel metadata and location: { "id": "expense_123", "additional_fields": ["TRAVEL_METADATA", "LOCATION"] }

Example 3: Getting an expense with everything: { "id": "expense_123", "expand": ["RECEIPTS"], "additional_fields": ["TRAVEL_METADATA", "LOCATION"] }

Understanding Expense Lifecycle and Compliance Status:

Expense Lifecycle: 1. New expense created (card transaction or reimbursement submitted) 2. Documentation phase: System checks if documentation is required (receipts, memo, attendees, etc.) 3. Spender submits documentation if needed 4. Review phase: System checks if approval/review is required based on company policy 5. Reviewer reviews and approves/rejects if necessary 6. Expense is finalized

Each expense returns TWO sets of compliance-related fields:

A. DOCUMENTATION COMPLIANCE (for spenders - receipts, memo, attendees):

• documentationComplianceStatus: Status of documentation requirements that the spender must fulfill
• "NOT_REQUIRED"
• Company policy does not require any documentation for this expense. Empty receipts/memo are acceptable.
• "COMPLETED"
• All required documentation has been provided according to policy.
• "DUE"
• Documentation is required by policy but not yet provided. Check missingDocumentations field for specifics.
• "OVERDUE"
• Required documentation is past its submission deadline. Check missingDocumentations field for specifics.
• missingDocumentations: Array of specific items required by policy but not yet provided. Possible values: ["MEMO", "RECEIPT", "ATTENDEES", "EXTENDED_FIELD"]
• Empty array []
• Either no documentation is required OR all required documentation is complete
• Non-empty array
• Lists specific items that must be provided (e.g., ["MEMO", "RECEIPT"])
• documentationSubmissionDeadline: The UTC timestamp by which documentation must be submitted (only present if documentation is required)

B. REVIEW COMPLIANCE (for reviewers - approval/rejection):

• reviewComplianceStatus: Status of review/approval requirements that the reviewer must fulfill
• "NOT_REQUIRED"
• Company policy does not require review/approval for this expense.
• "COMPLETED"
• The expense has been reviewed and approved/rejected.
• "DUE"
• Review is required by policy but not yet completed.
• "OVERDUE"
• Required review is past its deadline.
• reviewDeadline: The UTC timestamp by which the review must be completed (only present if review is required)

KEY DISTINCTIONS:

• DocumentationComplianceStatus="NOT_REQUIRED" and missingDocumentations=[] → Documentation not required by company policy
• Empty receipts/memo with documentationComplianceStatus="DUE" or "OVERDUE" and missingDocumentations=["RECEIPT","MEMO"] → Documentation IS required by policy but missing
• reviewComplianceStatus="DUE" or "OVERDUE" → Expense is waiting for someone to review/approve it
• reviewComplianceStatus="NOT_REQUIRED" → No approval needed

Get expense policy information for a budget/spend limit as structured, validatable content.

This tool returns expense policy rules in the EXACT same format as shown in the Brex Dashboard's "View policy" sidebar, but structured as JSON for proper validation.

What you'll get:

• formatted_text: Human-readable policy text matching Dashboard display
• sections: Array of policy sections with rules
• has_restrictions: Boolean indicating if there are any policy restrictions
• budget_name: Name of the budget/spend limit
• policy_name: Name of the policy

Use this tool to answer questions like:

• "Do I need a receipt for this $30 lunch?"
• "Can I expense alcohol?"
• "Who needs to approve my $500 dinner?"
• "What's the limit before I need approval?"
• "Do I need to list attendees for a business meal?"

Parameters:

• spend_limit_id: REQUIRED
• The ID of the budget/spend limit. Use the ID directly from list_my_limits response.
• rules_filter: OPTIONAL
• Which view of the policy to return:
• "ONLY_RELEVANT_FOR_REQUESTER" (default): Shows personalized rules for the requesting user
• "ALL_RULES": Shows complete policy including all user-specific exceptions (requires admin permissions)

Response Format: Returns structured JSON with:

• formatted_text: Natural language policy rules
• sections: Array of {title, type, description, rules[]}
• has_restrictions: boolean
• budget_name: string
• policy_name: string

Get the expected payout date for a reimbursement expense. Returns the date when the reimbursement payment is expected to arrive. Only works for REIMBURSEMENT type expenses that are paid through Brex.

Note: This tool will return an error if the reimbursement is configured to be paid outside of Brex (Pay outside of Brex / PoB). In those cases, the payment is handled directly between the company and employee (usually at payroll time), and Brex does not control the payment date.

Parameters:

• expense_id: The ID of the reimbursement expense

Example: { "expense_id": "expense_123" }

Response includes:

• expense_id: The ID of the expense
• expense_type: The type of the expense (will be REIMBURSEMENT)
• expected_reimbursement_payout_date: The expected date when the reimbursement will be paid out (ISO 8601 format, UTC timezone)
• status: The current status of the expense

Get a user by their unique ID

This tool retrieves detailed information about a specific user using their unique user ID. Use this when you have a user ID and need to get their complete profile information.

Example Input: { "id": "cuuser_123" }

Example Output: { "id": "cuuser_123", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "role": "CARD_ADMIN", "status": "ACTIVE", "managerId": "cuuser_5678", "managerFirstName": "Jane", "managerLastName": "Smith", "managerTitleId": "ti_1234", "managerTitleName": "Engineering Manager", "departmentId": "cudmnt_1234", "departmentName": "Engineering", "locationId": "culoc_1234", "locationName": "San Francisco", "titleId": "ti_5678", "titleName": "Software Engineer" }

Get the current authenticated user

This tool retrieves the profile information of the currently authenticated user making the request. Use this when you need to get information about who is currently logged in or making the API call. No input parameters required.

Example Output: { "id": "cuuser_123", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "role": "CARD_ADMIN", "status": "ACTIVE", "managerId": "cuuser_5678", "managerFirstName": "Jane", "managerLastName": "Smith", "managerTitleId": "ti_1234", "managerTitleName": "Engineering Manager", "departmentId": "cudmnt_1234", "departmentName": "Engineering", "locationId": "culoc_1234", "locationName": "San Francisco", "titleId": "ti_5678", "titleName": "Software Engineer" }

List cards belonging to the calling user. You can filter by status views (ACTIVE, EXPIRED, LOCKED, TERMINATED, WAITING_ACTIVATION). Results are paginated - use limit and cursor for pagination.

Example 1: Getting all my active cards: { "status": ["ACTIVE"] }

Example 2: Getting all my cards (any status): {}

Example 3: Getting my active and locked cards: { "status": ["ACTIVE", "LOCKED"] }

List expenses with filters. expense types (BILLPAY, CARD, CLAWBACK, REIMBURSEMENT),

Date Filtering (only one type can be used at a time):

• Purchase Date: purchased_at_start/purchased_at_end
• Filter by when expense was purchased. Date must be in UTC timezone.
• Posted Date: posted_at_start/posted_at_end
• Filter by when expense was posted. Date must be in UTC timezone.
• Reimbursement Submission Date: reimbursement_submitted_at_start/reimbursement_submitted_at_end
• Filter by when reimbursement was submitted (only works with REIMBURSEMENT type). Date must be in UTC timezone.

Amount Filtering (all amounts in USD):

• min_amount: Filter expenses with amount greater than or equal to this value (in USD, supports decimals with up to 2 places)
• max_amount: Filter expenses with amount less than or equal to this value (in USD, supports decimals with up to 2 places)

Text Search:

• search: Search expenses by merchant name, memo, or other text fields (e.g., "nike", "lunch")

Limit Filtering:

• limit_ids: Filter expenses by spend limit IDs (e.g., ["limit_123", "limit_456"])

Additional Fields:

• additional_fields: Array of optional fields to include in response. Supported values:
• "TRAVEL_METADATA"
• Includes flight, car rental, lodging, and train travel data
• "LOCATION"
• Includes expense location details (country, city, coordinates, etc.)

Understanding Expense Lifecycle and Compliance Status:

Expense Lifecycle: 1. New expense created (card transaction or reimbursement submitted) 2. Documentation phase: System checks if documentation is required (receipts, memo, attendees, etc.) 3. Spender submits documentation if needed 4. Review phase: System checks if approval/review is required based on company policy 5. Reviewer reviews and approves/rejects if necessary 6. Expense is finalized

Each expense returns TWO sets of compliance-related fields:

A. DOCUMENTATION COMPLIANCE (for spenders - receipts, memo, attendees):

• documentationComplianceStatus: Status of documentation requirements that the spender must fulfill
• "NOT_REQUIRED"
• Company policy does not require any documentation for this expense. Empty receipts/memo are acceptable.
• "COMPLETED"
• All required documentation has been provided according to policy.
• "DUE"
• Documentation is required by policy but not yet provided. Check missingDocumentations field for specifics.
• "OVERDUE"
• Required documentation is past its submission deadline. Check missingDocumentations field for specifics.
• missingDocumentations: Array of specific items required by policy but not yet provided. Possible values: ["MEMO", "RECEIPT", "ATTENDEES", "EXTENDED_FIELD"]
• Empty array []
• Either no documentation is required OR all required documentation is complete
• Non-empty array
• Lists specific items that must be provided (e.g., ["MEMO", "RECEIPT"])
• documentationSubmissionDeadline: The UTC timestamp by which documentation must be submitted (only present if documentation is required)

B. REVIEW COMPLIANCE (for reviewers - approval/rejection):

• reviewComplianceStatus: Status of review/approval requirements that the reviewer must fulfill
• "NOT_REQUIRED"
• Company policy does not require review/approval for this expense.
• "COMPLETED"
• The expense has been reviewed and approved/rejected.
• "DUE"
• Review is required by policy but not yet completed.
• "OVERDUE"
• Required review is past its deadline.
• reviewDeadline: The UTC timestamp by which the review must be completed (only present if review is required)

KEY DISTINCTIONS:

• DocumentationComplianceStatus="NOT_REQUIRED" and missingDocumentations=[] → Documentation not required by company policy
• Empty receipts/memo with documentationComplianceStatus="DUE" or "OVERDUE" and missingDocumentations=["RECEIPT","MEMO"] → Documentation IS required by policy but missing
• reviewComplianceStatus="DUE" or "OVERDUE" → Expense is waiting for someone to review/approve it
• reviewComplianceStatus="NOT_REQUIRED" → No approval needed

All dates should be in ISO 8601 format (e.g., "2025-04-01T07:00:00.000Z"). Date must be in UTC timezone. All amounts are assumed to be in USD currency. Results are paginated - use limit and cursor for pagination.

Example 1: Getting all my reimbursements: { "types": ["REIMBURSEMENT"], }

Example 2: Getting all card expenses purchased in April 2025 (UTC timezone): { "types": ["CARD"], "purchased_at_start": "2025-04-01T00:00:00.000Z", "purchased_at_end": "2025-04-30T23:59:59.999Z" }

Example 3: Getting reimbursements for transactions after a specific date (UTC timezone): { "types": ["REIMBURSEMENT"], "purchased_at_start": "2025-04-01T07:00:00.000Z" }

Example 4: Getting my expenses that are missing compliance documentation (e.g. receipts, memo): { "missing_compliance_documentation": true }

Example 5: Getting expenses between $100 and $500: { "min_amount": 120.78, "max_amount": 500.00 }

Example 6: Search for Nike expenses: { "search": "nike" }

Example 7: Getting expenses for a specific limit: { "limit_ids": ["limit_123"] }

Example 8: Getting expenses with travel metadata and location data: { "types": ["CARD"], "additional_fields": ["TRAVEL_METADATA", "LOCATION"] }

Get all limits that apply to the current user with pagination support.

This includes:

• User Limit: The personal spending budget for the user
• Spend Limits: Shared budgets/limits where the user is a member

Each limit shows:

• Limit amount and remaining balance
• Period type (MONTHLY, QUARTERLY, etc.)
• Status (ACTIVE, EXPIRED, etc.)
• Start and end dates
• Amount spent in current period

Pagination:

• Use 'limit' parameter to specify how many spend limits to return (default: 100, max: 1000)
• Use 'cursor' parameter to paginate through results (use next_cursor from previous response)

Example usage:

• "What are my spending limits?"
• "How much budget do I have left?"
• "Show me all my limits"
• "Show me the first 10 limits" (with limit: 10)

List users with optional filtering and pagination

This tool retrieves a paginated list of all users in the system with full control over sorting and pagination. Use this when you need to browse through users, get multiple users at once, or need specific sorting.

Parameters:

• cursor: Optional pagination cursor from a previous response to get the next page
• limit: Number of users to return (1-1000, default: 100)
• direction: Sort direction - "ASC" or "DESC" (default: "ASC")
• sort: Field to sort by - "FIRST_NAME", "LAST_NAME", "EMAIL", etc. (default: "FIRST_NAME")

Example Input 1 (basic, with defaults): {}

Example Input 2 (with pagination and sorting): { "limit": 50, "direction": "DESC", "sort": "LAST_NAME", "cursor": "cursor_1234" }

Example Output: { "items": [ { "id": "cuuser_123", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "role": "CARD_ADMIN", "status": "ACTIVE", "managerId": "cuuser_5678", "managerFirstName": "Jane", "managerLastName": "Smith", "managerTitleId": "ti_1234", "managerTitleName": "Engineering Manager", "departmentId": "cudmnt_1234", "departmentName": "Engineering", "locationId": "culoc_1234", "locationName": "San Francisco", "titleId": "ti_5678", "titleName": "Software Engineer" } ], "nextCursor": "cursor_5678" }

List users by name or email

This tool allows you to search for users by name or email. It will return a paginated list of up to 10 users that match the search criteria, sorted by first name. If you only have the name or email, you can use this tool to find the user ID and their full details.

Example Input 1 (search by name): { "search_text": "John Smith" }

Example Input 2 (search by email): { "search_text": "john.smith@example.com" }

Example Output: { "items": [ { "id": "cuuser_123", "firstName": "John", "lastName": "Smith", "email": "john.smith@example.com", "role": "CARD_ADMIN", "status": "ACTIVE", "managerId": "cuuser_5678", "managerFirstName": "Jane", "managerLastName": "Doe", "managerTitleId": "ti_1234", "managerTitleName": "Engineering Manager", "departmentId": "cudmnt_1234", "departmentName": "Engineering", "locationId": "culoc_1234", "locationName": "San Francisco", "titleId": "ti_5678", "titleName": "Software Engineer" } ], "nextCursor": "cursor_1234" }

Query Brex expense data using natural language for comprehensive financial and operational analytics

This tool provides access to advanced expense reporting and analytics powered by specialized data models. It allows you to ask questions about spending patterns, compliance issues, budget performance, and organizational metrics using natural language queries.

ADMIN ONLY: This tool is only accessible to account administrators.

Supported Analytics Capabilities

Financial Analysis

• Total spending analysis by time period, department, merchant, vendor, or category
• Spending trends, comparisons (month-over-month, year-over-year), and forecasting
• Top spenders, vendors, and merchants by spend volume
• Category-level analytics across 40+ expense categories (travel, software, meals, etc.)
• Transaction-level details with temporal analysis (daily, weekly, monthly, quarterly)
• Average transaction amounts, statistical outliers, and anomaly detection

Compliance & Policy Monitoring

• Identify expenses missing receipts or memos
• Track policy violations and out-of-policy expenses
• Monitor expense approval workflows and pending reviews
• Audit manually approved transactions without documentation
• Receipt compliance tracking by card, user, or department
• Expense status tracking (APPROVED, SUBMITTED, OUT_OF_POLICY, DRAFT, CANCELED, SETTLED)

Budget & Spend Limit Management

• Track department budgets and identify overruns (by $ or %)
• Monitor spend limit utilization across organizational units
• Compare actual vs. budgeted spend by department or category
• Analyze budget performance over time
• Identify recently created or edited budgets/limits

Organizational Analytics

• Employee expense patterns and rankings (top spenders per department/category)
• Department-wise spending breakdowns and comparisons
• Manager-employee expense relationships and reporting hierarchies
• Location-based expense analysis
• User-level metrics including approval ratios and compliance rates

Vendor & Merchant Analysis

• Top vendors/merchants by spend volume or transaction count
• Vendor performance tracking and quarterly/monthly trends
• Identify recurring vs. one-time vendor relationships
• Categorize SaaS vs. non-SaaS vendor spend
• Maximum spend tracking per vendor

Card Transaction Analysis

• Corporate card transaction monitoring and compliance
• Card-specific spending patterns and receipt attachment rates
• Transaction counts and dollar amounts by card or user
• Location-based transaction analysis
• Payment status tracking (NOT_STARTED through CLEARED)

Operational Reporting

• Pending approval workflows and manager review queues
• Reimbursement tracking and payout status
• Disputed transactions by user or time period
• Transaction settlement status and payment processing
• Card vs. reimbursement expense comparisons

Available Data

The tool has access to 9 specialized analytical views:

• Expense Analysis View: Core expense metrics and temporal analysis
• Vendor & Merchant Analysis View: Supplier spend management
• Category Spending Analysis View: Expense categorization across 40+ categories
• Department Expense Analysis View: Departmental budget tracking
• Employee Expense Analysis View: Individual employee monitoring
• Organizational Hierarchy View: Management structure and reporting relationships
• Card Transaction Analysis View: Corporate card monitoring
• Expense Compliance View: Policy adherence and audit support
• Payment Tracking: Complete payment processing workflows

Expense Types Supported

• CARD: Corporate card transactions
• REIMBURSEMENT: Employee reimbursements
• BILLPAY: Vendor bill payments
• CLAWBACK: Reversed or recovered expenses

Example Queries

Financial Analytics

1. "What was our total spending on travel expenses in Q4 2025?" 2. "Show me the top 10 vendors by spend last month" 3. "How much did the Engineering department spend on software purchases?" 4. "Compare our card spending between December and January" 5. "What are the largest transactions over $10,000 this quarter?" 6. "Show me spending trends over the last 6 months" 7. "What's our average expense amount by category?"

Compliance & Policy

8. "Which employees have the most transactions missing receipts?" 9. "Show me all manually approved expenses without documentation" 10. "List expenses that are out of policy this month" 11. "What's our receipt compliance rate by department?"

Budget & Spend Limits

12. "Which departments are most over budget by percentage?" 13. "Show me budget utilization for all departments" 14. "What budgets were recently created or edited?"

Organizational

15. "Who are the top 5 spenders in the Engineering department?" 16. "Show me employee expense patterns by manager" 17. "Which users have the most spend per merchant category?"

Vendor Analysis

18. "Show me all recurring SaaS vendor spend from highest to lowest" 19. "What are our top non-SaaS vendors by spend?" 20. "Compare vendor spend quarter over quarter"

Operational

21. "Which managers have the most expenses pending their review?" 22. "Show me all disputed transactions this year by user" 23. "What's the status of pending reimbursements?"

Example Input

{ "question": "What was our total spending on travel expenses in Q4 2025?" }

Example Output

{ "answer": "Your total spending on travel expenses in Q4 2025 was $125,450.32. Here's the breakdown by month: October: $38,200, November: $42,150, December: $45,100. The top categories were flights (45%), hotels (35%), and ground transportation (20%).", "metadata": { "toolCalls": [ { "name": "query_expenses", "input": {...}, "result": {...} } ] } }

When to Use This Tool

✓ USE this tool for:

• Any aggregate analytics or reporting questions
• Compliance, policy, and audit queries
• Budget tracking and spend limit monitoring
• Top N rankings (top spenders, vendors, categories)
• Trend analysis and comparisons
• Statistical analysis (averages, outliers, anomalies)
• Operational reporting (pending reviews, approvals, disputes)
• Multi-dimensional analysis (department + category, user + time period)

✗ DO NOT use this tool for:

• Looking up a specific expense by ID (use get_expense_by_id instead)
• Fetching a user's personal expense list (use list_expenses instead)
• Retrieving a specific card by ID (use get_card_by_id instead)
• Non-financial queries unrelated to expenses