Schema

One envelope. Every endpoint.

Send one consistent JSON shape from your systems, then call any of our 8 core endpoints without redesigning your data for each feature.

Production calls count toward your monthly quota (500 successful API calls free per UTC month); the playground does not use that allowance.

Core payload (always required)

account_id — stable id you control for tracing and support.
transactions[] — ISO-8601 posted_at, integer minor units, explicit inflow/outflow direction.
balances — current cash plus trailing 30-day low / high watermarks for forecast and runway-style endpoints.

Conditional blocks (add when the question requires them)

ar_aging — receivable buckets for AR acceleration and collections prioritization.
payables — AP lines for due dates, reconciliation, and early-pay discount recovery.
fx_rates — pair map for multi-currency normalization on your side.
policy_rules — optional declarative caps you include on the shared envelope when you want them available to scoring routes.
scenario — knobs for the scenario runner.
baseline / thresholds / merchant_meta — optional enrichments that tighten scores when you have them.

Full envelope example (all optional blocks shown)

Illustrative JSONC-style comments for documentation — copy into JSON after removing // comment lines or use as a structural guide. Payables items must satisfy the live Zod schema in lib/schemas/envelope.ts (e.g. required id and due_at per line).

{
  // Required for every endpoint
  "account_id": "acct_demo_001",

  // Required: at least 30 days of transactions recommended
  "transactions": [
    {
      "id": "txn_001",
      "posted_at": "2026-03-01T00:00:00.000Z",   // ISO-8601
      "amount_minor": 250000,                    // integer, minor units (e.g. cents)
      "direction": "inflow",                     // "inflow" | "outflow"
      "category": "revenue"                      // optional but improves scoring
    },
    {
      "id": "txn_002",
      "posted_at": "2026-03-03T00:00:00.000Z",
      "amount_minor": 85000,
      "direction": "outflow",
      "category": "payroll"
    }
  ],

  // Required: trailing 30-day balance watermarks
  "balances": {
    "current_minor": 512000,
    "low_30d_minor": 210000,
    "high_30d_minor": 640000
  },

  // Optional: needed for ar-aging-accelerator
  "ar_aging": {
    "buckets": [
      { "label": "0-30d",  "amount_minor": 180000 },
      { "label": "31-60d", "amount_minor": 95000  },
      { "label": "61-90d", "amount_minor": 40000  },
      { "label": "90d+",   "amount_minor": 22000  }
    ]
  },

  // Optional: needed for early-payment-discount-leak (id + due_at + amount_minor per item; discount_minor optional)
  "payables": {
    "items": [
      {
        "id": "ap_001",
        "due_at": "2026-04-30T00:00:00.000Z",
        "amount_minor": 120000,
        "discount_minor": 2400
      }
    ]
  },

  // Optional: for simulated-scenario-runner (field names per API schema)
  "scenario": {
    "revenue_delta_pct": -20,
    "opex_delta_pct": 10,
    "delay_payables_days": 15
  },

  // Optional: async delivery — omit for synchronous response
  "webhook_url": "https://your-server.com/cashytics-hook"
}

You do not need all blocks for every endpoint. See the endpoint reference to know which optional blocks each slug uses.

Implementation reference

The canonical Zod schema ships in the open repo as lib/schemas/envelope.ts — useful when you want codegen or JSON Schema export for your own gateway.