Safe-to-spend disposable-cash figure
const url = 'https://api.tovarifinancial.com/dashboard/safe-to-spend?includeTransferImpact=1';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.tovarifinancial.com/dashboard/safe-to-spend?includeTransferImpact=1' \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Set to ‘1’ or ‘true’ to add the optional transferImpact disclosure block (KAN-2852) to data. Omit for the default response, which carries no transferImpact key and is otherwise identical. ANY other present value — including an empty value and ‘0’ — is rejected with 400, never treated as false. A failed impact read never fails the request: it is answered 200 without the key.
Responses
Section titled “Responses”Safe-to-spend DTO. Order of accountBreakdown[] mirrors includedAccounts[] and is rendered positionally; SUM(clearToSpendCents) === safeToSpendCents by construction.
object
object
Server-authoritative tri-state, one rule for both branches: safeToSpendCents < 0 => negative; <= tightThresholdCents => tight; otherwise healthy. The threshold is always >= 0, so $0.00 is structurally never “healthy”. Clients must not re-derive this from a client-side threshold.
Why the state reads the way it does. INFORMATIONAL except for ‘no-accounts’, which clients MUST consult BEFORE state to show the connect-an-account affordance (the empty branch’s $0 headline is a structural zero, not a measurement). ‘typical-spending’ when tightThresholdCents > 0; ‘zero-threshold’ when it is 0 (no history and no plan — no cushion is fabricated).
One pay period of typical spending: (customarySpendCents + budgeted non-bill-linked targets) x cycleDays / 30.4375, decimal.js ROUND_HALF_UP, clamped at 0.
Whole days from today through horizonDate, INCLUSIVE of both ends (a horizon of today is 1).
object
Only checking/savings can appear — migration 014’s CHECK forces include_in_safe_to_spend = FALSE for investment/credit_card/loan.
Integer minor units (cents). Equals the matching includedAccounts[] entry.
Signed sum of this account’s obligations (negative for net outflow).
BalanceCents + billsDueCents. SIGNED and never floored.
ClearToSpendCents < 0.
The bills behind billsDueCents, de-duplicated, in first-occurrence order by dateIso.
DISCLOSURE ONLY — no Safe to Spend figure is adjusted by it. Open own-account transfer suggestions in the customary-spend window [first of the client-local current month − 3 months, first of that month), org-wide; their unlinked legs may be counted in the spending the automatic cushion is based on. Present ONLY when includeTransferImpact was sent AND the household has included accounts AND cushionMode is automatic AND hasSpendingHistory is true AND the live read succeeded; otherwise the key is ABSENT (never null). Read live on every opted-in request, never from the snapshot.
object
Distinct open transfer-suggestion pairs with at least one leg inside the window.
Integer minor units (cents). In-window pair legs counted as income today, de-duplicated by transaction.
Integer minor units (cents). In-window pair legs counted as spend today, de-duplicated by transaction.
The read hit its row cap (200), so every figure is a FLOOR; clients render the count as “N+”.
Example
{ "data": { "state": "healthy", "stateBasis": "no-accounts", "accountBreakdown": [ { "accountType": "checking" } ] }}Validation failed — see errorCode / fieldErrors
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}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.
object
Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}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.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}