LIlightsparkdev
Agent Operations

List agent cards

Changed on

List the authenticated agent's cards: standard cards issued for it and purchase cards it issued. Filter with kind=PURCHASE for purchase cards only. Other cards of the customer are not listed. Requires the MANAGE_CARDS permission.

get/agents/me/cards

Request

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

Query parameters

kind'STANDARD' | 'PURCHASE'

How an agent card is used and funded.

KindDescription
STANDARDA card issued for the agent, by the platform with POST /cards or by the agent with POST /agents/me/cards. The customer holds the card details and its spend comes from the customer's account; that spend counts against the agent's policy limits as the agent's sends do. The agent can read the card, tighten its merchant categories, and freeze it.
PURCHASEA single-use virtual card the agent issued for one online purchase with POST /agents/me/cards. It is funded from the customer's Embedded Wallet, its spend counts against the agent's policy limits, and it closes after its first approved authorization or when it expires unused. A recurring purchase card (purchase.recurring) is instead locked to the first merchant that charges it, may be charged there again up to its monthly limit, and stays open until it is closed. The agent reads its number, expiry and CVV through POST /agents/me/cards/{cardId}/reveal.

Filter by card kind

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)

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": [
    {
      "card": {
        "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"
      },
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "effectiveBlockedMccs": [
        "7995",
        "6051"
      ],
      "purchase": {
        "amount": 4999,
        "spendLimit": 5749,
        "currency": "USD",
        "description": "Running shoes from example-store.com",
        "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
        "expiresAt": "2026-10-26T15:30:00Z"
      }
    }
  ],
  "nextCursor": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "totalCount": 3
}

Changes

  • e3a3f79a161fRevision changes
    • info

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

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status