Skip to content
Tovari Docs

The caller's delivery preferences, fully resolved

GET
/notifications/preferences
curl --request GET \
  --url https://api.tovarifinancial.com/notifications/preferences \
  --header 'Authorization: Bearer <token>'

SUBSCRIPTION-EXEMPT, with its PUT sibling: a lapsed household still receives always-on security and data-export mail and must keep a way to turn the rest of it off. types[] is the code registry LEFT JOINed onto stored overrides — an absent override resolves to the registry default here, so a client cannot predict this shape and must read it. sortOrder, categoryLabel, emailSupported and pushSupported are served so no client hard-codes a heading map, an ordering, or which types support push. With push unavailable in the deployment, push.available is false and no device row is read.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The resolved preferences document

Media typeapplication/json
object
data
required
object
timezone
required

The STORED IANA zone. Null until an X-Client-Timezone header has ever been observed.

string
nullable
effectiveTimezone
required

The zone scheduling actually uses. Never null — ‘UTC’ is the one fallback.

string
emailEnabled
required
boolean
quietHours
required

Paired or null; both are 0..1439. A wrapping range (22:00 -> 07:00) is normal. Affects EMAIL QUEUE TIMING only.

object
startMinute
required
integer
endMinute
required
integer
digest
required
object
enabled
required
boolean
weekday
required

0..6, 0 = Sunday.

integer
hourLocal
required

0..23, in effectiveTimezone.

integer
push
required
object
available
required

PUSH_ENABLED AND NOTIFICATIONS_ENABLED. False renders no push UI at all, and no device row is read.

boolean
deliveryActive
required

Available AND masterEnabled AND at least one live device. Server-derived; never re-computed by a client.

boolean
masterEnabled
required
boolean
registeredDeviceCount
required
integer
devices
required

At most 20 LIVE rows, most-recently-seen first. Never the push token or its fingerprint.

Array<object>
object
installId
required

The app-generated handle: 8–128 characters of A-Z, a-z, 0-9, _ or -.

string
platform
required
string
Allowed values: ios android
deviceName
required
string
nullable
lastSeenAt
required
string format: date-time
types
required
Array<object>
object
type
required

The registry type code, e.g. bills.due_rollup. OPEN vocabulary — a newer deployment may add one.

string
category
required
string
Allowed values: connection bills budget security org digest
categoryLabel
required

Server-supplied heading. Clients must not carry a category-to-heading map.

string
label
required
string
description
required
string
sortOrder
required

The order the rows are returned in; render positionally.

integer
alwaysOn
required

Security and data-export notices. Attempting to disable one is a 400.

boolean
emailSupported
required
boolean
pushSupported
required

Served on EVERY row, always-on ones included, so no client hard-codes which types support push.

boolean
inAppEnabled
required
boolean
emailEnabled
required
boolean
pushEnabled
required

The RESOLVED answer (stored override, else the registry default). False whenever pushSupported is false.

boolean
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "data": {
    "push": {
      "devices": [
        {
          "platform": "ios"
        }
      ]
    },
    "types": [
      {
        "category": "connection"
      }
    ]
  }
}

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.

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

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