Businesses - AgentaOS

Private preview Working end to end for the accounts that use it; details can still change. Tell us at contact@agentaos.ai before you rely on it, and we support you directly. See Product release phases.

agentaos.businesses is for platforms: the businesses you manage, whether a client’s business or another app of your own company. Every method acts on your own account, the platform. Call businesses.* on your platform client. A client made with { business } acts as that business, and a business manages no businesses of its own. To do anything as one of the businesses, see Acting for a business.

`businesses.list()`

const businesses = await agentaos.businesses.list();
for (const b of businesses) console.log(b.name, b.status);

Returns Business[]: every business you manage. Not paginated.

`businesses.retrieve(id)`

const biz = await agentaos.businesses.retrieve('5b1f0c2e-8a4d-4c7b-9e21-3f6a7d8c9b10');

string

required

The business id.

Returns one Business, the same shape as a row of list().

`businesses.create(params)`

const { business, inviteToken, inviteUrl } = await agentaos.businesses.create({
  name: 'ClientCo',
  country: 'DE',
  clientEmail: 'founder@example.com',
  sendInvitationEmail: false,
});

string

required

The name buyers see. A brand, not an email. Up to 100 characters.

string

required

Where the business is registered, ISO 3166-1 alpha-2 in upper case, e.g. 'DE'.

string

Invite your client as the business’s admin. Leave it out to run the business yourself. Only an owner of your platform may invite.

boolean

default:"false"

true for another app of your own company: verified and priced with you, with no share and no identity check of its own.

boolean

default:"true"

false: we send no email. You send inviteUrl to your client yourself (white-label).

The business starts in test mode and goes live after its own verification. Store business.id next to your own record of the client.

Business

The new business.

string | null

The invitation token, or null without clientEmail.

string | null

The link your client opens to accept, or null without clientEmail. Ready to send as it is. The invitation expires after 7 days.

`businesses.resendInvitation(id, params?)`

const { inviteUrl } = await agentaos.businesses.resendInvitation(biz.id, { sendInvitationEmail: false });

Sends the invitation again, to the person last invited. It is a new link: the old one stops working. The new invitation expires after 7 days.

string

required

The business id.

boolean

default:"true"

false: no email, you send the link yourself.

string

The new invitation token.

string

The new link to send.

Once your client has joined, the invitation is theirs to manage: this returns 409 client_joined.

`businesses.revokeInvitation(id)`

await agentaos.businesses.revokeInvitation(biz.id);

string

required

The business id.

Withdraws the open invitation. Its link stops working. Returns nothing. 409 client_joined once your client has joined.

`businesses.createVerificationLink(id)`

const { url, status } = await agentaos.businesses.createVerificationLink(biz.id);
if (url) sendToClient(url);

The identity check link for your client. You send it; only your client can complete it.

string

required

The business id.

string | null

The link to send. null when the client is already verified: nothing to send.

string

Where the identity check stands. These are the check’s own states, not a business status: Not Started, In Progress, Awaiting User, In Review, Approved, Declined, Resubmitted, Expired, Kyc Expired or Abandoned. Approved means the check is done.

Needs a live key (sk_live_...). A test key gets 403 live_key_required. The CLI signed in with agenta login, and the ID check link button in the dashboard, work in test mode too. For another app of your own company it returns 409 identity_from_company: its identity check is your company’s.

Calling it again while a check is open gives back the same check.

Business fields

string

Business UUID. Use it as { business } and in AgentaOS-Account.

string

The name buyers see.

string | null

ISO 3166-1 alpha-2.

Where the business stands. live means verified and with a payout account. changes_needed means we asked the business for a change. See Business status.

string

Your own id: the platform that manages it.

string

ISO 8601.

{ bps: number; fixedMinor: number }

Your share of its new sales: basis points of the price before VAT (1000 = 10%) plus a fixed amount in minor units. Set in the dashboard. See Platform fees.

boolean

true for another app of your own company.

Array<{ currency: string; feesMinor: number; feesDisplay: string }>

Your share of its live sales this month, per currency. feesDisplay is ready to show, e.g. "€12.50".

string | null

Who an open invitation is waiting on, or null.

boolean

The identity check is done: its own, or your company’s for another app of your own company.

{
  "id": "5b1f0c2e-8a4d-4c7b-9e21-3f6a7d8c9b10",
  "name": "ClientCo",
  "country": "DE",
  "status": "in_review",
  "platformOrgId": "0e6d2c1a-3b4f-4a5e-8c7d-9f1a2b3c4d5e",
  "createdAt": "2026-09-28T10:00:00.000Z",
  "platformFee": { "bps": 1000, "fixedMinor": 50 },
  "sameLegalEntity": false,
  "feesThisMonth": [{ "currency": "EUR", "feesMinor": 1250, "feesDisplay": "€12.50" }],
  "invitedEmail": "founder@example.com",
  "identityVerified": false
}

Business status

The dashboard, the status field and the account.updated event name the same states with different words:

Dashboard	`status`	`account.updated` `verification`
Test only	`test_only`	`unverified`
In review	`in_review`	`in_review`
Changes needed	`changes_needed`	`in_review`, with `changes_requested: true` (`changesRequested` in the SDK)
On hold	`on_hold`	`on_hold`
Rejected	`rejected`	`rejected`
Live	`live`	`verified`

A business is live when it is verified and has a payout account saved. Until it has a payout account, a verified business shows Test only (test_only), and verification is already verified.

Acting for a business

Any call on any resource can run as a business you manage. For a whole client, pass business when you create it. Every request it sends acts as that business:

const clientco = new AgentaOS(process.env.AGENTAOS_API_KEY!, { business: biz.id });

await clientco.paymentLinks.list();

For one call, pass { business } as the last argument of any method. It overrides the client’s business:

await agentaos.checkouts.create({ amount: 49, currency: 'EUR' }, { business: biz.id });
await agentaos.accountReview.submit(details, { business: biz.id });
await agentaos.invoices.list({ limit: 20 }, { business: biz.id });

Either way the SDK sends the id in the AgentaOS-Account header. Leave it out to act as yourself. A business you do not manage returns 403 You cannot act as this business., the same answer for an id that does not exist.

Filing a client’s verification with accountReview.submit(…, { business }) is recorded as filed by the platform. Only your client can complete the identity check: send them the link from createVerificationLink.

File a client’s verification

This is the same verification any account submits, sent as the business.

We record it as filed by the platform, and our reviewers see that. File only what your client confirmed to you.

await agentaos.accountReview.submit(
  {
    entityType: 'business',
    legalName: 'ClientCo GmbH',
    registrationNumber: 'HRB 123456',
    taxCountry: 'DE',
    address: { street: 'Hauptstrasse 1', city: 'Berlin', postal: '10115', country: 'DE' },
    productUrl: 'https://clientco.com',
    productDescription: 'Scheduling software for clinics',
    checklist: {
      prohibited_ok: true,
      checklist_ack: true,
      cooldown_ack: true,
      privacy_ok: true,
      tos_ok: true,
    },
  },
  { business: biz.id },
);

See Account review for what we check.

One webhook for every business

You need no webhook per client. Your own endpoint receives every event of every business you manage, signed with your own secret. Each event carries business, the id of the business it happened in.

const event = agentaos.webhooks.verify(
  req.body, // raw body
  req.headers['x-agentaos-signature'] as string,
  process.env.AGENTAOS_WEBHOOK_SECRET!, // your own secret, for every client
);

switch (event.type) {
  case 'checkout.session.completed':
    await fulfil(event.business, event.data.sessionId); // event.business = the client's id
    break;
  case 'account.updated': {
    const client = await agentaos.businesses.retrieve(event.business);
    await saveVerification(client.id, client.status, client.identityVerified);
    break;
  }
}

account.updated fires when the client’s verification changes. Set your endpoint in Settings → Developers → Webhooks. See Platform webhooks.

Next steps

Build a platform

End to end.

Businesses (CLI)

The same from the terminal.

Platform webhooks

business on every event, and account.updated.

API reference

The raw HTTP endpoints.

​businesses.list()

​businesses.retrieve(id)

​businesses.create(params)

​businesses.resendInvitation(id, params?)

​businesses.revokeInvitation(id)

​businesses.createVerificationLink(id)

​Business fields

​Business status

​Acting for a business

​File a client’s verification

​One webhook for every business

​Next steps

Build a platform

Businesses (CLI)

Platform webhooks

API reference

`businesses.list()`

`businesses.retrieve(id)`

`businesses.create(params)`

`businesses.resendInvitation(id, params?)`

`businesses.revokeInvitation(id)`

`businesses.createVerificationLink(id)`

Business fields

Business status

Acting for a business

File a client’s verification

One webhook for every business

Next steps