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

# Create budgets

> Create a new shared or individual sub-budget for a given account.

## Before you start

Make sure you have the following:

* **An API key** and **your account ID**. [Learn more about the API](/pages/get-started/about-the-api).
* **Your parent budget's ID** — retrieve this by [listing all budgets](/pages/budgets/view-budgets) and finding the one with type `accountBalance`.
* **A persona ID** (individual budgets only) — find this by [listing people](/pages/people/list-people) on your account. [Learn more about personas](/pages/people/about-personas-and-roles).

## Things to know

* **Accounts can be configured so that budget names must be unique per account.** If set, and a budget with the same name already exists, you'll receive an error.
* **Only one `accountBalance` budget can exist per account.** This is created during onboarding and cannot be created via the API.
* **Only one individual budget can exist per persona.** Attempting to create a second individual budget for the same persona will return an error.
* **Features must be enabled at account level first.** You can only enable `payments`, `peopleCards`, or `budgetCards` on a budget if they are already enabled on the account. For example, if `payments` is not enabled on the account, you cannot enable it on the budget.
* **At least one currency is required.** You must provide at least one currency when creating a budget.

## Create a shared budget

<Note>
  **POST** `/v2/budgets`
</Note>

### Request

Use this request to create a new shared budget, which can be used by multiple people.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/budgets?accountId=F12345' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
      "name": "Team Party",
      "features": [
        "payments"
      ],
      "currencies": [
        "USD"
      ],
      "type": "shared",
      "status": "active"
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/budgets?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "parentId": "string",
      "name": "string",
      "features": [
        "string"
      ],
      "currencies": [
        "string"
      ],
      "type": "string",
      "status": "string"
    }'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that you're creating a budget for.

  Allowable values: An existing `accountId`
</ParamField>

#### Request body schema

<ParamField body="parentId" type="string" required>
  The ID of the parent budget.

  Allowable values: An existing `budgetId` (≤ 36 characters)
</ParamField>

<ParamField body="name" type="string" required>
  The name of the new budget. Depending on your configuration, this might appear as the payee name.

  Allowable values: ≤ 75 characters
</ParamField>

<ParamField body="features" type="array of strings" required>
  The features that you want to enable for this budget.

  Allowable values: `payments`, `peopleCards`, `budgetCards`
</ParamField>

<ParamField body="currencies" type="array of strings" required>
  The currencies that you want to enable for this budget, in ISO 4217 format. You must provide at least one. If working with a sub-budget, the currencies you provide must be enabled on the parent budget.

  Allowable values: 3 characters
</ParamField>

<ParamField body="type" type="string" required>
  The type that you want this budget to be. Set this to `shared`. [Learn more about budget types](/pages/budgets/about-budget-hierarchy#budget-types).

  Allowable values: `shared`, `individual`
</ParamField>

<ParamField body="status" type="string">
  The status of the budget.

  Allowable values: `active`, `hidden`
</ParamField>

<ParamField body="boxId" type="string">
  The ID of the box to work with.

  Allowable values: An existing `boxId`
</ParamField>

### Response

If your request is successful, you'll receive a `201` response containing details about the newly-created sub-budget, including its `id`.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "createdAt": "2023-01-30T08:30:00Z",
    "updatedAt": "2023-01-30T08:30:00Z",
    "id": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
    "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
    "name": "Team Party",
    "type": "shared",
    "status": "active",
    "accountId": "F12345",
    "feature": [
      {
        "createdAt": "2023-01-30T08:30:00Z",
        "updatedAt": "2023-01-30T08:30:00Z",
        "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
        "payments": true,
        "budgetCards": true,
        "peopleCards": true,
        "forwardDeposits": true,
        "BudgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527"
      }
    ],
    "boxId": "f4a7d7c6-6124-45d9-9661-6240559fd1fe",
    "details": [
      {
        "currency": "USD",
        "sortCode": "12-34-56",
        "accountNumber": "12345678",
        "ibans": [
          {
            "iban": "GB26SPPV23188497371875",
            "bic": "BARCGB22"
          }
        ],
        "accountName": "Equals",
        "bankName": "SPECTRUM PAYMENT SERVICES",
        "bankAddress": "Vintners Place, 68 Upper Thames St, London, EC4V 3BJ, United Kingdom",
        "balanceReference": "Balance reference"
      }
    ]
  }
  ```

  ```json Payload structure theme={null}
  {
    "createdAt": "string",
    "updatedAt": "string",
    "id": "string",
    "parentId": "string",
    "name": "string",
    "type": "string",
    "status": "string",
    "accountId": "string",
    "feature": [
      {
        "createdAt": "string",
        "updatedAt": "string",
        "payments": boolean,
        "budgetCards": boolean,
        "peopleCards": boolean,
        "forwardDeposits": boolean,
        "BudgetId": "string"
      }
    ],
    "boxId": "string",
    "details": [
      {
        "currency": "string",
        "sortCode": "string",
        "accountNumber": "string",
        "ibans": [
          {
            "iban": "string",
            "bic": "string"
          }
        ],
        "accountName": "string",
        "bankName": "string",
        "bankAddress": "string",
        "balanceReference": "string"
      }
    ]
  }
  ```
</CodeGroup>

### Error responses

If your request is unsuccessful, you'll receive one of the following error responses.

```json theme={null}
{
  "path": "/v2/budgets",
  "message": "A budget with name: Team Party already exists"
}
```

```json theme={null}
{
  "path": "/v2/budgets",
  "message": "payments are not enabled for this account"
}
```

```json theme={null}
{
  "path": "/v2/budgets",
  "message": "cards are not enabled for this account"
}
```

```json theme={null}
{
  "path": "/v2/budgets",
  "message": "must have at least 1 active currency"
}
```

```json theme={null}
{
  "path": "/v2/budgets",
  "message": "Budgets count limit exceeded: 100"
}
```

```json theme={null}
{
  "path": "/v2/budgets",
  "message": "Account F12345 does not exist"
}
```

For more detailed information about this request and its response, [see the API reference](/api-reference/budgets/create-a-budget).

## Create an individual budget

<Note>
  **POST** `/v2/budgets`
</Note>

### Request

Use this request to create an individual budget associated with a given `personaId`. The name of the budget will automatically be set to that persona's `{firstName} {lastName}`. If the persona's name is updated in the future, the budget's name will also be updated.

<Info>
  A persona represents the relationship between a person and an account. To create an individual budget, you'll need the `personaId` for the person you want to assign it to. You can find this by [listing people](/pages/people/list-people) on your account. [Learn more about personas](/pages/people/about-personas-and-roles).
</Info>

<Info>
  A single persona can only ever have one budget associated with them.
</Info>

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/budgets?accountId=F12345' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
      "personaId": "42a27839-7690-486c-8cf4-5084fab52494",
      "features": [
        "payments"
      ],
      "currencies": [
        "USD"
      ],
      "type": "individual"
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/budgets?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "parentId": "string",
      "personaId": "string",
      "name": "string",
      "features": [
        "string"
      ],
      "currencies": [
        "string"
      ],
      "type": "string"
  }'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that you're creating a budget for.

  Allowable values: An existing `accountId`
</ParamField>

#### Request body schema

<ParamField body="parentId" type="string" required>
  The ID of the parent budget.

  Allowable values: An existing `budgetId` (≤ 36 characters)
</ParamField>

<ParamField body="personaId" type="string" required>
  The ID of the persona that you're creating this budget for.

  Allowable values: An existing `personaId` (≤ 36 characters)
</ParamField>

<ParamField body="features" type="array of strings" required>
  The features that you want to enable for this budget.

  Allowable values: `payments`, `peopleCards`, `budgetCards`
</ParamField>

<ParamField body="currencies" type="array of strings" required>
  The currencies that you want to enable for this budget, in ISO 4217 format. You must provide at least one. If working with a sub-budget, the currencies you provide must be enabled on the parent budget.

  Allowable values: 3 characters
</ParamField>

<ParamField body="type" type="string" required>
  The type that you want this budget to be. Set this to `individual`. [Learn more about budget types](/pages/budgets/about-budget-hierarchy#budget-types).

  Allowable values: `shared`, `individual`
</ParamField>

<ParamField body="status" type="string">
  The status of the budget.

  Allowable values: `active`, `hidden`
</ParamField>

<ParamField body="boxId" type="string">
  The ID of the box to work with.

  Allowable values: An existing `boxId`
</ParamField>

### Response

If your request is successful, you'll receive a `201` response containing details about the newly-created sub-budget, including its `id`.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "createdAt": "2023-01-30T08:30:00Z",
    "updatedAt": "2023-01-30T08:30:00Z",
    "id": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
    "parentId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
    "name": "Jane Doe",
    "type": "individual",
    "status": "active",
    "accountId": "F12345",
    "feature": [
      {
        "createdAt": "2023-01-30T08:30:00Z",
        "updatedAt": "2023-01-30T08:30:00Z",
        "budgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527",
        "payments": true,
        "budgetCards": true,
        "peopleCards": true,
        "forwardDeposits": true,
        "BudgetId": "b489ea2c-0dd1-4fb1-b345-de5a596a5527"
      }
    ],
    "boxId": "f4a7d7c6-6124-45d9-9661-6240559fd1fe",
    "details": [
      {
        "currency": "USD",
        "sortCode": "12-34-56",
        "accountNumber": "12345678",
        "ibans": [
          {
            "iban": "GB26SPPV23188497371875",
            "bic": "BARCGB22"
          }
        ],
        "accountName": "Equals",
        "bankName": "SPECTRUM PAYMENT SERVICES",
        "bankAddress": "Vintners Place, 68 Upper Thames St, London, EC4V 3BJ, United Kingdom",
        "balanceReference": "Balance reference"
      }
    ]
  }
  ```

  ```json Payload structure theme={null}
  {
    "createdAt": "string",
    "updatedAt": "string",
    "id": "string",
    "parentId": "string",
    "name": "string",
    "type": "string",
    "status": "string",
    "accountId": "string",
    "feature": [
      {
        "createdAt": "string",
        "updatedAt": "string",
        "payments": boolean,
        "budgetCards": boolean,
        "peopleCards": boolean,
        "forwardDeposits": boolean,
        "BudgetId": "string"
      }
    ],
    "boxId": "string",
    "details": [
      {
        "currency": "string",
        "sortCode": "string",
        "accountNumber": "string",
        "ibans": [
          {
            "iban": "string",
            "bic": "string"
          }
        ],
        "accountName": "string",
        "bankName": "string",
        "bankAddress": "string",
        "balanceReference": "string"
      }
    ]
  }
  ```
</CodeGroup>

### Error responses

If your request is unsuccessful, you'll receive one of the following error responses. The [shared budget error responses](#error-responses) also apply to individual budgets, along with the following additional errors.

```json 400 — Missing personaId theme={null}
{
  "path": "/v2/budgets",
  "message": "personaId required to create Individual balance"
}
```

```json 400 — Individual budget already exists for persona theme={null}
{
  "path": "/v2/budgets",
  "message": "Individual budget already exists"
}
```

For more detailed information about this request and its response, [see the API reference](/api-reference/budgets/create-a-budget).