Three new GET endpoints under /api/v1/wallet/ are now available for tracking your BatchData wallet balance, spend, and credit card history programmatically. All three are free to call — they do not deduct from your wallet balance, so you can poll them safely from dashboards, finance pipelines, or monitoring systems.
What's new
GET /api/v1/wallet/balance— current wallet balance, currency, and the timestamp the balance was last computed.GET /api/v1/wallet/consumption-report— debit/credit breakdown over a date range, grouped by hour/day/week/month. Available as JSON or a streaming CSV download.GET /api/v1/wallet/credit-card-transactions— paginated history of credit card top-ups, refunds, and refund failures.
What's available
Polling for balance is free. None of the three endpoints deducts from your wallet — including the format=csv variant of the consumption report. You can build dashboards, run nightly reconciliation jobs, or send low-balance alerts without burning credits.
Consumption breakdowns. The consumption report breaks debits and credits out by origin (e.g. api_request, list_builder_ui, admin_adjustment) and by API endpoint, so you can see exactly which routes spent what during any window up to 366 days.
CSV exports. Pass format=csv on the consumption report to receive a text/csv attachment with one row per transaction — convenient for spreadsheets, Looker, or downstream BI tools.
Pagination on credit card history. The credit card transactions endpoint paginates with page and per_page (max 100) and supports filtering by status (0 pending, 1 paid, 2 failed).
Best practice: scope a new API token to the wallet endpoints
Rather than reusing an existing general-purpose API token, provision a new token restricted only to the three wallet permissions:
wallet-balancewallet-consumption-reportwallet-credit-card-transactions
Why scope a separate token?
Isolate financial data. Wallet endpoints surface balance and credit-card transaction history. Keeping that surface narrow prevents the same credential from accessing property data, skip-trace, or other paid endpoints.
Limit blast radius. If a token leaks, a wallet-only token reveals only read-only financial reporting — not property/skip-trace credits or write actions.
Independent rotation. Finance and operations teams can hold and rotate the wallet token without touching the data team's general-purpose credentials.
Step-by-step setup:
Log in to the BatchData app.
Navigate to API Tokens.
Click New Token.
Give the token a recognizable name (e.g.
Wallet reporting — finance team).In the permissions list, enable only these three:
wallet-balancewallet-consumption-reportwallet-credit-card-transactions
Leave every other permission disabled.
Save the token and copy it into your reporting/finance system.
Quick start
Once you have a wallet-scoped token, the simplest sanity-check call is:
curl https://api.batchdata.com/api/v1/wallet/balance \ -H "Authorization: Bearer YOUR_WALLET_TOKEN"
A successful response returns the current balance in USD, the currency code, and the timestamp the balance was computed. No charge is deducted by this call.
Learn more
For the full parameter reference, response schemas, period grouping options, CSV column layout, and field-by-field notes, see the Wallet endpoints reference in our Getting Started guides.