One page of the caller's own notification feed

GET

/notifications

const url = 'https://api.tovarifinancial.com/notifications?unreadOnly=1&category=connection';
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/notifications?unreadOnly=1&category=connection' \
  --header 'Authorization: Bearer <token>'

PER-USER at the row layer: the select policy requires user_id = current_user_id with NO admin carve-out, so in a two-person household an admin cannot read a partner’s feed even by crafting a request. Keyset-paginated on (createdAt DESC, id DESC): pass the previous response’s nextCursor back as cursor. THE CURSOR IS OPAQUE — never parse or construct one; a malformed value is a 400, never a silent restart at page one. dataTrust must be rendered from THIS response rather than re-derived from GET /plaid/items’ feedFreshness, which collapses “stalled” and “quiet” into one value and would fire on an ordinary dormant account.

Authorizations

bearerAuth

Parameters

Query Parameters

limit

integer

Page size, 1–50. Default 20. Anything else is a 400.

cursor

string

Opaque cursor from a previous response’s nextCursor.

unreadOnly

string

Allowed values: 1

Set to ‘1’ to return unread rows only. Any other value is ignored.

category

string

Allowed values: connection bills budget security org digest

Restrict to one category.

Responses

200

One page, newest first

application/json

object

data

required

object

notifications

required

Array<object>

object

required

string format: uuid

type

required

The registry type code, e.g. connection.reauth_required. OPEN vocabulary by contract — a client must not switch exhaustively on it.

string

category

required

string

Allowed values: connection bills budget security org digest

severity

required

string

Allowed values: info warning critical

title

required

string

body

required

Server-rendered prose. The card renders this verbatim and never re-derives it from payload.

string

deepLink

required

string

nullable

payload

required

Per-type structured payload, discriminated on kind. An unrecognised shape resolves to { kind: 'generic' }. Every money member is integer minor units in a *Cents field.

object

kind

required

string

key

additional properties

any

groupCount

required

How many underlying events this row rolls up, when it rolls up any.

integer

nullable

createdAt

required

string format: date-time

readAt

required

string format: date-time

nullable

nextCursor

required

Null on the last page. Opaque — pass it back verbatim as cursor.

string

nullable

unreadCount

required

The caller’s WHOLE unread count, not the count on this page.

integer

dataTrust

required

object

suppressed

required

TRUE only when a suppressible type is ACTUALLY being withheld under the scoped gate.

boolean

reason

required

string

nullable

Allowed values: feed_stalled reauth_required

institutionName

required

string

nullable

suppressedTypes

required

The notification type codes currently withheld. Empty when nothing is suppressed.

Array<string>

message

string

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "data": {
    "notifications": [
      {
        "category": "connection",
        "severity": "info"
      }
    ],
    "dataTrust": {
      "reason": "feed_stalled"
    }
  }
}

400

Validation failed — see errorCode / fieldErrors

application/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

Missing, invalid, or expired bearer token

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

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.

application/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

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)

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

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.

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

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