/ Guides / Budgets / Create budgets

Create budgets

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

Create a shared budget

Post/v2/budgets

Request

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

Sample requestRequest structure
Copy
Copied
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"
  }'
Copy
Copied
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",
}'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating a budget for.

Allowable values:
An existing accountId

Request body schema

Parameter Description
parentId
string
required		 The ID of the parent budget.

Allowable values:
An existing budgetId (<= 36 characters)
name
string
required		 The name of the new budget. Depending on your configuration, this might appear as the payee name.

Allowable values:
<= 75 characters
features
array of strings
required		 The features that you want to enable for this budget.

Allowable values:
payments, peopleCards, budgetCards
currencies
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
type
string
required		 The type that you want this budget to be. Set this to shared. Learn more about budget types.

Allowable values:
shared, individual
status
string		 The status of the budget.

Allowable values:
active, hidden
boxId
string		 The ID of the box to work with.

Allowable values:
An existing boxId

Response

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

Sample responsePayload structure
Copy
Copied
{
  "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 Money",
      "bankName": "SPECTRUM PAYMENT SERVICES",
      "bankAddress": "Vintners Place, 68 Upper Thames St, London, EC4V 3BJ, United Kingdom",
      "balanceReference": "Balance reference"
    }
  ]
}
Copy
Copied
{
  "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"
    }
  ]
}

For more detailed information about this request and its response, see the API reference.

Create an individual budget

Post/v2/budgets

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 single persona can only ever have one budget associated with them.

Sample requestRequest structure
Copy
Copied
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"
  }'
Copy
Copied
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"
}'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that you're creating a budget for.

Allowable values:
An existing accountId

Request body schema

Parameter Description
parentId
string
required		 The ID of the parent budget.

Allowable values:
An existing budgetId (<= 36 characters)
personaId
string
required		 The ID of the persona that you're creating this budget for.

Allowable values:
An existing personaId (<= 36 characters)
features
array of strings
required		 The features that you want to enable for this budget.

Allowable values:
payments, peopleCards, budgetCards
currencies
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
type
string
required		 The type that you want this budget to be. Set this to individual. Learn more about budget types.

Allowable values:
shared, individual
status
string		 The status of the budget.

Allowable values:
active, hidden
boxId
string		 The ID of the box to work with.

Allowable values:
An existing boxId
personaId
string
required		 The ID of the persona that must be assigned to the budget. This is required only for individual budgets.

Allowable values:
An existing personaId

Response

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

Sample responsePayload structure
Copy
Copied
{
  "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 Money",
      "bankName": "SPECTRUM PAYMENT SERVICES",
      "bankAddress": "Vintners Place, 68 Upper Thames St, London, EC4V 3BJ, United Kingdom",
      "balanceReference": "Balance reference"
    }
  ]
}
Copy
Copied
{
  "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"
    }
  ]
}

For more detailed information about this request and its response, see the API reference.