List cards

Retrieve a paginated list of cards. Cards can be filtered by cardholder, bound funding-source internal account, status, and platform-specific card identifier. If no filters are provided, returns all cards visible to the caller.

GET /cards

List cards

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/cards \
  --header 'Authorization: Basic <encoded-value>'

200

{
  "data": [
    {
      "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "status": "PENDING_KYC",
      "form": "VIRTUAL",
      "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
      "createdAt": "2026-05-08T14:10:00Z",
      "updatedAt": "2026-05-08T14:11:00Z",
      "platformCardId": "card-emp-001",
      "statusReason": "DELEGATION_REQUIRED",
      "brand": "VISA",
      "pinStatus": "OK",
      "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2029,
      "cardCapabilities": {
        "supportsVelocityLimits": true,
        "supports3dSecurePassword": false,
        "supportsPanReveal": true,
        "supportsDigitalWalletTokenization": true
      },
      "maxNetworkRiskScore": 700,
      "allowedMccs": [
        "5411"
      ],
      "blockedMccs": [
        "7995"
      ],
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "defaultMccBlocksLifted": false,
      "lockedMerchant": {
        "descriptor": "BLUE BOTTLE COFFEE SF",
        "mcc": "5814",
        "city": "San Francisco",
        "state": "CA",
        "country": "US"
      },
      "currency": "USD",
      "processorRef": "card_b81c2a4f",
      "issuerRef": "lead_card_7a1b9c3d"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "totalCount": 123
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Query Parameters

customerId · string

Filter by customer id.

actingFor · string

Filter to agent cards issued for this person: cards whose actingFor is the given value.

accountId · string

Filter by internal account id. Returns cards whose fundingSource is the given internal account id.

platformCardId · string

Filter by platform-specific card identifier.

status · enum<string>

Filter by card status. Lifecycle status of a card.

Status	Description
PENDING_KYC	The cardholder has not yet completed KYC. Cards in this status cannot transact.
PROCESSING	The card has been requested and is being provisioned with the issuer.
PENDING_AUTH	The issuer has provisioned the card, but its USDB Embedded Wallet funding source lacks an active delegated signing key. Complete POST /auth/delegated-keys before using the card.
ACTIVE	The card is live and can authorize transactions.
FROZEN	The card is temporarily disabled by the platform or by Grid. New authorizations are declined with cardDeclinedReason: CARD_NOT_ACTIVE. Existing settlements and refunds continue to reconcile. A card Grid froze for review, or one frozen as COMPROMISED, cannot be unfrozen by the platform.
CLOSED	The card is permanently closed. Terminal, irreversible status.

Available options: PENDING_KYC, PROCESSING, PENDING_AUTH, ACTIVE, FROZEN, CLOSED

limit · integer · default: 20

Maximum number of results to return (default 20, max 100)

Required range: 1 <= x <= 100

cursor · string

Cursor for pagination (returned from previous request)

sortOrder · enum<string> · default: desc

Order to sort results in

Available options: asc, desc

Response

200

application/json

Successful operation

data · object[] · required

List of cards matching the filter criteria

Show child attributes

hasMore · boolean · required

Indicates if more results are available beyond this page

nextCursor · string

Cursor to retrieve the next page of results (only present if hasMore is true)

totalCount · integer

Total number of cards matching the criteria (excluding pagination)