Reject an agent action

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

Reject an agent action

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/{agentId}/actions/{actionId}/reject \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "reason": "Transaction amount exceeds customer's current risk limit."
}
EOF

200

{
  "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "status": "PENDING_APPROVAL",
  "type": "EXECUTE_QUOTE",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z",
  "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,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "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"
        }
      }
    ],
    "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
    },
    "purposeOfPayment": "GIFT",
    "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",
      "factor": "SMS_OTP",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAssertionOptions": {},
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    }
  },
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "status": "CREATED",
    "type": "INCOMING",
    "direction": "CREDIT",
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "currency": "EUR",
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
    "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
    "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",
      "status": "COMPLETED",
      "settledAt": "2025-08-15T14:35:00Z",
      "reason": "TRANSACTION_FAILED"
    },
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "currency": "USD",
      "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"
    },
    "failureReason": "LNURLP_FAILED"
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit."
}

Authorizations

Authorization · string · header · required

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

Path Parameters

agentId · string · required

System-generated unique agent identifier

actionId · string · required

Unique identifier of the agent action to reject

Body

application/json

reason · string

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

Example:

"Transaction amount exceeds customer's current risk limit."

Response

200

application/json

Action rejected successfully. Returns the updated AgentAction.

An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type.

id · string · required

System-generated unique identifier for this action.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

agentId · string · required

The agent that submitted this action.

Example:

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

customerId · string · required

The customer on whose behalf the action was submitted.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000010"

platformCustomerId · string · required

Platform-specific ID of the customer.

Example:

"user-a1b2c3"

status · enum<string> · 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	Approved but execution failed (e.g. quote expired, insufficient funds)

Available options: PENDING_APPROVAL, APPROVED, REJECTED, FAILED

type · enum<string> · required

The type of action the agent is requesting.

Type	Description
EXECUTE_QUOTE	Execute a quote

Available options: EXECUTE_QUOTE

createdAt · string<date-time> · required

When the action was submitted by the agent.

Example:

"2025-10-03T15:00:00Z"

updatedAt · string<date-time> · required

When the action was last updated.

Example:

"2025-10-03T15:02:00Z"

quote · object

The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user.

Show child attributes

transaction · Incoming Transaction · object

The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is PENDING_APPROVAL or REJECTED.

Incoming Transaction

Outgoing Transaction

Card Transaction

Show child attributes

rejectionReason · string

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

Example:

"Transaction amount exceeds customer's current risk limit."