LIlightsparkdev
Cards

List cards

Changed on

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

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/cards
  • Auth
    HTTP basic

Query parameters

customerIdstring

Filter by customer id.

accountIdstring

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

platformCardIdstring

Filter by platform-specific card identifier.

status'PENDING_KYC' | 'PROCESSING' | 'PENDING_AUTH' | 'ACTIVE' | 'FROZEN' | 'CLOSED'

Lifecycle status of a card.

StatusDescription
PENDING_KYCThe cardholder has not yet completed KYC. Cards in this status cannot transact.
PROCESSINGThe card has been requested and is being provisioned with the issuer.
PENDING_AUTHThe 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.
ACTIVEThe card is live and can authorize transactions.
FROZENThe 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.
CLOSEDThe card is permanently closed. Terminal, irreversible status.

Filter by card status.

limitinteger

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

cursorstring

Cursor for pagination (returned from previous request)

sortOrder'asc' | 'desc'

Order to sort results in

Response

Successful operation

hasMoreboolean required

Indicates if more results are available beyond this page

nextCursorstring

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

totalCountinteger

Total number of cards matching the criteria (excluding pagination)

Example response

{
  "data": [
    {
      "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "platformCardId": "card-emp-001",
      "pinStatus": "OK",
      "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2029,
      "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
      "cardCapabilities": {
        "supportsVelocityLimits": true,
        "supportsPanReveal": true,
        "supportsDigitalWalletTokenization": true
      },
      "maxNetworkRiskScore": 700,
      "allowedMccs": [
        "5411"
      ],
      "blockedMccs": [
        "7995"
      ],
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "currency": "USD",
      "processorRef": "card_b81c2a4f",
      "issuerRef": "lead_card_7a1b9c3d",
      "createdAt": "2026-05-08T14:10:00Z",
      "updatedAt": "2026-05-08T14:11:00Z"
    }
  ]
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5fbda612feb8Revision changes
    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • breaking

      removed the required property // from the response with the status

    • info

      added the required property /// to the response with the status