Agent Management13

Agent Operations24

API Tokens4

Cards15

Contact Verification4

Cross-Currency Transfers8

Customers10

Discoveries1

Documents5

Embedded Care2

Embedded Wallet Auth12

Exchange Rates1

External Accounts12

Internal Accounts5

Invitations4

KYC/KYB Verifications9

Periodic Statements2

Platform Configuration2

Same-Currency Transfers2

Sandbox20

Stablecoins12

Strong Customer Authentication16

Transactions6

Webhooks

Webhooks15

Agent Management

Reject an agent action

Changed on Nov 2, 2026

Reject a pending agent action, preventing execution. The action must have status PENDING_APPROVAL. Once rejected, the action transitions to REJECTED and the underlying operation is not executed. This endpoint is called by the platform's backend using platform credentials, not by the agent itself.

post/agents/{agentId}/actions/{actionId}/reject

Request

Base URL
https://api.lightspark.com/grid/2025-10-13
URL
https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/actions/{actionId}/reject
Auth
HTTP basic

Request body

reasonstring

Optional human-readable reason for the rejection, stored on the action and visible to the platform.

Example request

{
  "reason": "Transaction amount exceeds customer's current risk limit."
}

Response

Action rejected successfully. Returns the updated AgentAction.

idstring required

System-generated unique identifier for this action.

agentIdstring required

The agent that submitted this action.

customerIdstring required

The customer on whose behalf the action was submitted.

platformCustomerIdstring required

Platform-specific ID of the customer.

status'PENDING_APPROVAL' | 'APPROVED' | 'REJECTED' | 'FAILED' required

Status of an agent action.

Status	Description
PENDING_APPROVAL	Submitted by the agent, awaiting platform approval before execution
APPROVED	Approved by the platform; execution is in progress or completed
REJECTED	Rejected by the platform; the underlying transaction was not executed
FAILED	Not executed, or execution failed; see failureReason

type'EXECUTE_QUOTE' | 'ISSUE_PURCHASE_CARD' required

The type of action the agent is requesting.

Type	Description
EXECUTE_QUOTE	Execute a quote
ISSUE_PURCHASE_CARD	Issue a purchase card: single-use, or recurring when purchaseCard.recurring is true. See purchaseCard

cardIdstring

The purchase card the action issued. Present for an ISSUE_PURCHASE_CARD action once it is APPROVED and the card is issued; read it with GET /agents/me/cards/{cardId}.

rejectionReasonstring

Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.

Why an agent action has status FAILED.

Reason	Description
QUOTE_EXPIRED	The action's quote expired before execution, or, for an action Grid quotes again on approval, Grid could no longer quote the send
POLICY_DENIED	The agent policy no longer allowed the action
AGENT_INACTIVE	The agent was paused or deleted before execution
EXECUTION_FAILED	Grid could not execute the approved action. For ISSUE_PURCHASE_CARD, the card issuer did not issue the card
PRICE_MOVED	Reserved and legacy. Quotes to a CHAIN_ADDRESS pay out at a locked rate and no longer fail with this reason
ADDRESS_REFUSED	Grid refused the send's destination before it signed the send: the destination is no longer one the agent may send to (for example, a Spark address removed from the customer's saved addresses), or one of the customer's records of the address was refused or is held for review. A CHAIN_ADDRESS that screening refuses fails with EXECUTION_FAILED
APPROVAL_EXPIRED	An ISSUE_PURCHASE_CARD action, or an EXECUTE_QUOTE action with priceTolerance, was not approved before its expiresAt

expiresAtstring date-time required

When the action expires. For an EXECUTE_QUOTE action with priceTolerance, this is the end of the platform's approval window, independent of the quote's own expiry: approval executes a live quote and quotes the send again once it has expired, and a pending action that reaches this time fails with APPROVAL_EXPIRED. For any other EXECUTE_QUOTE action, this is the quote's own expiry; a pending action that reaches it fails with QUOTE_EXPIRED, and approval never creates a replacement quote. For ISSUE_PURCHASE_CARD, this is the end of the approval window, after which a pending action fails with APPROVAL_EXPIRED.

createdAtstring date-time required

When the action was submitted by the agent.

updatedAtstring date-time required

When the action was last updated.

Example response

{
  "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "quote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "feesIncluded": 10,
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "scaChallenge": {
      "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
      "expiresAt": "2025-10-03T12:05:00Z",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "previousQuote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "feesIncluded": 10,
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "scaChallenge": {
      "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
      "expiresAt": "2025-10-03T12:05:00Z",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "priceTolerance": {
    "basisPoints": 100,
    "minimumAmount": 100,
    "currency": "USD"
  },
  "purchaseCard": {
    "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"
  },
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "destination": {
      "destinationType": "ACCOUNT",
      "currency": "EUR",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "railDetails": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "settledAt": "2025-08-15T14:30:00Z",
    "createdAt": "2025-08-15T14:25:18Z",
    "updatedAt": "2025-08-15T14:30:00Z",
    "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "description": "Payment for invoice #1234",
    "sentAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "exchangeRate": 1.08,
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "refund": {
      "reference": "UMA-Q12345-REFUND",
      "initiatedAt": "2025-08-15T14:30:00Z",
      "settledAt": "2025-08-15T14:35:00Z",
      "status": "COMPLETED",
      "reason": "TRANSACTION_FAILED"
    },
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "currency": "USD",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "railDetails": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "fees": 10,
    "reconciliationInstructions": {
      "reference": "UMA-Q12345-REF",
      "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
    }
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit.",
  "expiresAt": "2025-10-03T15:05:00Z",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z"
}

Changes

Nov 2, 2026f90f21cf21e8 Revision changes
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
Nov 2, 2026e3a3f79a161f Revision changes
- info
  added the optional property / to the response with the status

Operation history (28 revisions)