Skip to main content
POST
/
v1
/
cards
/
{cardId}
/
intents
Create intent
curl --request POST \
  --url https://api.useproxy.ai/v1/cards/{cardId}/intents \
  --header 'Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intentId": "<string>",
  "summary": "<string>",
  "expectedAmount": 123,
  "expectedCurrency": "USD",
  "expectedMerchant": "<string>",
  "tolerance": 123,
  "ttlMinutes": 30,
  "metadata": {}
}
'
{
  "id": "<string>",
  "cardId": "<string>",
  "intentId": "<string>",
  "summary": "<string>",
  "status": "pending",
  "expiresAt": 123,
  "createdAt": 123,
  "expectedAmount": 123,
  "expectedCurrency": "<string>",
  "expectedMerchant": "<string>",
  "tolerance": 123,
  "approvalRequired": true,
  "approvedAt": 123,
  "approvedBy": "<string>",
  "rejectedAt": 123,
  "rejectedBy": "<string>",
  "rejectionReason": "<string>",
  "transactionId": "<string>",
  "matchResult": {
    "amountMatch": true,
    "merchantMatch": true,
    "actualAmount": 123,
    "actualMerchant": "<string>"
  },
  "matchedAt": 123
}

Authorizations

​
Api-Key
string
header
required

API key for authentication. Get your key from the Dashboard.

Path Parameters

​
cardId
string
required

The card ID

Body

application/json
​
intentId
string
required

Customer-provided UUID for idempotency. If an intent with this ID already exists, the existing intent is returned.

​
summary
string
required

Human-readable description of the intended purchase (e.g., 'Order dinner on DoorDash')

​
expectedAmount
integer

Expected transaction amount in cents

​
expectedCurrency
string
default:USD

Expected currency code

​
expectedMerchant
string

Expected merchant name for matching

​
tolerance
integer

Allowed variance from expectedAmount in cents (e.g., 500 = ±$5)

​
ttlMinutes
integer
default:30

Time-to-live in minutes before intent expires (default 30, max 1440 = 24 hours)

Required range: 1 <= x <= 1440
​
metadata
object

Additional context (taskId, orderId, cart items, etc.)

Response

Intent created

​
id
string
required

Internal intent ID

​
cardId
string
required
​
intentId
string
required

Customer-provided intent ID

​
summary
string
required
​
status
enum<string>
required

pending=approved and awaiting transaction, pending_approval=awaiting human approval, rejected=rejected by human, matched=transaction matched within tolerance, mismatched=transaction outside tolerance, expired=TTL reached, canceled=manually canceled

Available options:
pending,
pending_approval,
rejected,
matched,
mismatched,
expired,
canceled
​
expiresAt
integer
required

Unix timestamp when intent expires

​
createdAt
integer
required
​
expectedAmount
integer
​
expectedCurrency
string
​
expectedMerchant
string
​
tolerance
integer
​
approvalRequired
boolean

Whether this intent required human approval

​
approvedAt
integer

Unix timestamp when intent was approved

​
approvedBy
string

API key prefix of approver

​
rejectedAt
integer

Unix timestamp when intent was rejected

​
rejectedBy
string

API key prefix of rejector

​
rejectionReason
string

Reason provided for rejection

​
transactionId
string

ID of matched transaction (if status is matched or mismatched)

​
matchResult
object

Match details (populated after transaction)

​
matchedAt
integer

Unix timestamp when transaction was matched