API Reference

List vendor cards

get
https://api.cardda.com/v1/vendor_cards

Returns a paginated list of vendor cards (corporate cards issued by Cardda). Each row in the response represents a single physical or virtual card and exposes its current status, spending limits, balance, and the user it is assigned to.

The result is scoped per-caller across every company the caller has
permission in (via policy_scope), not by the company-id header — the
header is not consulted for this endpoint, and omitting it still returns
200 with the caller's full permitted scope across companies. To narrow the
results, filter explicitly; user_id is a cardholder filter (it returns
only cards assigned to that user), not a per-company restriction.

  • Admins see every card in their permitted scope.
  • Company members with the vendor_cards_manage permission see every
    card of the companies they manage.
  • Regular users see only cards assigned to them (user_id matches their
    Firebase user id).

The type field (issuing vendor / STI sub-class) is returned to every
caller: it is the model's Single Table Inheritance discriminator column, so
it always serializes into the row (the controller's methods.push(:type) if admin? is a no-op — type is already a column, not a computed method).

Response structure

Each item is a VendorCard plus the following computed fields:

FieldDescription
spentAmount spent in the current spending interval, as an integer in the minor unit of the transactions' currency (whole pesos for CLP). Sign-flipped from the negative amount_cents of the spends.
remaining_balanceFunds still available on the card, as a decimal string in the card currency (not cents).
preference_restricted_spendableSpendable amount taking active preferences into account.
spent_in_vendor_intervalAmount spent in the vendor's billing interval.
fees_in_vendor_intervalFees accrued in the vendor's billing interval.
limit_amountHard spending limit (limit_based strategy).
limit_amount_preferencePending limit change (waiting to be pushed to the vendor).
allocated_amountFunds currently loaded onto the card (allocation_based strategy).
allocated_amount_preferencePending allocation change.

Filtering grammar

Every column documented below accepts the MongoDB-style operators described in Filters: $gt, $gte, $lt, $lte, $in, $nin, $ne, $regex, $or. Combine them on a single field (created_at={"$gte":"2026-01-01T00:00:00Z","$lt":"2026-02-01T00:00:00Z"}) or across fields (status=active&user_id=...).

Common queries

# Active + inactive + pending cards of a specific user (the dashboard's default)
GET /v1/vendor_cards?\
  $or=[{"status":"active"},{"status":"inactive"},{"status":"pending"}]&\
  user_id=<firebase_uid>&\
  _order=desc&_field=created_at&_start=0&_end=25

# Search by name OR last4 (cardholder lookup)
GET /v1/vendor_cards?\
  $or=[{"name":{"$regex":"maria"}},{"last4":{"$regex":"^4242"}}]&\
  _start=0&_end=50

# Cards assigned to a specific person, with allocation-based control
GET /v1/vendor_cards?\
  user_id=<firebase_uid>&\
  spending_control_strategy=allocation_based

# Cards by id (batch lookup, e.g. to refresh a dashboard view)
GET /v1/vendor_cards?id={"$in":["Q2FyZDoxMDIwNjQ5Mw==","Q2FyZDoxMDIwNjQ5NA=="]}
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
integer
≥ 0

If all the cards where in an array, this would represent the index of the first item returned in the response

integer
≥ 0

If all the cards where in an array, this would represent the index of the last item returned in the response

string
enum

The order method, which can be ascending or descending

Allowed:
string

The field used to sort, the example illustrates a response that would be sorted by the creation date

string

Filter by card id. Cardda card ids are base64-encoded vendor identifiers.
Use id={"$in":["...", "..."]} for batch lookups.

string

Firebase user id of the cardholder.

string
enum

Lifecycle status of the card. The most common production query is
$or=[{"status":"active"},{"status":"inactive"},{"status":"pending"}]
to exclude canceled cards from a dashboard.

Allowed:
string

Free-form label assigned by the company (e.g. "Sales — María Pérez"). Most
clients combine this with last4 via $or for cardholder lookup.

string

Last four digits of the PAN. Accepts a plain 4-digit string for exact
match (e.g. 4242) or a JSON-encoded operator object for prefix /
regex search (e.g. {"$regex":"^42"}). No length constraint is set
on the schema so both forms validate against codegen clients.

boolean

Whether the card has a physical companion. true for plastic, false for virtual-only.

string
enum

How the card limits spend.

  • limit_based — capped at limit_amount per limit_interval (daily / weekly / monthly / etc.).
  • allocation_based — funded with allocated_amount; declines when funds run out (no per-interval limit).
Allowed:
string
enum

ISO-4217 code of the limit currency.

Allowed:
string
enum

Issuing vendor (STI sub-class). Useful when filtering by issuing partner — most companies will only see one or two values here.

string

Creation timestamp. Accepts comparators ($gte, $lt) and $in via a
JSON-encoded operator object, or a single ISO-8601 date-time string.
Schema is type: string (no format) so both forms validate.

string

Logical OR across sub-conditions. Used by the dashboard to paint
"all-non-closed" feeds: $or=[{"status":"active"},{"status":"inactive"},{"status":"pending"}].

Headers
uuid
required

UUID of the company that owns the card.

Responses

401

Unauthorized — missing or invalid bearer token, or the caller is not
permitted to list vendor cards (Pundit authorization failure). Returned
with an empty body. Note: the company-id header is not required for
this endpoint.

Updated 14 days ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 14 days ago

Did this page help you?