Track your BatchData wallet balance, spend, and credit card history programmatically. This guide walks through the three wallet endpoints under /api/v1/wallet/, the parameters each one accepts, the shape of the responses, and best practices for token scoping.
Overview
The wallet API exposes three GET endpoints:
GET /api/v1/wallet/balance— current wallet balance, currency, and timestamp.GET /api/v1/wallet/consumption-report— debit/credit breakdown over a date range, grouped by hour/day/week/month. Available as JSON or streaming CSV.GET /api/v1/wallet/credit-card-transactions— paginated history of credit card top-ups, refunds, and refund failures.
All three wallet endpoints are free to call. They do not deduct from your wallet balance — including the CSV variant of the consumption report. You can safely poll /wallet/balance from a dashboard or monitor without burning credits.
Authentication. Every wallet endpoint requires an API token with the matching permission (wallet-balance, wallet-consumption-report, wallet-credit-card-transactions). The token is passed via the Authorization: Bearer <token> header. See the Authentication section below for token-scoping recommendations.
GET /api/v1/wallet/balance
Returns the current wallet balance for the authenticated team. Free to call.
Request:
GET /api/v1/wallet/balance Authorization: Bearer <token>
Response (200):
{
"results": {
"balance": 42.5000,
"currency": "USD",
"asOf": "2026-05-19T18:43:21+00:00"
},
"status": {
"code": 200,
"message": "OK"
}
}
Field notes:
balance— current wallet balance incurrency. Rounded to four decimal places (trailing zeros are preserved in the JSON response).currency— ISO 4217 currency code. AlwaysUSDin the current API version.asOf— ISO 8601 timestamp indicating when the balance was last computed.
GET /api/v1/wallet/consumption-report
Returns a breakdown of wallet credit consumption between start_date and end_date, grouped by group_by (default hour). The response includes a summary of total debits/credits/net change plus a per-period series under results.data. Each period reports debit/credit totals broken out by origin and by API endpoint. Free to call — JSON and CSV variants alike.
Query parameters:
start_date(required) — inclusive lower bound (ISO 8601 calendar date).end_date(required) — inclusive upper bound (ISO 8601 calendar date).origin(optional) — narrow to a single origin (e.g.api_request,list_builder_ui,wallet_card_top_up).group_by(optional) —hour(default),day,week, ormonth. Controls the bucket grain inresults.data.format(optional) —json(default) returns the JSON payload below.csvstreams atext/csvfile with headerDate,Type,Amount,Balance After,Origin,Reference ID,Endpoint,Description.
Date validation runs against the server's UTC date. start_date and end_date must each be on or before the current server UTC date, and end_date must be on or after start_date. The two dates must additionally be within 366 days of each other. If you are in a negative UTC offset (e.g. US time zones in standard time), you may see a 422 response near local midnight for an end_date that looks valid in local time but is one day ahead in UTC — use the server's UTC date as the ceiling, not the local date.
Request:
GET /api/v1/wallet/consumption-report?start_date=2026-05-01&end_date=2026-05-15&group_by=hour Authorization: Bearer <token>
Response (200, JSON):
{
"results": {
"summary": {
"total_debit": 12.4500,
"total_credit": 100.0000,
"net_change": 87.5500,
"period_start": "2026-05-01",
"period_end": "2026-05-15"
},
"data": [
{
"period": "2026-05-01T14:00:00",
"debit": 0.45,
"credit": 0,
"by_origin": {
"address_verification_single_ui": { "debit": 0.135 },
"phone_verification_single_ui": { "debit": 0.007 }
},
"by_endpoint": {
"/api/v1/address/verify": 0.135,
"/api/v1/phone/verification": 0.007
}
}
]
},
"status": {
"code": 200,
"message": "OK"
}
}
Period format by group_by:
hour—%Y-%m-%dT%H:00:00(e.g.2026-05-01T14:00:00)day—%Y-%m-%d(e.g.2026-05-01)week—%Y-WwwISO week (e.g.2026-W18)month—%Y-%m(e.g.2026-05)
by_endpoint keys are full API route paths (e.g. /api/v1/address/verify). They populate for both api_request origin and UI-origin debits, since UI flows hit internal API routes via the same dispatcher.
CSV format. With format=csv, the response is a streaming text/csv attachment named wallet-consumption.csv containing one row per transaction:
Date,Type,Amount,Balance After,Origin,Reference ID,Endpoint,Description 2026-05-01 14:00:00,Debit,0.45,42.05,api_request,req_abc123,property-lookup-all-attributes,Property lookup request
The CSV variant ignores pagination and streams every matching transaction.
GET /api/v1/wallet/credit-card-transactions
Returns a paginated list of credit card transactions on the wallet (top-ups, refunds, refund failures). Free to call.
Query parameters:
start_date(optional) — inclusive lower bound on transactioncreated_at.end_date(optional) — inclusive upper bound on transactioncreated_at. Must be on or afterstart_datewhen both are supplied.status(optional) — filter to a single status.0= pending,1= paid,2= failed.page(optional) — 1-based page number. Defaults to1.per_page(optional) — items per page. Defaults to15, maximum100.
Request:
GET /api/v1/wallet/credit-card-transactions?status=1&per_page=25 Authorization: Bearer <token>
Response (200):
{
"results": {
"data": [
{
"id": 12345,
"credits": 100.0,
"sales_tax_charge": 8.25,
"card_processing_fee": 3.27,
"card_brand": "visa",
"card_last4": "4242",
"status": 1,
"created_at": "2026-05-15T14:30:21.000000Z"
}
],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 15,
"total": 73
}
},
"status": {
"code": 200,
"message": "OK"
}
}
Field notes:
status— transaction status:0= pending,1= paid,2= failed.card_processing_fee— payment processor fee applied to the transaction (in USD).card_last4— last four digits of the card used.meta— Laravel pagination metadata. Onlycurrent_page,last_page,per_page, andtotalare returned (the wallet controller hand-builds the meta object and omits Laravel's defaultfrom,to,path, etc.).
Authentication
Every wallet endpoint requires a Bearer token with the matching permission:
Endpoint | Required permission |
|
|
|
|
|
|
Best practice: scope a dedicated token to the wallet endpoints. Rather than reusing an existing general-purpose API token, provision a new token restricted to only the three wallet-* permissions:
Log in to the BatchData app.
Go to API Tokens and click New Token.
Enable only the
wallet-balance,wallet-consumption-report, andwallet-credit-card-transactionspermissions.Save and copy the token into your reporting/finance system.
Three reasons to keep wallet credentials separate:
Wallet endpoints surface financial data. Isolating them from data-access tokens keeps the financial surface narrow.
If a token leaks, blast radius is limited to read-only financial reporting — not property lookups or skip-trace credits.
Finance and operations teams can manage their own credentials without touching the data team's token, and rotate them independently.
See the wallet endpoints release note for the same step-by-step setup, plus a quick-start curl example.
Rate limits
Wallet endpoints share the standard BatchData rate limit. If you exceed it, expect a 429 Too Many Requests response — back off and retry. Because the wallet endpoints are free to call, there is no credit-cost reason to throttle aggressively on your side; rate-limit considerations are the only concern.