Skip to content
calternal docs

Create an account

POST
/api/v1/money/budgets/{budget_id}/accounts
curl --request POST \
  --url https://example.com/api/v1/money/budgets/example/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "example", "name": "example", "opening_balance": 1, "opening_date": "example" }'

Add a cash, card, or tracking account to a budget. An opening balance needs an opening date. A card account also adds its payment Category. The response lists the accounts. Route: /api/v1/money/budgets/{budget_id}/accounts. Inputs: budget_id. Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
budget_id
required
string

Budget ID

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Create an account (and, for a Card account, its payment Category).

object
kind
required

cash, card or tracking.

string
name
required

Display name.

string
opening_balance

Opening balance in minor units (a Card account’s debt is negative).

integer | null format: int64
opening_date

Date of the opening balance YYYY-MM-DD (required with a balance).

string | null
Examplegenerated
{
  "kind": "example",
  "name": "example",
  "opening_balance": 1,
  "opening_date": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

The account list with the new account

Media typeapplication/json

Accounts of a budget with totals.

object
accounts
required

Accounts in file order.

Array<object>

One account with its balances in budget minor units.

object
balance
required

Balance of every recorded row.

integer format: int64
cleared_balance
required

Balance of cleared rows.

integer format: int64
closed
required

Closed accounts remain available through history and deep links (#1130).

boolean
currency
required

Account currency.

string
debt_not_covered

For a Card account: debt its payment reserve does not cover.

integer | null format: int64
id
required

Account ID.

string
kind
required

cash, card or tracking.

string
name
required

Display name.

string
on_budget
required

False for Tracking accounts.

boolean
payment_category_id

For a Card account: its payment Category.

string | null
uncleared_balance
required

Balance of uncleared rows.

integer format: int64
budget_id
required

Budget ID.

string
currency
required

Budget currency.

string
on_budget_total
required

Sum of on-budget balances.

integer format: int64
scale
required

Decimal places of currency.

integer format: int32
tracking_total
required

Sum of tracking balances.

integer format: int64
Examplegenerated
{
  "accounts": [
    {
      "balance": 1,
      "cleared_balance": 1,
      "closed": true,
      "currency": "example",
      "debt_not_covered": 1,
      "id": "example",
      "kind": "example",
      "name": "example",
      "on_budget": true,
      "payment_category_id": "example",
      "uncleared_balance": 1
    }
  ],
  "budget_id": "example",
  "currency": "example",
  "on_budget_total": 1,
  "scale": 1,
  "tracking_total": 1
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

404

Section titled “404”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

409

Section titled “409”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}