Agio Developer

Appearance

On this page

Users ​

Manage Agio cardholders -- create, update, delete users and query their balances.

List Users ​

typescript
const { data: users } = await cards.users.getUsers();

Returns an array of AgioCardUser objects.

Get a User ​

typescript
const { data: user } = await cards.users.getUser("user-id");

console.log(user.firstName); // "Jane"
console.log(user.role); // "cardholder"
console.log(user.status); // "active"

Create a User ​

typescript
const { data: user } = await cards.users.createUser({
  firstName: "Jane",
  lastName: "Smith",
  email: "[email protected]",
  role: "cardholder"
});
FieldTypeRequiredDescription
firstNamestringYesUser's first name
lastNamestringYesUser's last name
emailstringYesUser's email address
rolestringYes"owner", "admin", or "cardholder"
companyIdstringNoAssociate user with a company

Update a User ​

typescript
await cards.users.updateUser("user-id", {
  firstName: "Janet",
  phoneCountryCode: "1",
  phoneNumber: "5555551234",
  walletAddress: "0x..."
});

Updatable fields include firstName, lastName, email, role, isActive, isTermsOfServiceAccepted, address, phoneCountryCode, phoneNumber, and walletAddress.

Delete a User ​

typescript
await cards.users.deleteUser("user-id");

Get User Balance ​

typescript
const { data: balance } = await cards.users.getUserBalance("user-id");

console.log(`Credit limit: $${balance.creditLimit / 100}`);
console.log(`Spending power: $${balance.spendingPower / 100}`);
console.log(`Balance due: $${balance.balanceDue / 100}`);

See the Payment System page for full details on the credit balance model.

Create User in Company (Corporate Flow) ​

After a corporate application is approved, add employees to the company. The initialUser from the application is created automatically -- this endpoint is for additional users.

typescript
const { data: user } = await cards.users.createUserInCompany("company-id", {
  firstName: "Jane",
  lastName: "Smith",
  email: "[email protected]",
  isTermsOfServiceAccepted: true,
  birthDate: "1990-05-15",
  walletAddress: "0x...",
  phoneCountryCode: "1",
  phoneNumber: "5555551234"
});

// Then issue a card for the new user
const { data: card } = await cards.cards.createCard({
  userId: user.id,
  type: "virtual",
  limit: { amount: 50000, frequency: "per30DayPeriod" }
});
FieldTypeRequiredDescription
firstNamestringYesMax 50 characters
lastNamestringYesMax 50 characters
emailstringYesEmployee email
isTermsOfServiceAcceptedbooleanYesMust be true
birthDatestringNoYYYY-MM-DD format
walletAddressstringNoEVM wallet address
addressCardAddressNoPhysical address
phoneCountryCodestringNoe.g. "1" for US
phoneNumberstringNoWithout country code

Charge a User ​

Apply custom fees to a user's account. Charges are per-user, not per-card and reduce the user's spending power.

typescript
await cards.users.chargeUser("user-id", {
  amount: 500, // $5.00 in cents
  description: "Express shipping fee"
});

WARNING

Custom charges are post-authorization and may cause a user's balance to go negative. The Agio charge API does not accept an idempotency key -- implement your own deduplication logic.

User Roles ​

RoleDescription
ownerFull control including admin management
adminCreate cards, manage members, set limits
cardholderUse assigned cards, view own expenses

User Statuses ​

StatusDescription
activeFully functional user
inactiveDisabled user
pendingAwaiting activation or approval