Skip to main content

​
Users

Users are KYC-verified individuals or entities who fund card spending. Each user goes through identity verification, deposits funds, and their agents can then issue cards against their balance.
KYC is Required — Users cannot deposit funds or use cards until KYC is approved. Plan for this in your integration timeline.

​
Who Should Be a User?

Your Use CaseWho is the User?
AI agents spending your company’s moneyYour company (1 User)
Platform where customers fund their own AIEach customer (1 User per customer)
B2B service managing client fundsEach client company (1 User per client)
Important: A “User” is not the developer integrating the API. It’s the entity whose money funds the cards.

​
KYC Requirements

RequirementDetails
Information neededFull legal name, date of birth, address, SSN (US) or equivalent
DocumentsGovernment-issued ID, proof of address (if requested)
Processing timeUsually 1-5 minutes for automated approval
Manual reviewUp to 1-2 business days if flagged
Use webhooks (user.application.approved, user.application.denied) to get notified when KYC status changes rather than polling.

​
Lifecycle

1

Create

Create a user with basic info via the API
2

Verify

Initiate KYC verification and user completes it
3

Deposit

User deposits funds via crypto
4

Active

Agents can issue cards against the user’s balance

​
Create a User

curl -X POST https://api.useproxy.ai/v1/users \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  }'

{
  "object": "user",
  "id": "user_abc123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "applicationStatus": "notStarted",
  "isActive": true,
  "createdAt": 1703520000000
}

​
Initiate KYC Verification

After creating a user, initiate the KYC process: 
curl -X POST https://api.useproxy.ai/v1/verification/user \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123"
  }'

{
  "object": "verification",
  "userId": "user_abc123",
  "applicationStatus": "pending",
  "verificationUrl": "https://kyc.useproxy.ai/verify/xyz789"
}
The user completes KYC via the verificationUrl. You’ll receive a webhook when their status changes.

​
Check Verification Status

curl https://api.useproxy.ai/v1/verification/user/user_abc123 \
  -H "Api-Key: $API_KEY"

{
  "object": "verification",
  "userId": "user_abc123",
  "applicationStatus": "approved",
  "approvedAt": 1703523600000
}

​
Application Status

StatusDescription
notStartedKYC not yet initiated
pendingAwaiting KYC completion
needsInformationAdditional info required
manualReviewUnder manual review
approvedReady to deposit and use cards
deniedVerification failed

​
Check Balance

curl https://api.useproxy.ai/v1/balances/user_abc123 \
  -H "Api-Key: $API_KEY"

{
  "userId": "user_abc123",
  "available": 10000,
  "pending": 0,
  "deposited": 10000,
  "currency": "USD"
}
FieldDescription
availableWhat can be spent right now (cents)
pendingAuthorizations not yet settled (cents)
depositedTotal funds deposited (cents)
currencyCurrency code (always “USD”)

​
Get Funding Methods

Users deposit funds via crypto. Get their available funding methods: 
curl https://api.useproxy.ai/v1/users/user_abc123/funding \
  -H "Api-Key: $API_KEY"

{
  "object": "funding",
  "userId": "user_abc123",
  "methods": [{
    "type": "crypto",
    "network": "base",
    "chainId": 8453,
    "address": "0x36561987b391685A09A26068eFBa31D6dFbfC530"
  }]
}
FieldDescription
typeFunding method type (crypto, bank_transfer in future)
networkNetwork name (e.g., base, ethereum)
chainIdChain ID (e.g., 8453 for Base)
addressAddress to send deposits to

​
User CRUD Operations

​
Get User

curl https://api.useproxy.ai/v1/users/user_abc123 \
  -H "Api-Key: $API_KEY"

​
Update User

curl -X PATCH https://api.useproxy.ai/v1/users/user_abc123 \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jonathan"
  }'

​
Delete User

curl -X DELETE https://api.useproxy.ai/v1/users/user_abc123 \
  -H "Api-Key: $API_KEY"
Deleting a user is permanent. All associated agents and cards will be closed.

​
List User’s Cards

curl https://api.useproxy.ai/v1/users/user_abc123/cards \
  -H "Api-Key: $API_KEY"

​
Webhooks

EventDescription
user.createdUser created
user.updatedUser info updated
user.deletedUser deleted
user.application.approvedKYC passed
user.application.deniedKYC failed
user.application.needs_infoAdditional info needed
user.balance.updatedBalance changed
deposit.receivedFunds received
deposit.address_readyDeposit address available

Deposits & Withdrawals

Learn how to deposit and withdraw funds