Skip to main content
GET
/
cards
List cards
curl --request GET \
  --url https://api.cartevo.co/api/v1/cards \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "company_id": "eca5e982-00b5-4aa2-b709-7d5cd673e95c",
    "statistics": {
      "total": 5,
      "active": 5,
      "frozen": 0,
      "terminated": 0,
      "pending": 0,
      "failed": 0,
      "total_balance": 16,
      "available_slots": 5,
      "by_customer": {}
    },
    "cards": [
      {
        "id": "91b3c6d6-111b-44da-9f81-16f019bebe8c",
        "customer_id": "4d4dad81-7899-4612-a9f6-133ce56a4507",
        "status": "ACTIVE",
        "balance": 5,
        "masked_pan": "**** **** **** 5407",
        "currency": "USD",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "is_active": true,
        "is_virtual": true
      }
    ]
  }
}

​
Overview

GET /cards returns every card issued under your company, plus a statistics block summarizing counts and balances by status and per customer. Use it to populate dashboards, reconcile your own card records, or look up a specific card by last-4.

​
When to use it

  • Render a “all cards” view in your back-office.
  • Reconcile your records against Cartevo’s source of truth.
  • Find a card by last-4 when a customer reports an issue without knowing the card ID.

​
Prerequisites

  • Authenticated as a company user.

​
Request

​
Headers

NameRequiredDescription
AuthorizationYesBearer <access_token>

​
Query parameters

NameTypeRequiredDescription
statusstringNoFilter by card status. One of PENDING, ACTIVE, FROZEN, SUSPENDED, TERMINATED, FAILED.
brandstringNoFilter by VISA or MASTERCARD (case-insensitive).
last4stringNoLast 4 digits of the card PAN. Useful for support lookups.
syncbooleanNoIf true, force a re-fetch from the upstream issuer before returning. Slower; default false.

​
Response

​
200 — Success

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": {
    "company_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "statistics": {
      "total": 142,
      "active": 120,
      "frozen": 5,
      "terminated": 15,
      "pending": 1,
      "failed": 1,
      "total_balance": 18450.75,
      "available_slots": 858,
      "by_customer": {
        "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b": {
          "cards": 2,
          "balance": 245.5
        }
      }
    },
    "cards": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "customer_id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
        "status": "ACTIVE",
        "balance": 100.0,
        "masked_pan": "4111********1111",
        "brand": "VISA",
        "currency": "USD",
        "is_active": true,
        "is_virtual": true,
        "created_at": "2026-05-09T10:15:00.000Z",
        "updated_at": "2026-05-09T10:15:02.500Z"
      }
    ]
  }
}
FieldTypeDescription
data.company_idstringEchoes your company ID for client-side validation.
data.statistics.totalintegerNumber of cards (filtered by query, if any).
data.statistics.total_balancenumberSum of balance across all returned cards (USD).
data.statistics.available_slotsintegerHow many more cards your company can issue under its current plan.
data.statistics.by_customerobjectMap of customer_id → { cards, balance }.
data.cards[]arrayCard records — see GET /cards/{id} for the per-card field reference.
Note: This endpoint is not paginated — it returns the full set in a single response. If your company has more than a few thousand cards, prefer per-customer lookups via GET /customers/{id}/cards (currently undocumented; reach out if you need it).

​
Error responses

StatusTrigger
401Missing or expired Bearer token.
400Invalid status or brand value.

​
Code examples

cURL
curl -G https://api.cartevo.co/api/v1/cards \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "brand=VISA"
Node.js (axios)
const { data } = await axios.get("https://api.cartevo.co/api/v1/cards", {
  headers: { Authorization: `Bearer ${token}` },
  params: { status: "ACTIVE", brand: "VISA" },
});
console.log(`${data.data.statistics.total} active VISA cards`);

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

200 - application/json

A list of cards with company statistics.

​
success
boolean
Example:

true

​
statusCode
integer
Example:

200

​
message
string
Example:

"Data retrieved successfully"

​
data
object