Income vs expense over a month range

GET

/reports/income-vs-expense

curl --request GET \
  --url 'https://api.tovarifinancial.com/reports/income-vs-expense?preset=this_month&start=2026-07&end=2026-07&includeContributions=1' \
  --header 'Authorization: Bearer <token>'

• Production
• Development

Per-month income and expense series plus KPIs. Range resolves through the shared selectReportMode; with no preset/start/end it defaults to last_6_months. A custom range is at most 12 months and a future end is clamped to the current month. budgetOnly filters the EXPENSE side only — income is never budget-filtered. includeContributions=1 adds the opt-in range-wide contributions block; without it the response is { mode, period, months, kpis } exactly as before.

Authorizations

• bearerAuth

Parameters

Query Parameters

preset

string

Allowed values: this_month last_month last_3_months last_6_months ytd last_year

Range preset (mutually exclusive with start/end)

start

Month, ‘YYYY-MM’

string

Example

2026-07

Range start month ‘YYYY-MM’

end

Month, ‘YYYY-MM’

string

Example

2026-07

Range end month ‘YYYY-MM’

accountIds

string

Comma-separated account UUIDs to scope the report to. Omit for all accounts. A malformed value is rejected with 400 — it is never dropped to an unfiltered report.

budgetOnly

string

Set to ‘1’ or ‘true’ to restrict the expense side to budgeted expense categories. Never applied to income. Any other value is treated as false.

includeContributions

string

Allowed values: 1 true

Set to ‘1’ or ‘true’ to add the range-wide contributions block (top income sources and expense categories for the whole window) to the response. Omit for the default response, which carries no contributions key. Unlike budgetOnly, ANY other present value — including an empty value and ‘0’ — is rejected with 400, never treated as false.

Responses

200

Income-vs-expense report

Media typeapplication/json

object

data

required

object

key

additional properties

any

message

string

requestId

required

string

timestamp

required

string format: date-time

Example^generated

{
  "data": {},
  "message": "example",
  "requestId": "example",
  "timestamp": "2026-04-15T12:00:00Z"
}

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"
}