Beta
Capulse FOR PARTNERS
Partner API · Beta REST + Webhooks Download OpenAPI Interactive reference ↗

Partner API Documentation

Capulse provides financial intelligence APIs for fintech and institutional teams, including consent-bound Credit, Lending & Risk endpoints. Use the reference to review endpoint inputs, scopes, response schemas and integration requirements for your company.

Overview

Capulse is a B2B financial intelligence API platform for fintech and WealthTech platforms, brokers, research and advisory firms, PMS teams, banks, NBFCs, lenders, and credit bureaus. The API is organized into eight families with company-managed keys, usage metering and webhook support for supported workflows. Each endpoint documents its input requirements, scopes and data limitations.

One partner platform · eight API families

Financial intelligence APIs for partners

Integrate the financial data and analysis your product needs through documented REST endpoints. Each API reference explains its inputs, response fields, access requirements and data limitations.

01Source-dependent

Market Data

Supported market and instrument lookups, company data, quotes, history, and market context.

02Partner-submitted

Financial Account & Asset Data

Submit and retrieve partner-authorized account snapshots, balances, transactions, holdings, and aggregates. Direct bank and broker connections are not implied.

03Structured analytics

Financial Intelligence & Scoring

Market, company, portfolio, F&O and trading-behaviour analysis returned as structured fields and evidence.

04Consent-bound

Credit, Lending & Risk

Partner-supplied cash-flow, debt-burden, affordability, SME-ratio, threshold-risk, anomaly, early-warning, and human-review APIs. No bureau score, fraud finding, or lending decision.

05Partner API · Beta

Payments, Banking & Reconciliation

Import tokenized partner transaction and settlement records, look up imported status, reconcile sources with versioned rules, review exceptions, and export results. No bank connection or money movement.

06Partner controls

DPDP, Consent & Data Governance

Partner-attested consent records and scope checks support limited account operations; the standalone governance family is not enabled.

07Caller-supplied data

Investment, Wealth & Planning

Portfolio, wealth-health, and goal calculations based on data submitted by the partner.

08LLM-assisted

CapLLM Financial AI

Financial language-model capabilities with CapLLM as the primary provider and Claude as the secondary provider when configured.

Capulse is a B2B beta platform. Specific endpoints and data sources depend on company verification, product entitlement, subscription or sandbox access, key scopes, and required consent. Review the API documentation or interactive reference for endpoint-level details. Account and credit data is partner-supplied; consent records are partner-attested, not independently verified by Capulse.

All endpoints are mounted under /api/v1 and return JSON. Caller-supplied analytical POST requests remain stateless. Credit cases store derived summaries, not the raw request figures. Payment records are deliberately stored as normalized partner submissions for status lookup and reconciliation; all records, rules, jobs, and exceptions are scoped to the partner company. Customer-linked payment operations require partner-attested authorization matching the customer reference, purpose, transaction category, operation, and evidence reference. Capulse enforces the recorded scope but does not capture or independently verify end-customer consent. The OpenAPI specification contains the complete endpoint and response contract.

Beta and example notice. Endpoint access, source coverage and freshness vary by company and operation. All static values in examples are illustrative, not live market output. Preserve documented schema fields when integrating. If an actual schema includes BUY or SELL, interpret it as an analytical classification—not personalized investment advice or an instruction to trade.

Registration does not guarantee sandbox access. Access requires separate company review and provisioning. Only if an approved company is provisioned does the existing policy apply: one shared, one-time allowance of 1,000 sandbox requests for 30 days, sandbox-only. It is not a production quota or an access guarantee.

GEThttps://api.capulse.tech/api/v1/docs

Example: send a trading plan for position sizing

curl -X POST https://api.capulse.tech/api/v1/trading/position-size \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "BUY",
    "entry_price": 100,
    "stop_loss": 95,
    "capital": 10000,
    "risk_percent": 2
  }'

This request illustrates the documented request shape. Console examples are static unless specifically identified otherwise; sample values are not live output.

Financial accounts — submit and retrieve snapshots

Use an opaque customer reference owned by your system; do not send names, email addresses, phone numbers, or government identifiers. Data is isolated to the authenticated partner workspace. Use a server-side API key with privacy:manage to record or check consent, financial_accounts:write to submit snapshots, and financial_accounts:read to read or aggregate data. Supply the same purpose_code on every data read and snapshot write. Account deletion remains available after consent withdrawal. Currency values are stored as decimal strings, and totals are grouped by currency without FX conversion.

Partner attestation is not independent verification. Your organization must obtain valid authorization and retain its evidence. Capulse records your attestation and enforces the scope, expiry, and withdrawal state you submit; it does not verify the customer's identity, notice, or consent evidence.

1. Record customer authorization

Create a consent record before submitting or retrieving account data. Supported categories are account, balance, transaction, and holding; supported operations are read, write, and aggregate. Use a partner-controlled reference to the consent evidence; do not upload identity documents or raw consent evidence here.

POST/api/v1/privacy/consents
curl -X POST https://api.capulse.tech/api/v1/privacy/consents \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_attestation": true,
    "customer_ref": "customer_8f3a",
    "purpose_code": "portfolio_service",
    "data_categories": ["account", "balance", "transaction", "holding"],
    "operations": ["read", "write", "aggregate"],
    "consent_version": "notice-v1",
    "capture_method": "partner_system",
    "evidence_reference": "consent-record-4582",
    "expires_at": "2027-10-23T00:00:00Z"
  }'

Use GET /api/v1/privacy/consents?customer_ref=... to review records and POST /api/v1/privacy/consents/{consent_id}/withdraw to withdraw one. That grant no longer authorizes future operations; another active grant may still cover the same purpose and data. Withdrawal does not delete stored data.

POST/api/v1/accounts
curl -X POST https://api.capulse.tech/api/v1/accounts \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ref": "customer_8f3a",
    "purpose_code": "portfolio_service",
    "authorization_reference": "consent-record-4582",
    "source": "partner_broker",
    "account": {
      "external_account_id": "broker-account-23",
      "institution_name": "Example Broker",
      "account_type": "brokerage",
      "currency": "INR",
      "masked_identifier": "****8721"
    },
    "balances": [
      {"balance_type": "current", "amount": "25000.00", "currency": "INR",
       "observed_at": "2026-10-23T10:00:00Z"}
    ],
    "transactions": [
      {"external_transaction_id": "trade-781", "amount": "1200.00",
       "currency": "INR", "direction": "debit", "transaction_type": "expense",
       "transaction_date": "2026-10-22", "status": "posted"}
    ],
    "holdings": [
      {"external_holding_id": "holding-rel-1", "symbol": "RELIANCE",
       "asset_class": "equity", "quantity": "2", "unit_cost": "2800",
       "current_price": "2900", "currency": "INR"}
    ]
  }'

Send the same external account and transaction IDs to update the corresponding records safely. Re-submit the holdings array as the latest complete holdings snapshot; earlier holdings for that account are replaced.

GET/api/v1/accounts?customer_ref=customer_8f3a&purpose_code=portfolio_service

For each account, retrieve /accounts/{account_id}/balances, /accounts/{account_id}/transactions?customer_ref=...&purpose_code=...&from=YYYY-MM-DD&to=YYYY-MM-DD, and /accounts/{account_id}/holdings?customer_ref=...&purpose_code=.... Account IDs are workspace-scoped and every account read requires the matching customer reference and purpose code.

Portfolio, net worth & cash flow

GET /api/v1/assets/portfolio?customer_ref=...&purpose_code=... and GET /api/v1/assets/net-worth?customer_ref=...&purpose_code=... aggregate the latest submitted balances and priced holdings by currency. Loan and credit-card balances count as liabilities; bank balances and holdings count as assets. No exchange rate is applied. Cash flow requires customer_ref, from and to date parameters; posted transfers are excluded from the net flow.

GET/api/v1/assets/cash-flow?customer_ref=customer_8f3a&purpose_code=portfolio_service&from=2026-10-01&to=2026-10-31

DELETE /api/v1/accounts/{account_id}?customer_ref=... deletes that account and its associated balances, transactions, and holdings from the partner workspace. Deletion remains available after consent withdrawal so partners can honor erasure requests.

Authentication

Every protected endpoint requires a Bearer token in the Authorization header:

curl https://api.capulse.tech/api/v1/me \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY"

The existing API contract distinguishes sandbox (tc_test_) and production (tc_live_) key formats. A format or workspace control does not mean production access is currently offered or enabled. Any key provisioning depends on company review, configuration and applicable terms. Keep credentials on your server, never in browser or mobile code. A raw key is shown once at creation; if it is lost or exposed, rotate or revoke it in the workspace.

Access & provisioning

Start by discussing an early-access partnership and sharing your company use case. A form submission or account registration does not approve API or sandbox access. Selected testing is considered separately, after company review and provisioning. If your organization already has an approved workspace, sign in to the API workspace to use its existing functionality and review applicable limits.

Sandbox vs production. The existing workspace may expose separate environment controls; this does not imply a general production offering. Use testing functionality only when your company has been provisioned for it.

Errors & rate limits

Errors return a JSON body with a stable code string:

{
  "success": false,
  "request_id": "req_example",
  "timestamp": "2026-10-21T10:00:00Z",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is invalid."
  },
  "metadata": {
    "freshness": "UNAVAILABLE",
    "quality": "UNAVAILABLE",
    "output_type": "ERROR"
  },
  "model": {
    "engine": "capulse",
    "provider": "not_called"
  },
  "disclaimer": "Research and education, not investment advice."
}
HTTPCodeMeaning
400INVALID_REQUEST / INVALID_INDEX / INVALID_SYMBOLMalformed input
401NO_API_KEY / INVALID_API_KEYMissing or bad bearer token
403FORBIDDEN / INSUFFICIENT_SCOPE / PRODUCT_NOT_ENTITLEDAdmin-only endpoint, key scope mismatch, or company does not have access to the requested product family.
404NOT_FOUNDSubscription does not exist
429RATE_LIMITED / QUOTA_EXCEEDED / TRIAL_EXHAUSTED / TRIAL_EXPIREDCompany or key rate limit reached, the monthly allowance is exhausted, or the one-time sandbox trial is used or expired. Usage and audit endpoints remain available.
500 / 503ENGINE_ERROR / DATA_UNAVAILABLEEngine or approved data provider unavailable. Retry with bounded backoff; do not retry state-changing subscription requests blindly.

Each API response exposes X-Capulse-Quota-Limit, X-Capulse-Quota-Used, X-Capulse-Quota-Remaining, X-Capulse-Quota-Reset and X-Capulse-Quota-Status headers. Monthly allowances are assigned by organization type and shared across its environments and keys. The GET /api/v1/usage response reports the allowance, use, remaining requests and next reset. Its family_totals breakdown shows usage by product family, while product_entitlements lists all eight catalog families with their current availability and company enablement state. Historical requests from before family-level metering appear as legacy. Requests denied with PRODUCT_NOT_ENTITLED are logged but do not consume quota or the sandbox trial. Requests beyond the allowance are rejected with QUOTA_EXCEEDED; Capulse does not apply automatic overage charges. Only where an approved company is separately provisioned does the existing policy provide one shared 1,000-request sandbox trial. Its 30-day period starts on the first sandbox request; client errors count, while server errors and rate-limit responses do not. Trial usage is reported in the free_trial object from GET /api/v1/usage and the X-Capulse-Trial-* response headers.


F&O — request-time analysis contract

GET/api/v1/fno/signals/live?index=NIFTY

The endpoint returns request-time analysis fields for supported indices: direction, confidence, entry mode, ATM strike, option trade candidates, scoring detail and source context. Access requires the F&O product to be enabled for your company. Values depend on source availability and freshness; the example below is illustrative.

Query parameters

NameRequiredDescription
indexNo; defaults to NIFTYOne of NIFTY, BANKNIFTY, FINNIFTY, SENSEX

Actual data availability and freshness depend on the configured source and endpoint status. The sample response below is static and illustrative, not current market output.

Example

curl "https://api.capulse.tech/api/v1/fno/signals/live?index=NIFTY" \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY"
{
  "success": true,
  "index":   "NIFTY",
  "analysis": {
    "trade_direction": "BULLISH",
    "confidence":      82,
    "confidence_grade":"Strong",
    "entry_mode":      "BREAKOUT",
    "atm_strike":      22500,
    "spot_price":      22487.4,
    "trades": [
      { "type": "ATM", "strike": 22500, "ltp": 118.4, "risk": "MEDIUM" },
      { "type": "OTM", "strike": 22550, "ltp":  78.1, "risk": "HIGH" },
      { "type": "ITM", "strike": 22400, "ltp": 175.6, "risk": "LOW" }
    ],
    "layers": { "direction": {...}, "strength": {...}, "filters": {...} },
    "data_source": "broker"
  }
}

F&O — history

GET/api/v1/fno/signals/history?index=NIFTY&days=7

Returns historical signal records when available for the requested scope. The endpoint path and schema do not promise continuous monitoring, scan cadence, market-hour availability or complete history.

NameDefaultRange
indexNIFTYRequired, one of the four
days71–30
limit1001–500

I-Score — single stock

GET/api/v1/iscore/<symbol>?asset_type=stocks

The i-Score response includes components, confidence, analytical classification and score factors. Supported instruments, source fields and freshness vary; access depends on company provisioning. The example below is illustrative.

curl "https://api.capulse.tech/api/v1/iscore/RELIANCE" \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY"
{
  "success": true,
  "symbol":  "RELIANCE",
  "result": {
    "iscore":         72.4,
    "confidence":     0.81,
    "recommendation": "BUY",
    "summary":        "Strong fundamentals, improving trend, low risk regime.",
    "components": {
      "qualitative":    { "score": 70, "weight": 15, ... },
      "quantitative":   { "score": 78, "weight": 35, ... },
      "trend":          { "score": 75, "weight": 20, ... },
      "risk":           { "score": 65, "weight": 15, ... },
      "search":         { "score": 60, "weight": 10, ... },
      "market_context": { "score": 55, "weight":  5, ... }
    },
    "score_factors": [
      "Wilder RSI(14) = 62 — bullish bias",
      "Price > 50-EMA, EMA stack rising",
      "Drawdown 6% — well below 20% penalty band"
    ]
  }
}

I-Score — batch

POST/api/v1/iscore/batch

Up to 25 symbols per call.

curl -X POST https://api.capulse.tech/api/v1/iscore/batch \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "symbols": ["RELIANCE","TCS","HDFCBANK","INFY"] }'

Subscriptions — push alerts

The contract describes subscription and webhook behavior for configured testing. Whether a subscription or delivery capability is enabled depends on endpoint status, source availability and company provisioning; event timing is not guaranteed.

GET/api/v1/subscriptions
POST/api/v1/subscriptions
DELETE/api/v1/subscriptions/<id>

Body

FieldTypeDescription
enginestringfno or iscore
symbolstringIndex (NIFTY, BANKNIFTY, …) for F&O; NSE stock symbol for I-Score
min_confidenceintOnly fire when score ≥ this. Default 75 (F&O) / 60 (I-Score)
delta_thresholdintI-Score only. Re-fire when score moves by this many points. Default 5
channelsarrayCurrently ["webhook"]. Email coming soon
is_activeboolPause without deleting
curl -X POST https://api.capulse.tech/api/v1/subscriptions \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine":         "fno",
    "symbol":         "NIFTY",
    "min_confidence": 75
  }'
POST is idempotent on (engine, symbol) — repeating with new thresholds updates the existing subscription instead of erroring.

Portfolio risk analysis

POST/api/v1/portfolio/analyze

Stateless risk analysis on a list of holdings — up to 50 per request. Pass any portfolio (your customer's or a model book) and get back a risk score, concentration metrics, sector/asset allocation, a heat map and prescriptive recommendations. Nothing is stored on our side.

curl -X POST https://api.capulse.tech/api/v1/portfolio/analyze \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "INR",
    "holdings": [
      {"symbol":"RELIANCE","qty":50,"avg_price":2400,"current_price":2890,
       "sector":"Energy","asset_class":"Equities"},
      {"symbol":"TCS","qty":20,"avg_price":3500,"current_price":3850,
       "sector":"IT","asset_class":"Equities"},
      {"symbol":"GOLDBEES","qty":200,"avg_price":55,"current_price":62,
       "sector":"ETF","asset_class":"Gold"}
    ]
  }'

Holding fields

FieldTypeRequiredNotes
symbolstringyesTrading symbol (case-insensitive)
qtynumberyesQuantity held, > 0
avg_pricenumberyesAverage buy price
current_pricenumbernoDefaults to avg_price if omitted
sectorstringnoUsed for sector allocation
asset_classstringnoOne of Equities, Mutual Funds, FD, Gold, Crypto, FNO, Bonds, Insurance, Real Estate. Default Equities

Response

{
  "success": true,
  "summary": {
    "currency":            "INR",
    "holdings_count":      3,
    "sector_count":        3,
    "total_invested":      141000.00,
    "total_current_value": 233900.00,
    "total_pnl":           92900.00,
    "total_pnl_pct":       65.89,
    "risk_score":          72.4,         // 0–100, higher = riskier
    "risk_grade":          "Aggressive", // Conservative | Balanced | Aggressive | Highly Aggressive
    "concentration_hhi":   3712.5,       // Herfindahl index, >2500 = concentrated
    "top_holding_pct":     61.78,
    "top_holding_symbol":  "RELIANCE",
    "warnings_count":      2
  },
  "details": {
    "holdings":          [ ... per-holding metrics ... ],
    "sector_allocation": [ {"name":"Energy","weight_pct":61.78, ...}, ... ],
    "asset_allocation":  [ {"name":"Equities","weight_pct":94.7, ...}, ... ],
    "risk_heatmap":      [ {"symbol":"RELIANCE","weight_pct":61.8,"risk_score":8, ...}, ... ],
    "warnings":          [ {"type":"concentration","severity":"high","message":"..."} ],
    "recommendations":   [ "Trim single-stock positions above 25% ...", ... ]
  }
}
Limit: 50 holdings per request. Larger books should be split client-side (e.g. by account or asset class) and the summaries combined.

Behavioural analysis

POST/api/v1/behaviour/analyze

Run our trading-psychology engine on a list of trades — up to 100 per request. Detects 8 patterns (overtrading, revenge trading, tilt, loss aversion, profit-booking bias, poor timing, position-sizing inconsistency, symbol concentration), produces a 0–100 Discipline Score, headline stats and prescriptive coaching.

curl -X POST https://api.capulse.tech/api/v1/behaviour/analyze \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lookback": "Last 30 days",
    "trades": [
      {"symbol":"NIFTY","side":"BUY","qty":75,"price":120,
       "entry_time":"2026-04-12T09:18:00","exit_time":"2026-04-12T09:25:00",
       "pnl":-450,"segment":"FNO"},
      {"symbol":"NIFTY","side":"BUY","qty":150,"price":110,
       "entry_time":"2026-04-12T09:35:00","exit_time":"2026-04-12T09:50:00",
       "pnl":-1200,"segment":"FNO"}
    ]
  }'

Trade fields

FieldTypeRequiredNotes
symbolstringyesTrading symbol
sidestringyesBUY or SELL
qtynumberyesFilled quantity, > 0
pricenumberyesAverage fill price
entry_timestringyesISO 8601 timestamp
exit_timestringnoISO 8601, required for hold-time analysis
pnlnumbernoRealised P&L. Required for win-rate, loss aversion, revenge & tilt detection
segmentstringnoEQ, FNO, MCX. Default EQ
strategystringnoFree-form tag, echoed in response

Response

{
  "success": true,
  "summary": {
    "lookback":           "Last 30 days",
    "discipline_score":   62,                  // 0–100
    "discipline_grade":   "Fair",              // Excellent | Good | Fair | Poor | Critical
    "total_trades":       6,
    "closed_trades":      6,
    "win_rate_pct":       33.33,
    "profit_factor":      0.94,
    "total_pnl":          -650.00,
    "patterns_detected":  3,
    "top_concern":        "revenge_trading"
  },
  "details": {
    "patterns": [
      {"pattern":"revenge_trading","detected":true,"severity":"medium",
       "evidence":"2 trade(s) entered within 30m of a loss with equal or larger size.",
       "metric":{"count":2}},
      {"pattern":"tilt","detected":true,"severity":"medium", ...},
      {"pattern":"poor_timing","detected":true,"severity":"medium", ...},
      ...
    ],
    "stats": {
      "win_rate_pct": 33.33, "avg_win": 1050, "avg_loss": -687.5,
      "profit_factor": 0.94, "segment_breakdown":{"FNO":6},
      "top_5_symbols":[["NIFTY",5],["BANKNIFTY",1]],
      "hourly_distribution":{"9":3,"10":1,"11":1,"15":1}
    },
    "recommendations": [
      "Enforce a 30-minute cool-down after any losing trade before re-entering.",
      "Use fixed position sizing — never increase size after a loss.",
      "Avoid the first and last 15 minutes of the session — wait for stable price action."
    ]
  }
}
Limit: 100 trades per request. For longer histories, send each lookback window (e.g. month-by-month) and aggregate the discipline trend on your side.

Credit, lending & risk APIs

These deterministic APIs analyze partner-supplied values. They do not connect to a credit bureau or bank, create a regulated credit score, determine fraud, estimate a probability of default, or approve or decline an application. The partner remains responsible for policy, verification, adverse-action requirements, and all lending decisions.

MethodEndpointPurpose
GET/api/v1/credit/modelsList available rule-based metrics and limitations
POST/api/v1/credit/profilesCreate a consent-bound case and store derived ratios only
GET/api/v1/credit/profiles/{case_id}Retrieve a case summary after rechecking authorization
POST/api/v1/credit/cash-flow-analysisCash-flow margin, volatility, and debt-service coverage
POST/api/v1/credit/debt-burdenDebt-to-income and residual-income metrics
POST/api/v1/credit/affordabilityAssumption-based amortizing-principal estimate
POST/api/v1/credit/sme-analysisSME statement ratios from supplied values
POST/api/v1/credit/risk-indicatorsTransparent threshold flags; no composite credit score
POST/api/v1/credit/anomaly-detectionStatistical outlier flag for a supplied metric series
POST/api/v1/credit/early-warningThreshold checks on supplied monitoring signals
POST/api/v1/credit/reviewsCreate a partner human-review task
GET / PATCH/api/v1/credit/reviews/{review_id}Read task status or record the partner's outcome
Access and authorization. A verified, entitled partner company and an eligible subscription or sandbox trial are required. Restricted keys need credit:analyze for analysis and credit:review for review operations. Each customer-linked request must match an active partner-attested consent for the same customer reference, purpose, data category, and evidence reference. Creating or updating a review also requires write authorization; reading one requires read. These calls are metered to the company's credit_risk family.

Example: calculate debt burden

curl -X POST https://api.capulse.tech/api/v1/credit/debt-burden \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ref": "opaque-customer-381",
    "purpose_code": "lending_preassessment",
    "evidence_reference": "partner-consent-381",
    "monthly_income": 120000,
    "monthly_debt_payments": 30000,
    "currency": "INR"
  }'

Record consent through POST /api/v1/privacy/consents first, with the matching evidence reference, the income and debt categories, and the aggregate operation. Response examples and field constraints are in the interactive OpenAPI reference.


Payments, banking & reconciliation APIs

This family is in controlled Beta. Partners import their own normalized transaction, settlement, and settlement-line data; Capulse stores it within the partner company for status lookup and reconciliation. There is no bank or payment-provider connection, no live provider status query, and no ability to initiate, hold, or transfer funds. Send opaque customer references and tokenized external references only—never PAN, CVV, full account numbers, bank credentials, or direct customer identifiers.

Access and metering. Requests require an approved company, an active subscription or eligible sandbox trial, and company entitlement to this family. Restricted keys use payments:read, payments:write, reconciliation:read, or reconciliation:manage. Customer-linked reads/imports require a matching partner-attested authorization for the transaction category, exact purpose, operation, and evidence reference. Every API call—including an idempotent retry—is metered to the company's payments_reconciliation family.
MethodEndpointPurpose
POST/api/v1/payments/transactions/importImport or revise up to 500 partner-supplied records
GET/api/v1/payments/transactionsList imported records for a customer and purpose
GET/api/v1/payments/transactions/{record_id}Read one imported record
GET/api/v1/payments/status/{reference}Look up status from imported records only
POST/api/v1/reconciliation/rulesCreate an immutable, versioned match rule
GET/api/v1/reconciliation/rulesList active company rules
POST/api/v1/reconciliation/jobsReconcile two imported sources using a saved rule
GET/api/v1/reconciliation/jobs/{job_id}Read job status and summary
GET/api/v1/reconciliation/jobs/{job_id}/resultsRead matches, explanations, and exceptions
GET/api/v1/reconciliation/exceptionsList open or resolved exceptions
POST/api/v1/reconciliation/exceptions/{exception_id}/resolveRecord a partner human-review outcome
GET/api/v1/reconciliation/reportsSummarize job outcomes for a customer and period
POST/api/v1/reconciliation/exportsExport one job's results as JSON

1. Record partner authorization

Before importing, looking up, or reconciling customer-linked transaction data, record the partner's authorization. Keep the evidence in your own system and send only its reference.

curl -X POST https://api.capulse.tech/api/v1/privacy/consents \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_attestation": true,
    "customer_ref": "merchant-customer-381",
    "purpose_code": "payment_reconciliation",
    "data_categories": ["transaction"],
    "operations": ["read", "write", "aggregate"],
    "consent_version": "payments-notice-v1",
    "capture_method": "partner_system",
    "evidence_reference": "consent-record-381"
  }'

2. Import tokenized payment records

Include a stable source record ID and increasing source_revision when correcting an existing record. Every write requires Idempotency-Key: an exact retry returns the original response, while changing the body under the same key returns 409.

curl -X POST https://api.capulse.tech/api/v1/payments/transactions/import \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-settlement-2026-10-23" \
  -d '{
    "customer_ref": "merchant-customer-381",
    "purpose_code": "payment_reconciliation",
    "authorization_reference": "consent-record-381",
    "source_system": "processor",
    "records": [{
      "external_record_id": "settlement-line-728",
      "record_type": "settlement_line",
      "external_reference": "processor-txn-728",
      "invoice_reference": "invoice-728",
      "transaction_reference": "merchant-txn-728",
      "settlement_reference": "settlement-982",
      "amount": "1000.00",
      "fee_amount": "10.00",
      "net_amount": "990.00",
      "currency": "INR",
      "status": "settled",
      "direction": "not_applicable",
      "occurred_at": "2026-10-23T10:00:00Z",
      "source_revision": 1
    }]
  }'

3. Create a matching rule and run reconciliation

Rules are versioned. Auto-finalization defaults to off. Exact reference and configured amount/date matches are explained; ambiguous or conflicting rows are sent to human review. Jobs process at most 500 records per source.

curl -X POST https://api.capulse.tech/api/v1/reconciliation/rules \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rule-invoice-settlement-v1" \
  -d '{
    "rule_name": "invoice-settlement",
    "matching_fields": ["transaction_reference", "invoice_reference", "settlement_reference"],
    "amount_tolerance": "10.00",
    "date_window_days": 2,
    "auto_finalize_exact": false,
    "auto_finalize_composite": false
  }'

curl -X POST https://api.capulse.tech/api/v1/reconciliation/jobs \
  -H "Authorization: Bearer tc_test_YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reconcile-customer-381-2026-10" \
  -d '{
    "customer_ref": "merchant-customer-381",
    "purpose_code": "payment_reconciliation",
    "authorization_reference": "consent-record-381",
    "left_source": "merchant-ledger",
    "right_source": "processor",
    "rule_id": 1,
    "from": "2026-10-01",
    "to": "2026-10-31"
  }'

4. Review and export results

Use GET /api/v1/payments/transactions, /payments/status/{reference}, /reconciliation/jobs/{job_id}, /reconciliation/jobs/{job_id}/results, /reconciliation/exceptions, and /reconciliation/reports with customer_ref, purpose_code, and the matching authorization_reference. Resolve an exception with POST /api/v1/reconciliation/exceptions/{exception_id}/resolve and the original evidence reference; reviewing a potential match closes both linked exception entries and records the partner's decision, but never alters payment status. Use POST /api/v1/reconciliation/exports for an idempotent JSON export. The full parameter and response schemas are in the interactive OpenAPI reference.


Webhook payloads

F&O signal

POST https://your-platform.com/webhooks/tc
Content-Type: application/json
X-TC-Event: fno.signal
X-TC-Signature: sha256=<hex hmac of body>

{
  "engine":          "fno",
  "event":           "TRADE_TRIGGER",
  "index":           "NIFTY",
  "symbol":          "NIFTY",
  "score":           82,
  "confidence":      82,
  "tier":            "HIGH",
  "trade_direction": "BULLISH",
  "entry_mode":      "BREAKOUT",
  "atm_strike":      22500,
  "entry_price":     120,
  "sl":              105,
  "target":          145,
  "trade_code":      "NIFTY-2026-05-03-001",
  "data_source":     "broker",
  "subscription_id": 17,
  "timestamp":       "2026-05-03T05:21:00Z"
}

Tier maps directly to confidence: HIGH ≥ 75, REGULAR 60–74, AGGRESSIVE 50–59.

I-Score update

Fires on new subscription, recommendation tier change, or score delta ≥ delta_threshold:

POST https://your-platform.com/webhooks/tc
X-TC-Event: iscore.update

{
  "engine":         "iscore",
  "symbol":         "RELIANCE",
  "score":          72.4,
  "confidence":     0.81,
  "tier":           "BUY",
  "recommendation": "BUY",
  "summary":        "...",
  "components":     { ... },
  "subscription_id": 12,
  "timestamp":       "2026-05-03T05:30:00Z"
}

Verifying signatures

Every webhook carries an HMAC-SHA256 of the raw request body keyed by your webhook_secret. Always verify before trusting the payload.

import hmac, hashlib

def verify(req_body: bytes, header_sig: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), req_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_sig or "")
Respond with 2xx within 5 seconds. We retry once on 5xx; 4xx is treated as permanent rejection. All attempts are logged.

Delivery log

GET/api/v1/alerts?limit=50&engine=fno

Returns the last n webhook attempts with HTTP status, error and the exact payload sent. Filter by engine.


Changelog

This reference documents current endpoint contracts. Company access, supported inputs and source availability can vary by endpoint and partner agreement. A path in the reference is not a substitute for confirming that the endpoint is enabled for your company.

Support

For an early-access discussion, share your use case through the partnership enquiry form. For other questions: partners@capulse.tech. For platform issues see the Help Center or contact our team.