Issue an agent card

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({fundingSource: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"fundingSource\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/cards")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "card": {
    "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",
    "maxSpendPerTransaction": 5000,
    "maxSpendPerDay": 25000,
    "maxTransactionsPerDay": 20,
    "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": {
      "supportsSpendLimits": true,
      "supportsSpendLimitsAtIssuance": true,
      "supportsTransactionCountLimit": true,
      "supports3dSecurePassword": false,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "defaultMccBlocksLifted": false,
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d"
  },
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentCardKind": "STANDARD",
  "effectiveBlockedMccs": [
    "7995",
    "6051"
  ]
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Agent Operations

Issue an agent card

Issue a virtual card for the authenticated agent, as POST /cards with agentId does for the platform. The card belongs to the agent’s customer, who must have KYC status APPROVED and have accepted the cardholder agreement where the platform requires one. Its spend is the customer’s own and does not count against the agent’s policy, and Grid’s default agent merchant-category blocks apply. Requires the ISSUE_CARDS permission; reading the card afterwards needs MANAGE_CARDS. While any of the agent’s cards is not CLOSED, including one the platform issued for it, the request is rejected with AGENT_CARD_EXISTS.

Card issuance is fee-bearing and cannot be reversed, so an Idempotency-Key header is required. Keys are scoped to the agent: a retry by the same agent with the same key returns the card the first request created, even though that card is now live, and another agent’s key never matches.

New cards start in status: "PROCESSING" and follow the same status transitions and card.status_change webhooks as cards issued with POST /cards.

POST

agents

cards

Issue an agent card

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({fundingSource: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"fundingSource\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/cards")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "card": {
    "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",
    "maxSpendPerTransaction": 5000,
    "maxSpendPerDay": 25000,
    "maxTransactionsPerDay": 20,
    "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": {
      "supportsSpendLimits": true,
      "supportsSpendLimitsAtIssuance": true,
      "supportsTransactionCountLimit": true,
      "supports3dSecurePassword": false,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "defaultMccBlocksLifted": false,
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d"
  },
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentCardKind": "STANDARD",
  "effectiveBlockedMccs": [
    "7995",
    "6051"
  ]
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNRECOGNIZED_MANDATORY_PAYEE_DATA_KEY",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Headers

Idempotency-Key

string

required

A unique identifier for the request, up to 255 characters, scoped to the agent. A retry carrying the same key returns the card created by the first request; reusing a key for a different card request is rejected with 409.

Maximum string length: 255

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

fundingSource

string

required

Internal account id that funds the card. The account must belong to the agent's customer and be denominated in a card-eligible currency; otherwise the request is rejected with INVALID_INPUT.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

Response

Card created. It starts in PROCESSING while the issuer provisions it.

A card that belongs to the authenticated agent: the card itself and how the agent may use it.

card

object

required

Show child attributes

agentId

string

required

The agent the card belongs to.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

agentCardKind

enum<string>

required

How an agent card is used and funded.

Kind	Description
`STANDARD`	A 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 is the customer's own; the agent can read it, tighten its limits, and freeze it.

Available options:

STANDARD

effectiveBlockedMccs

string[]

required

Every merchant category code the card declines: blockedMccs plus the categories Grid blocks for agent cards, unless the platform lifted those defaults (defaultMccBlocksLifted).

Pattern: ^[0-9]{4}$

Example:

["7995", "6051"]

Using the API

API documentation

Issue an agent card

Authorizations

Headers

Body

Response