> For the complete documentation index, see [llms.txt](https://docs.txn.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.txn.io/accounts/creating-subaccount.md).

# Creating subaccount

<mark style="color:green;">`POST`</mark> `/api/public/v1/accounts/:account_id/subaccounts`

Creates a subaccount under a master account to hold a separate balance in the same currency, for example per client or business unit. The subaccount inherits the master account's currency and gets its own ID and `bankReference`; a crypto subaccount can also get its own receiving addresses. Fund it with [Creating account transfer](https://docs.txn.io/accounts/creating-account-transfer.md), or by sending deposits to its addresses.

**Headers**

| Name          | Value                      |
| ------------- | -------------------------- |
| Content-Type  | `application/vnd.api+json` |
| Authorization | `Bearer <api_key>`         |

**Path Parameters**

| Name        | Type   | Description        |
| ----------- | ------ | ------------------ |
| account\_id | string | Master account ID. |

**Body**

<table><thead><tr><th>Name</th><th width="116">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Request data object.</td></tr><tr><td>data.type</td><td>string</td><td>Resource type. Always <code>accounts</code>.</td></tr><tr><td>data.attributes</td><td>object</td><td>Subaccount attributes.</td></tr><tr><td>data.attributes.label</td><td>string</td><td>Subaccount label. Use a human-readable value so you can recognize it later. Must be unique among your accounts in the same currency; the comparison is case-insensitive.</td></tr></tbody></table>

**Request JSON**

```json
{
  "data": {
    "type": "accounts",
    "attributes": {
      "label": "Sub-account Olivia Bennett"
    }
  }
}
```

**cURL**

```bash
curl -X "POST" "https://api.sandbox.txn.io/api/public/v1/accounts/e289de2b-37bd-4eff-b832-f754c31a2d95/subaccounts" \
     -H 'Content-Type: application/vnd.api+json' \
     -H 'Authorization: Bearer <api_key>' \
     -d $'{
  "data": {
    "type": "accounts",
    "attributes": {
      "label": "Sub-account Olivia Bennett"
    }
  }
}'
```

**Response**

{% tabs %}
{% tab title="HTTP 200" %}

```json
{
  "data": {
    "id": "065ae325-9581-4f01-b7ff-b4c8ec6f397d",
    "type": "accounts",
    "attributes": {
      "master": false,
      "currencyCode": "USDT",
      "label": "Sub-account Olivia Bennett",
      "bankReference": "BDR3286386347484475",
      "balance": "0.000000",
      "totalBalance": null,
      "bankWithdrawalAvailable": false,
      "bankDepositAvailable": false,
      "transferAvailable": true,
      "currencyType": "crypto"
    },
    "relationships": {
      "company": {
        "meta": {
          "included": false
        }
      },
      "networks": {
        "meta": {
          "included": false
        }
      },
      "txnBankCredentials": {
        "meta": {
          "included": false
        }
      }
    }
  },
  "meta": {},
  "jsonapi": {
    "version": "1.0"
  }
}
```

{% endtab %}

{% tab title="HTTP 422" %}

```json
{
  "errors": [
    {
      "status": 422,
      "title": "Invalid attribute",
      "code": "account_invalid",
      "detail": "Label has already been taken",
      "source": {
        "pointer": "/data/attributes/label"
      }
    }
  ]
}
```

An account with the same label already exists in this currency.
{% endtab %}

{% tab title="HTTP 404" %}

```json
{
  "errors": [
    {
      "status": 404,
      "title": "Record not found",
      "code": "account_not_found",
      "detail": "Account not found"
    }
  ]
}
```

The master account in the path does not exist.
{% endtab %}
{% endtabs %}

**Response Body**

| Name                                      | Type    | Description                                                                                                                                                                            |
| ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.id`                                 | string  | Subaccount ID.                                                                                                                                                                         |
| `data.type`                               | string  | Entity type returned. Always `accounts`.                                                                                                                                               |
| `data.attributes.master`                  | boolean | Always `false` for a subaccount.                                                                                                                                                       |
| `data.attributes.currencyCode`            | string  | Currency code, inherited from the master account.                                                                                                                                      |
| `data.attributes.label`                   | string  | Subaccount label, as set in the request.                                                                                                                                               |
| `data.attributes.bankReference`           | string  | Unique bank deposit reference assigned to the subaccount.                                                                                                                              |
| `data.attributes.balance`                 | string  | Subaccount balance. A new subaccount starts at zero.                                                                                                                                   |
| `data.attributes.totalBalance`            | string  | Matches `balance` for subaccounts.                                                                                                                                                     |
| `data.attributes.bankWithdrawalAvailable` | boolean | If `true`, bank withdrawals can be initiated from this account.                                                                                                                        |
| `data.attributes.bankDepositAvailable`    | boolean | If `true`, bank deposits can be made to this account.                                                                                                                                  |
| `data.attributes.transferAvailable`       | boolean | If `true`, transfers between this account and your other accounts are allowed.                                                                                                         |
| `data.attributes.currencyType`            | string  | Currency type. Either `fiat` or `crypto`.                                                                                                                                              |
| `data.relationships.company`              | object  | Not expanded (`meta.included` is `false`).                                                                                                                                             |
| `data.relationships.networks`             | object  | Not expanded on this endpoint (`meta.included` is `false`). [Read the account](https://docs.txn.io/accounts/reading-account.md) to get the networks it can receive deposits on.        |
| `data.relationships.txnBankCredentials`   | object  | Not expanded on this endpoint (`meta.included` is `false`). [Read the account](https://docs.txn.io/accounts/reading-account.md) to get the bank details for funding a fiat subaccount. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.txn.io/accounts/creating-subaccount.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
