Budget view for a month

GET

/budget

curl --request GET \
  --url 'https://api.tovarifinancial.com/budget?month=2026-07' \
  --header 'Authorization: Bearer <token>'

• Production
• Development

Authorizations

• bearerAuth

Parameters

Query Parameters

month

required

Month, ‘YYYY-MM’

string

Example

2026-07

Month ‘YYYY-MM’

Responses

200

Budget view

Media typeapplication/json

object

data

required

object

month

Month, ‘YYYY-MM’

string

income

object

receivedCents

Integer minor units (cents)

integer format: int64

expectedMonthlyCents

Integer minor units (cents)

integer format: int64

threeMonthAvgCents

Integer minor units (cents)

integer format: int64

categoryId

string

nullable

categoryName

string

nullable

colorId

string

nullable

sections

Array<object>

object

id

string

name

string

sortOrder

number

categories

Array<object>

object

id

string

name

string

iconId

string

colorId

string

sortOrder

number

isEnabled

boolean

isBudgeted

boolean

targetCents

Integer minor units (cents)

integer format: int64

targetIsExplicit

boolean

spentCents

Integer minor units (cents)

integer format: int64

expectedCents

Integer minor units (cents)

integer format: int64

threeMonthAvgCents

Integer minor units (cents)

integer format: int64

rolloverUnspentCents

Integer minor units (cents)

integer format: int64

remainingCents

Integer minor units (cents)

integer format: int64

budgetCents

Integer minor units (cents)

integer format: int64

plannedCents

Integer minor units (cents)

integer format: int64

other

object

reserveCents

Integer minor units (cents)

integer format: int64

categories

Array<object>

object

id

string

name

string

iconId

string

colorId

string

sectionId

string

nullable

sectionName

string

nullable

spentCents

Integer minor units (cents)

integer format: int64

threeMonthAvgCents

Integer minor units (cents)

integer format: int64

expectedCents

Integer minor units (cents)

integer format: int64

safeToBudget

object

expectedIncomeCents

Integer minor units (cents)

integer format: int64

totalTargetsCents

Integer minor units (cents)

integer format: int64

otherReserveCents

Integer minor units (cents)

integer format: int64

safeToBudgetCents

Integer minor units (cents)

integer format: int64

feasibilityDeficitCents

Integer minor units (cents)

integer format: int64

totals

object

totalBudgetCents

Integer minor units (cents)

integer format: int64

totalSpentCents

Integer minor units (cents)

integer format: int64

totalOutflowCents

Integer minor units (cents)

integer format: int64

message

string

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "data": {
    "month": "2026-07",
    "sections": [
      {
        "categories": [
          {
            "isBudgeted": true
          }
        ]
      }
    ]
  }
}

400

Validation failed — see errorCode / fieldErrors

Media typeapplication/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS ORG_NAME_TAKEN INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND

message

required

string

fieldErrors

Optional field-level validation errors, keyed by field name.

object

key

additional properties

Array<string>

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

401

Missing, invalid, or expired bearer token

Media typeapplication/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS ORG_NAME_TAKEN INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND

message

required

string

fieldErrors

Optional field-level validation errors, keyed by field name.

object

key

additional properties

Array<string>

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

403

Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.

Media typeapplication/json

object

errorCode

required

Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.

string

Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED

message

required

string

details

object

outstanding

required

Active policy versions the user has not yet accepted.

Array<object>

object

id

required

string format: uuid

policyType

required

string

version

required

integer

title

required

string

firstAcceptance

required

True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.

boolean

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "errorCode": "EMAIL_NOT_VERIFIED"
}

500

Internal error (no internal detail leaked)

Media typeapplication/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS ORG_NAME_TAKEN INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND

message

required

string

fieldErrors

Optional field-level validation errors, keyed by field name.

object

key

additional properties

Array<string>

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

503

Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.

Media typeapplication/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS ORG_NAME_TAKEN INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND

message

required

string

fieldErrors

Optional field-level validation errors, keyed by field name.

object

key

additional properties

Array<string>

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "errorCode": "INVALID_EMAIL_FORMAT"
}