Guides

Tutorial: Filter transactions

The Cardda transaction endpoints — bank_transactions, card_transactions, the unified transactions view — share the same filtering grammar. This tutorial shows the patterns you'll use 95% of the time. For the formal grammar reference, see Filters.

All examples assume the standard headers:

Authorization: Bearer YOUR_API_KEY
company-id:    COMPANY_ID

1. Date ranges

The most common filter. created_at, occurred_at, and posted_at are typical.

# Card transactions in April 2026
GET /v1/card_transactions?occurred_at[$gte]=2026-04-01T00:00:00Z&occurred_at[$lt]=2026-05-01T00:00:00Z

# Bank transactions in the last 7 days, newest first
GET /v1/banking/bank_transactions?created_at[$gte]=2026-04-22T00:00:00Z&_order=desc&_field=created_at

ISO-8601 dates required (with Z suffix). Date-only strings (2026-04-01) are rejected — use the full timestamp.

2. Amount

# Bank transactions over CLP 1M
GET /v1/banking/bank_transactions?amount[$gte]=1000000

# Bank transactions between 100k and 500k
GET /v1/banking/bank_transactions?amount[$gte]=100000&amount[$lte]=500000
💡

Amounts are in the smallest unit of the currency (CLP cents are the same as CLP, but USD cents are 100x USD). Always check the currency field next to the amount.

3. Status (enum)

Each endpoint declares its valid status values. For bank_transactions:

draft, pending, authorized, confirmed, failed, rejected
# Pending or authorized only
GET /v1/banking/bank_transactions?status[$in]=["pending","authorized"]

# Anything except failed/rejected
GET /v1/banking/bank_transactions?status[$nin]=["failed","rejected"]

# Currently failed transactions sorted by failure time
GET /v1/banking/bank_transactions?status=failed&_order=desc&_field=updated_at

4. By recipient / merchant / counterparty

# Bank transactions to one specific recipient
GET /v1/banking/bank_transactions?recipient_id=11111111-1111-1111-1111-111111111111

# Card transactions at a specific merchant
GET /v1/card_transactions?merchant.name={"$regex":"AWS"}

# Card transactions by category
GET /v1/card_transactions?merchant.category={"$in":["software","cloud"]}

Note the merchant.name syntax — nested fields are dot-separated and the operator goes inside the JSON value.

5. Custom columns

If your company defined custom_columns (e.g. cost_center, project_code), you can filter on them too:

# Only transactions tagged to project ALPHA
GET /v1/transactions?custom_columns.project_code=ALPHA

# Multiple cost centers
GET /v1/transactions?custom_columns.cost_center={"$in":["FIN-01","FIN-02"]}

The available custom columns for your company are listed at GET /v1/custom_columns.

6. Combining (logical AND / OR)

# AND across fields (default behavior)
GET /v1/banking/bank_transactions?status=authorized&amount[$gte]=100000&created_at[$gte]=2026-04-01T00:00:00Z

# OR across fields — use $or
GET /v1/banking/bank_transactions?$or=[
  {"status":{"$in":["pending","authorized"]}},
  {"amount":{"$gte":1000000}}
]

The $or value is a JSON array of objects; URL-encode it before sending.

7. Practical recipes

Reconciliation: "things that should have settled by now but haven't"

GET /v1/banking/bank_transactions?\
status=authorized&\
created_at[$lt]=2026-04-22T00:00:00Z&\
_order=asc&_field=created_at

Anything in authorized for >48 h is suspicious. Investigate.

Month-end card-spend by user

# Per-user breakdown (the dedicated endpoint, not the index — see companies.spending_per_user)
GET /v1/companies/COMPANY_ID/spending_per_user?\
period_start=2026-04-01&period_end=2026-04-30

Failed payouts that need a manual retry

GET /v1/banking/bank_transactions?\
status=failed&\
failure_reason[$nin]=["insufficient_funds","duplicate"]&\
created_at[$gte]=2026-04-01T00:00:00Z

8. CSV export

For one-off reports, every index endpoint that supports CSV exposes a download_csv action:

curl 'https://api.cardda.com/v1/transactions/download_csv?created_at[$gte]=2026-01-01T00:00:00Z&created_at[$lt]=2026-02-01T00:00:00Z' \
  -H "Authorization: Bearer $API_KEY" \
  -H "company-id: $COMPANY_ID" \
  -o january.csv

The response is text/csv with a UTF-8 BOM (Excel-friendly).

Related

Updated 1 day ago