> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useproxy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intents

> Pre-transaction declarations of planned purchases

# 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

```bash theme={"system"}
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

| Field              | Type   | Description                         |
| ------------------ | ------ | ----------------------------------- |
| `purpose`          | string | Human-readable description          |
| `expectedAmount`   | number | Expected transaction amount (cents) |
| `expectedMerchant` | string | Expected merchant name              |

## Intent Lifecycle

| Status             | Description                           |
| ------------------ | ------------------------------------- |
| `pending_approval` | Awaiting human approval               |
| `pending`          | Approved, awaiting transaction        |
| `matched`          | Transaction matched the intent        |
| `mismatched`       | Transaction didn't match expectations |
| `expired`          | Intent 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:

```bash theme={"system"}
# 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

<CardGroup cols={2}>
  <Card title="Cards" icon="credit-card" href="/concepts/cards">
    Learn about card controls
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Get notified about intent status
  </Card>
</CardGroup>