> ## Documentation Index > Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt > Use this file to discover all available pages before exploring further. # List Cards > List all cards belonging to your company, with optional filters by status, brand, or last-4 digits, plus aggregate statistics. ## 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 | Name | Required | Description | | --------------- | -------- | ----------------------- | | `Authorization` | Yes | `Bearer ` | ### Query parameters | Name | Type | Required | Description | | -------- | ------- | -------- | ------------------------------------------------------------------------------------------------- | | `status` | string | No | Filter by card status. One of `PENDING`, `ACTIVE`, `FROZEN`, `SUSPENDED`, `TERMINATED`, `FAILED`. | | `brand` | string | No | Filter by `VISA` or `MASTERCARD` (case-insensitive). | | `last4` | string | No | Last 4 digits of the card PAN. Useful for support lookups. | | `sync` | boolean | No | If `true`, force a re-fetch from the upstream issuer before returning. Slower; default `false`. | ## Response ### 200 — Success ```json theme={null} { "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" } ] } } ``` | Field | Type | Description | | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `data.company_id` | string | Echoes your company ID for client-side validation. | | `data.statistics.total` | integer | Number of cards (filtered by query, if any). | | `data.statistics.total_balance` | number | Sum of `balance` across all returned cards (USD). | | `data.statistics.available_slots` | integer | How many more cards your company can issue under its current plan. | | `data.statistics.by_customer` | object | Map of `customer_id → { cards, balance }`. | | `data.cards[]` | array | Card records — see [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-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`](/api-reference/endpoint/get-customer-by-id) (currently undocumented; reach out if you need it). ### Error responses | Status | Trigger | | ------ | ---------------------------------- | | `401` | Missing or expired Bearer token. | | `400` | Invalid `status` or `brand` value. | ## Code examples ```bash cURL theme={null} curl -G https://api.cartevo.co/api/v1/cards \ -H "Authorization: Bearer $TOKEN" \ --data-urlencode "status=ACTIVE" \ --data-urlencode "brand=VISA" ``` ```js Node.js (axios) theme={null} 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`); ``` ## Related * [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-id) — full card detail (with optional reveal). * [`POST /cards`](/api-reference/endpoint/post-create-card) — issue a new card. ## OpenAPI ````yaml GET /cards openapi: 3.1.0 info: title: Cartevo API description: Essential endpoints for wallets, transactions, customers and conversion. version: 1.0.0 servers: - url: https://api.cartevo.co/api/v1 security: - bearerAuth: [] paths: /cards: get: summary: List cards description: >- Retrieves a list of all cards for the authenticated company with statistics. responses: '200': description: A list of cards with company statistics. content: application/json: schema: $ref: '#/components/schemas/ListCardsResponse' components: schemas: ListCardsResponse: allOf: - $ref: '#/components/schemas/StandardResponse' - type: object properties: data: type: object properties: company_id: type: string format: uuid example: eca5e982-00b5-4aa2-b709-7d5cd673e95c statistics: $ref: '#/components/schemas/CardStatistics' cards: type: array items: $ref: '#/components/schemas/Card' StandardResponse: type: object properties: success: type: boolean example: true statusCode: type: integer example: 200 message: type: string example: Data retrieved successfully CardStatistics: type: object properties: total: type: integer example: 5 active: type: integer example: 5 frozen: type: integer example: 0 terminated: type: integer example: 0 pending: type: integer example: 0 failed: type: integer example: 0 total_balance: type: integer example: 16 available_slots: type: integer example: 5 by_customer: type: object additionalProperties: type: object properties: customer_id: type: string format: uuid cards_count: type: integer example: 1 total_balance: type: integer example: 5 active_cards: type: integer example: 1 Card: type: object properties: id: type: string format: uuid example: 91b3c6d6-111b-44da-9f81-16f019bebe8c customer_id: type: string format: uuid example: 4d4dad81-7899-4612-a9f6-133ce56a4507 status: type: string example: ACTIVE balance: type: number example: 5 masked_pan: type: string example: '**** **** **** 5407' currency: type: string example: USD created_at: type: string format: date-time updated_at: type: string format: date-time is_active: type: boolean example: true is_virtual: type: boolean example: true securitySchemes: bearerAuth: type: http scheme: bearer ````