Tarazu API

Overview

One REST API, four capabilities: statement parsing (PDF, XLS, XLSX, CSV into clean transactions), a suspicious-activity risk score with weighted reasons, statement integrity checks, and account detail extraction. All requests and responses are JSON over HTTPS, amounts are in INR and timestamps are ISO 8601 in IST (+05:30).

Risk output is a set of indicators, not a verdict. Responses carry risk.disclaimer: “Indicators only. Not a determination of fraud or mule activity.” Show it wherever you display the score.

Authentication

Send your secret key as a Bearer token on every request. Keys are created in the dashboard. Sandbox keys look like tz_test_… and only ever return mock data; live keys look like tz_live_… and respect your IP allowlist.

Authorization: Bearer tz_live_••••••••••••••••

Never ship keys in mobile apps or browsers. Call the API from your backend. For safe retries on POST, send an Idempotency-Key header (any unique string, kept for 24 hours).

Endpoints

curl -X POST https://api.tarazu.example/v1/statements/analyze \
  -H "Authorization: Bearer tz_live_••••••••" \
  -F "file=@statement_apr_sep.pdf" \
  -F "password=•••••" \
  -F 'checks=["parse","risk","integrity","account"]' \
  -F "consent_ref=cns_8F2K19QX"

curl https://api.tarazu.example/v1/statements/stm_01JD4Q7Y3W \
  -H "Authorization: Bearer tz_live_••••••••"

curl "https://api.tarazu.example/v1/statements/stm_01JD4Q7Y3W/transactions?limit=100&flagged=true" \
  -H "Authorization: Bearer tz_live_••••••••"

{
  "data": [
    {
      "id": "txn_3fd0a1",
      "date": "2026-04-02",
      "time": "23:41",
      "mode": "UPI",
      "direction": "cr",
      "amount_inr": 4500,
      "balance_inr": 5120.4,
      "narration": "UPI/CR/412790110482/upi•••12@okbank",
      "flags": [
        "NIGHT_VELOCITY"
      ]
    }
  ],
  "next_cursor": "c_9Qm2",
  "has_more": true
}

curl -X DELETE https://api.tarazu.example/v1/statements/stm_01JD4Q7Y3W \
  -H "Authorization: Bearer $API_KEY"

curl -X POST https://api.tarazu.example/v1/webhooks/test \
  -H "Authorization: Bearer tz_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{"event":"statement.completed"}'

Response schema

POST /statements/analyze and GET /statements/{id} return the same object. Sections you did not request in checks are null.

{
  "id": "stm_01JD4Q7Y3W",
  "status": "completed",
  "processing_ms": 4180,
  "account": {
    "holder_name": "R•••• K•••• S••••",
    "bank": "Sample Co-operative Bank",
    "account_no": "XXXXXXXX4417",
    "ifsc": "SMPL0001234",
    "type": "savings",
    "period": {
      "from": "2026-04-01",
      "to": "2026-09-30"
    }
  },
  "summary": {
    "transactions": 1284,
    "credits_inr": 4821330.5,
    "debits_inr": 4809112,
    "closing_balance_inr": 18630.25
  },
  "integrity": {
    "verdict": "review",
    "checks_passed": 11,
    "checks_total": 13,
    "findings": [
      "font_mismatch_page_4",
      "running_balance_break_row_612"
    ]
  },
  "risk": {
    "score": 78,
    "band": "high",
    "label": "suspicious_activity_indicators",
    "reasons": [
      {
        "code": "PASS_THROUGH",
        "weight": 0.31,
        "detail": "92% of credits leave the account within 30 minutes"
      },
      {
        "code": "MANY_TO_ONE",
        "weight": 0.22,
        "detail": "214 distinct UPI senders, 3 recurring beneficiaries"
      },
      {
        "code": "LOW_RESIDUAL",
        "weight": 0.14,
        "detail": "Median end-of-day balance below ₹600"
      }
    ],
    "disclaimer": "Indicators only. Not a determination of fraud or mule activity."
  }
}

Risk reason codes

Each code describes an observed pattern in the statement. None of them on its own, or together, establishes that an account is used for fraud.

Integrity check codes

Checks that do not apply to the input (for example PDF metadata on a CSV) are reported as pass with a skipped note. Any fail makes the verdict fail; otherwise any review makes it review.

Errors

Errors use standard HTTP status codes and a stable machine-readable code.

{
  "error": {
    "code": "password_required",
    "message": "The PDF is encrypted. Send the password field.",
    "request_id": "req_7Hk2PzQ"
  }
}

Webhooks and signatures

Events: statement.completed, statement.failed. We retry non-2xx responses with exponential backoff for up to 24 hours. Respond within 10 seconds and process asynchronously.

{
  "id": "evt_01JD4Q8A2C",
  "type": "statement.completed",
  "created_at": "2026-11-07T14:32:04+05:30",
  "data": {
    "id": "stm_01JD4Q7Y3W",
    "status": "completed",
    "risk": {
      "score": 78,
      "band": "high"
    },
    "integrity": {
      "verdict": "review"
    }
  }
}

Every delivery carries an X-Signature header: a timestamp and an HMAC-SHA256 of {timestamp}.{raw body} using your webhook signing secret. Verify against the raw request body before parsing JSON, compare in constant time, and reject timestamps older than five minutes.

import crypto from "node:crypto";

// header: X-Signature: t=1762506124,v1=5f2c...e9
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > 300) return false; // reject replays older than 5 minutes
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Rate limits

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. On 429, wait for Retry-After seconds. Higher limits are available on request.

Consent and data retention

Statements contain personal data of the account holder. Under the Digital Personal Data Protection Act, 2023 you act as the Data Fiduciary and Tarazu processes the data on your behalf.

• 01

  consent_ref is required.

  Every analysis must reference a consent record you hold: who consented, when, for what purpose. Requests without it fail with consent_missing.

• 02

  Purpose limitation.

  Use results only for the purpose the holder consented to, such as credit underwriting or onboarding checks.

• 03

  Raw file deleted after processing.

  The uploaded statement and any password are discarded as soon as processing finishes. They are never used for training.

• 04

  Derived data is configurable.

  Parsed transactions, scores and checks are kept for 30 days by default, configurable from 0 to 180 days per workspace.

• 05

  Erasure on request.

  Call DELETE /statements/{id} when a holder withdraws consent; derived data is removed within 24 hours.

• 06

  Data stays in India.

  Processing and storage happen in Indian data centres.

Grievances and data-principal requests: grievance@tarazu.example. Security reports: security@tarazu.example.