Skip to main content
POST
/
cards
/
{cardId}
/
intents
Create an intent
curl --request POST \
  --url https://api.useproxy.ai/v1/cards/{cardId}/intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purpose": "<string>",
  "intentId": "<string>",
  "expectedAmount": 123,
  "expectedCurrency": "<string>",
  "expectedMerchant": "<string>",
  "expectedMccs": [
    "<string>"
  ],
  "tolerance": 123,
  "tolerancePercent": 123,
  "ttlMinutes": 123,
  "metadata": {}
}
'
{
  "id": "<string>",
  "cardId": "<string>",
  "purpose": "<string>",
  "status": "pending_approval",
  "intentId": "<string>",
  "expectedAmount": 123,
  "expectedCurrency": "<string>",
  "expectedMerchant": "<string>",
  "expectedMccs": [
    "<string>"
  ],
  "toleranceAmount": 123,
  "tolerancePercent": 123,
  "expiresAt": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "approvedAt": "2023-11-07T05:31:56Z",
  "rejectedAt": "2023-11-07T05:31:56Z",
  "rejectionReason": "<string>",
  "canceledAt": "2023-11-07T05:31:56Z",
  "matchedAt": "2023-11-07T05:31:56Z",
  "mismatchedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

API key authentication. Include your API key in the Authorization header as Bearer <api_key>.

Headers

​
Idempotency-Key
string

Unique key for idempotent requests (24-hour cache)

Path Parameters

​
cardId
string
required

Card ID (e.g., card_...)

Body

application/json
​
purpose
string
required

Description of intended spend

​
intentId
string

Client-provided intent ID for idempotency

​
expectedAmount
number

Expected amount in cents

​
expectedCurrency
string

Expected currency (e.g., usd)

​
expectedMerchant
string

Expected merchant name

​
expectedMccs
string[]

Expected merchant category codes

​
tolerance
number

Allowed amount tolerance in cents

​
tolerancePercent
number

Allowed amount tolerance as percentage

​
ttlMinutes
number

Intent time-to-live in minutes (max 1440)

​
metadata
object

Response

Intent created

​
id
string
required

Unique intent ID

​
cardId
string
required

Associated card ID

​
purpose
string
required

Description of intended spend

​
status
enum<string>
required

Intent status

Available options:
pending_approval,
pending,
matched,
mismatched,
expired,
rejected,
canceled
​
intentId
string | null

Client-provided intent ID for idempotency

​
expectedAmount
number | null

Expected transaction amount in cents

​
expectedCurrency
string | null
​
expectedMerchant
string | null
​
expectedMccs
string[] | null

Expected merchant category codes

​
toleranceAmount
number | null

Allowed amount tolerance in cents

​
tolerancePercent
number | null

Allowed amount tolerance as percentage

​
expiresAt
number | null

Intent expiration timestamp (ms)

​
createdAt
string<date-time> | null
​
updatedAt
string<date-time> | null
​
approvedAt
string<date-time> | null
​
rejectedAt
string<date-time> | null
​
rejectionReason
string | null
​
canceledAt
string<date-time> | null
​
matchedAt
string<date-time> | null
​
mismatchedAt
string<date-time> | null