---
title: "Create a business"
method: POST
path: "/gateway/businesses"
tags: ["Businesses"]
---

# Create a business

`POST /gateway/businesses`

## Request

- Base URL: `https://api.agentaos.ai/api/v1`
- URL: `https://api.agentaos.ai/api/v1/gateway/businesses`
- Auth: API key in header `x-api-key`

Add a business you manage. It starts in test mode and goes live after its own verification. With `clientEmail`, your client is invited as its admin, and the invitation expires after 7 days. We email the invitation, or with `sendInvitationEmail: false` we send nothing and you send `inviteUrl` yourself (white-label).

## Request body

- BusinessCreateRequest
  - `name` string, required: The name buyers see. A brand, not an email.
  - `country` string, required: Where it is registered, ISO 3166-1 alpha-2, upper case.
  - `clientEmail` string, email: Invite your client as its admin. Leave it out to run the business yourself. Only an owner of your platform may invite.
  - `sameLegalEntity` boolean: `true` for another app of your own company.
  - `sendInvitationEmail` boolean: `false`: we send no email; you send `inviteUrl` yourself (white-label).

## Response `201`

The business was created.

- CreatedBusiness
  - `business` Business, required: A business you manage: a client's business, or another app of your own company. Every field is camelCase on the wire.
    - `id` string, uuid, required: Business UUID. Send it in `AgentaOS-Account` to act as the business.
    - `name` string, required: The name buyers see.
    - `country` string, nullable, required: ISO 3166-1 alpha-2.
    - `status` 'test_only' | 'in_review' | 'changes_needed' | 'on_hold' | 'rejected' | 'live', required: Where the business stands. `live` = verified. A bank account is needed before the first payout, not for this status. `changes_needed` = we asked the business for a change.
    - `platformOrgId` string, uuid, required: Your own id: the platform that manages it.
    - `createdAt` string, date-time, required
    - `platformFee` object, required: Your share of its new sales, set in the dashboard: basis points of the price before VAT (`1000` = 10%) plus a fixed amount in minor units.
      - `bps` integer, required
      - `fixedMinor` integer, required
      - `fixedDisplay` string, required: The fixed part as money, in the currency of this month's fees, else euros: `€0.30`.
    - `sameLegalEntity` boolean, required: `true` for another app of your own company: verified and priced with you, no share, no identity check of its own.
    - `feesThisMonth` object[], required: Your share of its live sales this month, per currency. `feesDisplay` is ready to show.
      - `currency` string, required
      - `feesMinor` integer, required
      - `feesDisplay` string, required
    - `invitedEmail` string, nullable, required: Who an open invitation is waiting on, or null.
    - `identityVerified` boolean, required: The identity check is done: its own, or your company's for another app of your own company.
  - `inviteToken` string, nullable, required: The invitation token, or null without `clientEmail`.
  - `inviteUrl` string, nullable, required: The link your client opens to accept, or null without `clientEmail`. Ready to send.

## Other responses

- `400`: A field is missing or invalid, for example a country that is not a two-letter code or a name that is an email. `message` lists every problem; `errors` names the field of each.
- `401`: Missing or invalid `x-api-key`.
- `403`: You are not an owner or admin of the platform, or you sent `clientEmail` as an admin: only an owner of your platform may invite the client.
- `409`: The caller is itself a business managed by a platform. A managed business cannot manage businesses of its own.

---

[API](https://skmtc.dev/agentaos/apis/agentaos-gateway-api.md) · [All operations](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaos/apis/agentaos-gateway-api/revisions/3a8ad3c6b965?raw)