API Documentation

Push transactions, FX trades, transfers, and balance snapshots into your Tallyroot workspace from any data source.

Prerequisites

A Tallyroot account. The API is available on the Free plan, which includes one API key; Premium removes the limit
An API key — create one in Settings → API Keys

Authentication

All requests require a Bearer token. API keys start with bk_.

Authorization: Bearer bk_your_api_key_here

Base URL

https://app.tallyroot.com/api/v1/ingest

Endpoints

PUT /transactions

Create or update transactions by externalTxnId. Idempotent — re-sending the same ID updates the existing record.

curl -X PUT https://app.tallyroot.com/api/v1/ingest/transactions \
  -H "Authorization: Bearer bk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "my-connector",
    "transactions": [
      {
        "externalTxnId": "txn-001",
        "accountId": "uuid-of-your-account",
        "bookedAt": "2026-04-10T14:30:00Z",
        "currency": "EUR",
        "amountMinor": "-4550",
        "merchantName": "Grocery Store",
        "description": "Weekly groceries",
        "bookingStatus": "booked"
      }
    ]
  }'

Amount convention: amounts are strings in minor units (cents). Debits are negative, credits are positive.

bookingStatus: pending → booked or voided. Use the same externalTxnId to transition between states.

PUT /fx

Create or update foreign-exchange transactions between two accounts.

curl -X PUT https://app.tallyroot.com/api/v1/ingest/fx \
  -H "Authorization: Bearer bk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "my-connector",
    "fxTransactions": [
      {
        "externalTxnId": "fx-001",
        "fromAccountId": "uuid-eur-account",
        "toAccountId": "uuid-usd-account",
        "fromAmountMinor": "10000",
        "fromCurrency": "EUR",
        "toAmountMinor": "10850",
        "toCurrency": "USD",
        "bookedAt": "2026-04-10T10:00:00Z"
      }
    ]
  }'

PUT /transfers

Create or update internal transfers between your own accounts (same currency).

curl -X PUT https://app.tallyroot.com/api/v1/ingest/transfers \
  -H "Authorization: Bearer bk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "my-connector",
    "transfers": [
      {
        "externalTxnId": "xfer-001",
        "fromAccountId": "uuid-checking",
        "toAccountId": "uuid-savings",
        "amountMinor": "50000",
        "currency": "EUR",
        "bookedAt": "2026-04-10T09:00:00Z"
      }
    ]
  }'

POST /balance-snapshots

Push account balance snapshots for reconciliation and drift detection.

curl -X POST https://app.tallyroot.com/api/v1/ingest/balance-snapshots \
  -H "Authorization: Bearer bk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshots": [
      {
        "accountId": "uuid-of-your-account",
        "currency": "EUR",
        "balanceMinor": "125430",
        "snapshotAt": "2026-04-10T23:59:59Z"
      }
    ]
  }'

POST /alert

Send a connector failure alert to notify the workspace owner.

curl -X POST https://app.tallyroot.com/api/v1/ingest/alert \
  -H "Authorization: Bearer bk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "my-connector",
    "error": "Bank API returned 503",
    "consecutiveFailures": 3
  }'

Responses

Transaction endpoints return:

{
  "created": 1,   // new records
  "skipped": 0,   // unchanged duplicates
  "restated": 0   // updated existing records
}

Errors

Status	Code	Meaning
400	VALIDATION_ERROR	Request body failed validation
401	—	Missing or invalid API key
429	RATE_LIMITED	Too many requests — wait and retry (see Rate Limits)

Rate Limits

120 requests per minute per workspace, shared across all API keys. Every response includes:

Header	Description
X-RateLimit-Limit	Max requests per window (120)
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

Tip: each request can contain many items in the array, so you rarely need more than a few calls per sync cycle.

Node.js SDK

If you're building in Node.js, the official SDK wraps this API with typed methods, error handling, and money helpers.

npm install @tallyroot/sdk

View SDK documentation on GitHub →