Pagination, Filtering & Rate Limits
The list endpoints across Cardholders, Cards, Transactions, and Fees share a common pagination shape and a broadly consistent set of query parameters. This page documents that shared shape once, so individual Guides can link back here instead of repeating it.
Common pagination parameters
| Parameter | Type | Default | Notes |
|---|---|---|---|
limit | integer | 50 | Maximum number of results per page. Maximum allowed value is 200. |
offset | integer | 0 | Number of rows to skip before returning results — use for page-by-page traversal (offset = page_number × limit). |
before | string (Unix timestamp, seconds) | — | Returns only records created before this time. |
after | string (Unix timestamp, seconds) | — | Returns only records created after this time. |
orderBy | string (enum, endpoint-specific) | endpoint-specific | See per-endpoint tables below. |
sort | string (asc | desc) | endpoint-specific | Sort direction applied to orderBy. |
Every paginated list response shares this envelope:
{
"status": "success",
"items": [ /* ... */ ],
"total": 137,
"limit": 50,
"offset": 0
}total reflects the total number of records matching your filters (not just the current page). Use it together with limit/offset to know when you've reached the end.
GET /cardholders
| Parameter | Values |
|---|---|
status | 0 Pending · 1 Approved · 2 Compliance Decline · 3 Under Review · 4 Draft · 5 Deleted · 6 Error · 7 Admin Decline |
orderBy | cardholderId | status | lastName | dateCreated |
sort | asc | desc |
before / after / limit / offset | As above |
Example: the 20 most recently created Approved cardholders:
GET /cardholders?status=1&orderBy=dateCreated&sort=desc&limit=20&offset=0GET /cards
| Parameter | Values |
|---|---|
issuerCardStatus | 0 Pending · 1 Active · 2 On Hold · 3 Closed · 4 Not Activated |
cardholderId | Filter to a single cardholder's cards |
orderBy | cardId | issuerCardStatus | cardholderId | cardHolderLastName | createdDatetime |
sort | asc | desc |
before / after / limit / offset | As above |
Example: all active cards for a given cardholder:
GET /cards?cardholderId=10532&issuerCardStatus=1GET /cards/transactions
| Parameter | Values |
|---|---|
cardId | Filter to a single card |
cardholderId | Filter to a single cardholder (across all their cards) |
transId | Look up a specific transaction by its ID |
transStatus | 1 Pending · 2 Cleared · 3 Completion · 4 Declined · 5 Error |
transType | Filter to a specific transaction type — see Statuses & Enums |
orderBy | Sort results by a given field |
sort | asc | desc |
before / after / limit / offset | As above |
GET /cards/fees
| Parameter | Values |
|---|---|
cardId | Filter to a single card |
cardholderId | Filter to a single cardholder |
feeId | Look up a specific fee by its ID |
feeStatus | 1 Pending · 2 Cleared · 3 Completion · 4 Declined · 5 Error |
feeType | Integer 1 through 5 |
orderBy | Sort results by a given field |
sort | asc | desc |
before / after / limit / offset | As above |
Reconciling transactions and fees
GET /cards/transactions and GET /cards/fees return non-overlapping datasets. A single real-world event (e.g. a foreign-currency purchase) may produce both a transaction record and one or more associated fee records. To build a complete picture of activity on a card, query both endpoints for the same time range and cardId/cardholderId. See Reconcile Transactions & Fees and Transactions & Fees for the full model.
GET /wallets
Neither endpoint currently accepts pagination or filter parameters. GET /wallets returns all wallets in the Program, and GET /wallets/{walletId} returns a single wallet by ID.
Rate limits
Specific rate limit thresholds are not surfaced via response headers. If you receive a
429response, back off and retry. See Errors & Status Codes. If rate limits become relevant to your integration's throughput, raise a support ticket.