> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Business Account

> Create a business account in Kotlin, then list, read, and rename it.

> [!NOTE]
>
> Business Accounts are in **early access**. See [Business Accounts](https://docs.dynamic.xyz/docs/business-accounts/accounts.md) for the model.

Create a business account as an authenticated user. You become the **owner**, and can then add [wallets](https://docs.dynamic.xyz/docs/kotlin/business-accounts/add-wallets.md), [signers](https://docs.dynamic.xyz/docs/kotlin/business-accounts/manage-signers.md), and [members](https://docs.dynamic.xyz/docs/kotlin/business-accounts/members-and-roles.md). Every business account operation lives on `DynamicSDK.getInstance().businessAccounts`.

## Prerequisites

* `DynamicSDK` initialized with your environment ID (see the [quickstart](https://docs.dynamic.xyz/docs/kotlin/quickstart.md))
* An authenticated user, because account operations act on behalf of the signed-in user
* Business Accounts enabled for your environment

## Create an account

`create` takes an optional `name`, `externalRef`, and `metadata`, and returns the new account.

```kotlin theme={"system"}
import com.dynamic.sdk.android.DynamicSDK
import kotlinx.serialization.json.JsonPrimitive

val sdk = DynamicSDK.getInstance()

val account = sdk.businessAccounts.create(
    name = "Acme Treasury",
    externalRef = "org_acme_123",
    metadata = mapOf("tier" to JsonPrimitive("enterprise"))
)

println(account.id) // use this to add wallets, signers, and members
```

**name** `String?`

Display name for the account.

**externalRef** `String?`

A developer-supplied label for mapping your own org or tenant ID onto this account. Not unique, so multiple accounts may share a value.

**metadata** `Map\<String, JsonElement\>?`

Arbitrary key-value metadata stored alongside the account.

The returned `BusinessAccount` has `id`, `name`, `externalRef`, `metadata`, `projectEnvironmentId`, `createdAt`, and `updatedAt`.

## List accounts

`list` returns the accounts the current user is a member of, for the active environment. Pass `externalRefs` to filter by your own org or tenant IDs.

```kotlin theme={"system"}
val list = sdk.businessAccounts.list()

list.items?.forEach { account ->
    println(account.name ?: account.id)
}

// Filter by your own references
val filtered = sdk.businessAccounts.list(externalRefs = listOf("org_acme_123"))
```

`BusinessAccountList` returns `items` plus a `nextCursor` for paging.

## Read one account

`get` returns the account plus its `members`, `signers`, and `wallets`.

```kotlin theme={"system"}
val detail = sdk.businessAccounts.get(businessAccountId = account.id)

println(detail.members.size)
println(detail.signers.size)
println(detail.wallets?.size ?: 0)
```

Each entry in `detail.wallets` is a `BusinessAccountWalletSummary` with `id`, `chain`, and `publicKey`. Use the `id` when you [add or remove wallets](https://docs.dynamic.xyz/docs/kotlin/business-accounts/add-wallets.md) and when you [manage signers](https://docs.dynamic.xyz/docs/kotlin/business-accounts/manage-signers.md).

> [!TIP]
>
> Only members of an account can read it. A request from a non-member returns 404 rather than 403, so account existence is not leaked across tenants.

## Rename an account

`update` changes the account name.

```kotlin theme={"system"}
val renamed = sdk.businessAccounts.update(
    businessAccountId = account.id,
    name = "Acme Operating Funds"
)
```

## On error

Every method is a `suspend` function that throws on failure. Wrap calls in `try/catch` and show the failure to the user:

```kotlin theme={"system"}
try {
    val account = sdk.businessAccounts.create(name = "Acme Treasury")
    println(account.id)
} catch (e: Exception) {
    println("Failed to create business account: ${e.message}")
}
```

## Next steps

> [card] [Add wallets](https://docs.dynamic.xyz/docs/kotlin/business-accounts/add-wallets.md)
>
> Link an embedded wallet to the account.

> [card] [Members and roles](https://docs.dynamic.xyz/docs/kotlin/business-accounts/members-and-roles.md)
>
> Add admins and viewers, and transfer ownership.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.