Approve an agent action
Approve a pending agent action, allowing Grid to proceed with execution. The action must have status PENDING_APPROVAL. Once approved, Grid executes the underlying operation (quote execution or transfer) and the action transitions to APPROVED.
For an EXECUTE_QUOTE action without priceTolerance, note that the underlying quote may have expired between submission and approval — in that case the action will transition to FAILED instead.
An EXECUTE_QUOTE action with priceTolerance whose quote is still live executes that quote, as shown. Once its quote has expired, approval quotes the send again and runs every check against the new quote and its amount. When the new price is no worse for the customer than priceTolerance allows, Grid executes the new quote and the action transitions to APPROVED with it as quote. When it is worse by more, nothing is sent: the response is 200 with status still PENDING_APPROVAL, the new quote, and previousQuote set to the quote the customer was shown, so they can be asked again; approving again repeats the check against the new quote. A send Grid can no longer quote fails with the matching failureReason, and one past its expiresAt with APPROVAL_EXPIRED.
For ISSUE_PURCHASE_CARD actions, approval issues the purchase card and the action carries its cardId. When purchaseCard.increaseCardId is set, approval instead raises that existing card to the new amount and limit. The card’s limit is checked against the agent’s policy again first; an action past its expiresAt fails with APPROVAL_EXPIRED, one the policy now denies with POLICY_DENIED, a paused or deleted agent with AGENT_INACTIVE, and one the card issuer refuses with EXECUTION_FAILED.
For USE_STORED_CARD actions, approval lets the agent collect one single-use link to the card’s details. A use with storedCardUse.needsCvc needs storedCardCvc, the security code encrypted by Evervault’s Card component; without it the request is refused with 400. autoApproveMerchant also lets the agent use the card at the same merchant again, up to the same amount, without asking. Grid cannot verify the customer here: confirm the decision with them (for example with a passkey or an emailed code) before calling. An action past its expiresAt fails with APPROVAL_EXPIRED, and one whose card was removed, or whose agent lost access or is paused or deleted, with AGENT_INACTIVE.
This endpoint is called by the platform’s backend using platform credentials, not by the agent itself.
Authorizations
API token authentication using format <api token id>:<api client secret>
Path Parameters
System-generated unique agent identifier
Unique identifier of the agent action to approve
Body
Optional details for approving a USE_STORED_CARD action. Refused with 400 on any other action type.
The card's security code, encrypted by Evervault's Card component, when the use has storedCardUse.needsCvc. Required for such a use. Grid holds it only until the agent opens its link, or the link expires, and never stores it with the card.
2048^ev:"ev:Tk9D:cvc:...$"
Also let this agent use this card at this merchant again, up to this use's amount, without asking. A later use that needs the security code still asks.
false
Response
Action approved, or, for an action whose new quote moved past priceTolerance, still PENDING_APPROVAL with previousQuote set. 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.
System-generated unique identifier for this action.
"AgentAction:019542f5-b3e7-1d02-0000-000000000099"
The agent that submitted this action.
"Agent:019542f5-b3e7-1d02-0000-000000000042"
The customer on whose behalf the action was submitted.
"Customer:019542f5-b3e7-1d02-0000-000000000010"
Platform-specific ID of the customer.
"user-a1b2c3"
Status of an agent action.
PENDING_APPROVAL, APPROVED, REJECTED, FAILED The type of action the agent is requesting.
EXECUTE_QUOTE, ISSUE_PURCHASE_CARD, CLAIMABLE_PAYOUT, USE_STORED_CARD, CREATE_SETTLEMENT_RULE, UPDATE_SETTLEMENT_RULE, PAYOUT_RUN 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, USE_STORED_CARD, CREATE_SETTLEMENT_RULE, UPDATE_SETTLEMENT_RULE and PAYOUT_RUN, this is the end of the approval window, after which a pending action fails with APPROVAL_EXPIRED; a settlement rule's window is seven days, and a payout run's 24 hours.
"2025-10-03T15:05:00Z"
When the action was submitted by the agent.
"2025-10-03T15:00:00Z"
When the action was last updated.
"2025-10-03T15:02:00Z"
The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. Present for EXECUTE_QUOTE.
The quote the customer was shown before an approval found that the price had moved past priceTolerance. Present only while the action is PENDING_APPROVAL after such an approval; quote is then the new quote to show the customer, and approving it again repeats the check against it.
Present on a PENDING_APPROVAL EXECUTE_QUOTE action that Grid quotes again when it is approved after its quote expired: how far the price may move against the customer before they are asked again. Fixed when the action is created. Absent when approval can only execute quote as it is.
The purchase card the agent asked for, so an approval decision can show its amount, limit, description and funding account. Present for ISSUE_PURCHASE_CARD.
The claimable payout the agent asked to send, so an approval decision can show its amount and recipient. Present for CLAIMABLE_PAYOUT. Approving the action makes the payout AWAITING_CLAIM; rejecting it, or letting it expire, ends the payout and releases its hold.
The stored card the agent asked to use, where, and for how much, so an approval decision can show them. Present for USE_STORED_CARD. Approving the action lets the agent collect a single-use link with POST /agents/me/stored-cards/{storedCardId}/reveal and actionId.
The settlement rule the agent proposed, so an approval decision can show what it matches, who it pays and its limits. Present for CREATE_SETTLEMENT_RULE and UPDATE_SETTLEMENT_RULE. For CREATE_SETTLEMENT_RULE, approving the action makes the rule ACTIVE; rejecting it, or letting it expire, deletes it. For UPDATE_SETTLEMENT_RULE, it is the rule as the change would make it, with the rule's id; approving the action applies the change, and rejecting it, or letting it expire, drops it while the rule keeps its terms. Approving a rule does not approve its payments in advance. Each share is still checked against the agent's policy when it is sent.
The payout run the agent created, so an approval decision can show every row. Present for PAYOUT_RUN. Approving the action starts the run; rejecting it, or letting it expire, cancels the run and skips every row. The approval covers each row's own approval, so no row waits for another.
The purchase card the action issued, or for an increase the card whose amount it raised. Present for an ISSUE_PURCHASE_CARD action once it is APPROVED and the card is issued or increased; read it with GET /agents/me/cards/{cardId}.
"Card:019542f5-b3e7-1d02-0000-000000000011"
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
Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.
"Transaction amount exceeds customer's current risk limit."
Machine-readable reason the action failed. Only present when status is FAILED; rejectionReason is used only for REJECTED actions.
QUOTE_EXPIRED, POLICY_DENIED, AGENT_INACTIVE, EXECUTION_FAILED, PRICE_MOVED, ADDRESS_REFUSED, APPROVAL_EXPIRED, DELETED_BY_AGENT, AGENT_CANCELLED