Claims Case Intake Hub

A claims/case intake and adjudication backend, with bank verification via Plaid before any payout is authorized — and it runs as a working demo the moment it's deployed, no credentials required.

A claim walks a fixed lifecycle — submitted → under_review → bank_verified → approved | rejected. Documents are validated on intake, the claimant's bank is verified before a cent is approved, and every transition is written to an append-only audit trail. The centerpiece is a hard payout gate: a claim literally cannot reach approved until its bank verification has passed.

Claims and cases don't arrive as clean records. They arrive as a pile of documents and a promise to pay — and the real risk isn't collecting them, it's authorizing money against them. Most intake tools stop at "we received your form." The expensive mistakes happen after that: a payout approved on incomplete paperwork, or sent to an account nobody verified, with no record of who decided what.

This hub carries a claim all the way to a defensible payout decision. Documents are validated on intake, the claimant's bank is verified before a cent is approved, and every state change is written to an append-only claim_event trail you could hand to an auditor. The hard payout gate — a claim cannot be approved until its bank verification has passed — is the difference between "we processed a claim" and "we can prove why we paid." Even if you never touch Plaid, the shape is the point: a workflow that turns a stack of uploads into an accountable, auditable financial action. Swap Plaid for any verification step you like; the gate and the trail stay.

backend/
  api/
    claims_intake/
      api_group.xs
      claims_approve_POST.xs
      claims_dashboard_GET.xs
      claims_get_GET.xs
      claims_list_GET.xs
      claims_reject_POST.xs
      claims_seed_POST.xs
      claims_submit_POST.xs
      claims_validate_POST.xs
      claims_verify_bank_POST.xs
  function/
    claims_check_auth.xs
    claims_check_transition.xs
    claims_plaid_verify_bank.xs
    claims_record_event.xs
    claims_validate_document.xs
  table/
    bank_verification.xs
    claim.xs
    claim_document.xs
    claim_event.xs
  workflow_test/
    claims_gate_and_reject.xs
    claims_happy_path.xs
  workspace/
    claims_case_intake_hub.xs

submitted ──validate──▶ under_review ──verify-bank──▶ bank_verified ──approve──▶ approved
                             │                              │
                             └──────────── reject ──────────┴──▶ rejected

The state machine lives in one place — claims_check_transition — and is enforced on every mutating call; an illegal transition returns a 400 and changes nothing. Each accepted transition writes an audit row through claims_record_event, so the claim_event trail is a complete, append-only record of who did what and when.

• Validate (claims_validate_document) — moves submitted → under_review only if every attached document passes its type/size checks.
• Verify bank (claims_plaid_verify_bank) — moves under_review → bank_verified. Calls Plaid's /auth/get to confirm the claimant's account and pull its ACH account + routing numbers. Out of the box, with no credentials, it returns Plaid's documented sandbox values (First Platypus Bank, routing 011401533) so the full pipeline runs end-to-end; those rows are marked mode: "demo". Set the Plaid env vars and pass an access_token from your Plaid Link integration and the call hits Plaid for real, marking rows mode: "live". (Plaid authenticates with client_id + secret in the JSON body, no Authorization header — handled for you.)
• Approve (claims_check_auth gate) — moves bank_verified → approved only. This is the payout gate.
• Reject — from under_review or bank_verified → rejected.

Start with your coding agent. Paste the prompt below into a local MCP-capable coding agent — Claude Code, Cursor, Windsurf, and others. It installs the Xano CLI, connects Xano, and imports this template.

Start building in Xano: Access the prompt at https://go.xano.co/start-xano-with-template-skill and run it here with claims-intake-plaid as your template.

The agent will walk you through the setup below.

1. Deploy backend/ to a Xano workspace: xano workspace push -d backend.
2. Seed the demo data (see Seed data): POST /claims/seed.
3. Open the console (see Frontend): serve frontend/index.html, paste your api:xxxx group URL into the header, and click Connect.

The whole flow — including bank verification and the payout gate — runs credential-free on the seed.

All endpoints live in the ClaimsIntake API group (api:<claims-intake-group>). If API_AUTH_SECRET is set, every write requires a matching api_secret field or X-API-Secret header; unset leaves the demo open.

POST /claims                        submit a claim + documents (starts at submitted)
GET  /claims                        list, newest first; optional ?status= filter
GET  /claims/{claim_id}             case file — claim + documents + bank verification + full audit trail
POST /claims/{claim_id}/validate    submitted → under_review; every document must pass type/size checks
POST /claims/{claim_id}/verify-bank under_review → bank_verified; runs Plaid Auth (or demo data)
POST /claims/{claim_id}/approve     bank_verified → approved ONLY — the payout gate
POST /claims/{claim_id}/reject      under_review or bank_verified → rejected
GET  /claims/dashboard              counts per status + approved-payout total
POST /claims/seed                   load demo data (idempotent)

• claim — one claim/case, the workflow entity: submitted → under_review → bank_verified → approved | rejected. Cannot reach approved until the bank is verified.
• claim_document — a document attached to a claim; Xano owns the metadata, the bytes live in your object store under an opaque document_ref (no S3 required for the demo).
• bank_verification — the result of verifying a claimant's bank via Plaid, one row per claim; its presence + verified=true is the payout gate.
• claim_event — append-only audit trail; every state transition and decision writes one row (who, when, what changed).

Ships with tests you can run on any deployment.

• Unit tests (xano unit_test run_all) — embedded test blocks in claims_check_transition, claims_validate_document, claims_check_auth, and claims_plaid_verify_bank cover the state-machine boundaries, document validation, the auth gate, and the Plaid verify function's demo path.
• Workflow tests (xano workflow_test run_all):
  • claims_happy_path — a claim walks submit → validate → verify-bank → approve, ending in the right status with a 4-event audit trail.
  • claims_gate_and_reject — proves a claim cannot be approved before bank verification, plus the reject and invalid-document branches.

The Plaid /auth/get contract is covered by a mock built from Plaid's documented /auth/get response (sandbox account 1111222233330000, routing 011401533).

The demo runs credential-free — Plaid falls back to documented sandbox values. Set these to verify against a real Plaid account.