JSON-RPC API

Reference for the Savi Finance JSON-RPC API: request format, authentication, errors and documented methods.

Last updated October 2, 2026

Your first authenticated read

1. Run ping to verify connectivity without a token. Expect a live HTTP 200 response with reply: pong.
2. Sign in with the guided email-code flow, then verify the token with getCurrentUser.
3. Call listAccounts. The signed-in userId replaces the example userId; a pasted token alone does not identify it. An empty account list can still be a successful read.

Requests here use your real Savi data. Local previews are fixed examples, not a sandbox. Start with reads; write and email actions require explicit confirmation.

Request format

Send a JSON-RPC 2.0 POST with Content-Type: application/json to:

https://api-v2.financesavi.com/rpc

{
  "jsonrpc": "2.0",
  "method": "ping",
  "params": {},
  "id": 1
}

Authenticated methods need an Authorization: Bearer <token> header. See Authentication.

Simulate transaction and goal timelines

Test clocks let an integration exercise time-based flows without waiting for bank posts. Create an isolated scenario with createTestClock, move its clock forward with advanceTestClock, and inspect posted and pending activity with getTestClock.

{
  "frozenTime": "2026-10-02T00:00:00Z",
  "transactions": [
    {
      "at": "2026-10-03T00:00:00Z",
      "name": "Simulated payroll",
      "amount": 2500,
      "currency": "CAD",
      "type": "INCOME"
    }
  ],
  "goals": [
    {
      "name": "Emergency fund",
      "targetAmount": 1000,
      "initialAmount": 100,
      "contributions": [
        {
          "at": "2026-10-03T00:00:00Z",
          "amount": 150
        },
        {
          "at": "2026-10-04T00:00:00Z",
          "amount": 250
        }
      ]
    }
  ]
}

A clock owns only its synthetic scenario. Its events do not enter listTransactions or listSavingGoals, and the API does not contact a bank. Event schedules are fixed at creation; each createTestClock call creates a separate clock, so create one per tester or scenario and keep its returned id. Clocks belong to the authenticated Savi identity, not an individual bearer-token session. People using the same identity can access and advance the same clock IDs; separate identities are isolated. Time moves forward only, up to the returned maxTime. Clocks expire after seven days and can be removed with deleteTestClock. See the MCP test-clock workflow to run the same flow through tools.

Use with Postman

Download the collection and import it in Postman using the Postman import flow. It includes a request for every documented API method, with the versioned endpoint prefilled and public and authenticated methods grouped separately. Get an API token through the sign-in flow, then set the collection's saviToken variable locally. Store it as a secure variable or in Postman Vault, and never share or export a collection after adding a token.

Example IDs may not exist in your account. Review every request before sending; some methods change real data or send email.

Download Postman collection

Responses and errors

A successful call returns HTTP 200 with a result. A rejected call returns an error object. The captures below show the status and body returned by safe, unauthenticated production requests.

Troubleshooting a request

1. No HTTP response: check connectivity or browser CORS. Local preview origins may be blocked by the production API. Run the copied cURL snippet to distinguish an API failure from browser restrictions.
2. HTTP response but no matching JSON-RPC result: inspect the body and error code. HTTP 200 alone does not prove success; check the JSON-RPC version, request id, and result/error envelope.
3. Unauthenticated or permission denied: sign in again or check ownership and roles. API bearer tokens and MCP OAuth tokens serve different endpoints.
4. A request timed out: the docs stop waiting after 30 seconds. Check whether a write completed before retrying; requests are not automatically retried.

When reporting a problem, include the method, HTTP status, JSON-RPC error code, and a sanitized description of the request. Remove tokens, email codes, and personal financial data.

Error codes

Errors use JSON-RPC envelopes, rather than REST Problem Details. Inspect both the HTTP status and the JSON-RPC error object. These captured requests do not read or change account data.

{
  "jsonrpc": "2.0",
  "method": "ping",
  "params": {
    "message": 42
  },
  "id": 2
}

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "invalid params"
  },
  "id": 2
}

{
  "jsonrpc": "2.0",
  "method": "codexProofMethodDoesNotExist",
  "params": {},
  "id": 3
}

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "unknown method"
  },
  "id": 3
}

{
  "jsonrpc": "2.0",
  "method": "getCurrentUser",
  "params": {},
  "id": 4
}

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32002,
    "message": "missing or invalid auth token"
  },
  "id": 4
}

Methods

Machine-readable references: method manifest, error-code registry, and Postman collection JSON.