Skip to content
Tovari Docs

The investment portfolio for a period: value, net invested, growth and the reconciliation

GET
/investments/overview
curl --request GET \
  --url 'https://api.tovarifinancial.com/investments/overview?period=1M' \
  --header 'Authorization: Bearer <token>'

Read-only: it parses no X-Idempotency-Key. While the INVESTMENTS_PHASE1_ENABLED rollout flag is off the body is { enabled: false } and nothing else. Otherwise state is the single discriminant: empty (no Plaid-linked investment account in scope), syncing (linked, no value yet), holdings-only (values but no activity history, so no invested line and no reconciliation) or decomposed. Money is integer cents, ratios integer basis points, quantities exact decimal strings and dates America/New_York calendar days; null means absent. The reconciliation ties only through unreconciledCents: market growth is measured from the nightly holdings series and is never back-solved.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
period
string
Allowed values: 1M 3M 6M YTD 1Y ALL

One of 1M, 3M, 6M, YTD, 1Y, ALL; absent means ALL. A period that reaches before tracking began is served as ALL, with requestedPeriod echoing the ask. Any other value is a 400.

Responses

Section titled “Responses”

200

Section titled “200”

The portfolio overview, or { enabled: false } while the rollout flag is off

Media typeapplication/json
object
data
required
One of:
object
enabled
required
boolean
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "data": {
    "enabled": false
  }
}

400

Section titled “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 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

Section titled “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 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

Section titled “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. This operation is ALSO capability-fenced: after the three gate codes, an org whose plan does not include this feature is refused with errorCode CAPABILITY_REQUIRED and no details. The fence has its OWN switch and is unreachable while CAPABILITY_FENCE_ENABLED is not exactly true — that switch is independent of BILLING_ENABLED, so this code is reachable with the subscription paywall off. The errorCode enum on this operation’s response schema is the complete, machine-readable list.

Media typeapplication/json
object
errorCode
required

Which condition refused the request, evaluated in this order (CCR-1). SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true; CAPABILITY_REQUIRED is unreachable while CAPABILITY_FENCE_ENABLED is not exactly true. The two switches are independent, so CAPABILITY_REQUIRED is reachable with the subscription paywall off. CAPABILITY_REQUIRED carries no details.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED CAPABILITY_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

Section titled “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 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

Section titled “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 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"
}