Skip to main content

​
Intents

An Intent is a pre-transaction declaration of what an agent plans to purchase. Intents enable policy enforcement before card details are accessed.

​
Why Intents?

Intents serve several purposes:
  1. Approval workflows - Require human approval for large purchases
  2. Merchant restrictions - Validate purchases against allowed merchants
  3. Spending controls - Enforce limits before transactions occur
  4. Audit trail - Document the purpose of every transaction

​
Creating an Intent

curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/intents \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Purchase office supplies from Amazon",
    "expectedAmount": 5000,
    "expectedMerchant": "Amazon"
  }'

​
Intent Fields

FieldTypeDescription
purposestringHuman-readable description
expectedAmountnumberExpected transaction amount (cents)
expectedMerchantstringExpected merchant name

​
Intent Lifecycle

StatusDescription
pending_approvalAwaiting human approval
pendingApproved, awaiting transaction
matchedTransaction matched the intent
mismatchedTransaction didn’t match expectations
expiredIntent expired before use

​
Matching Rules

When a transaction occurs, Proxy matches it against pending intents:
  • Amount tolerance: ±10% of expected amount
  • Merchant matching: Fuzzy match on merchant name
  • Time window: Intent must not be expired

​
Approval Workflows

If requireApproval is enabled in the policy, intents start in pending_approval status: 
# Approve an intent
curl -X POST https://api.useproxy.ai/v1/intents/int_xxx/approve \
  -H "Authorization: Bearer your_api_key"

# Reject an intent
curl -X POST https://api.useproxy.ai/v1/intents/int_xxx/reject \
  -H "Authorization: Bearer your_api_key"

​
Next Steps

Cards

Learn about card controls

Webhooks

Get notified about intent status