Developers & API

Use TaxSense's engine from your own software: compute tax under both regimes, parse Form 16/AIS text, read the deadline calendar, manage saved profiles and receive signed webhooks. Base URL https://taxsense.mnbresearch.com/api/v1 · OpenAPI spec.

1. Authenticate

Create a key below (you need to be signed in). Send it as a bearer token from your server — never ship keys in browser or mobile apps.

curl https://taxsense.mnbresearch.com/api/v1/me \
  -H "Authorization: Bearer tsk_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Keys carry scopes; a request without the needed scope gets 403 forbidden.
Keys expire after 1–365 days (default 90). Rotate with an optional overlap of up to 24 h; revoke instantly.
Limits per key: free 30/min & 500/day; paid plans 120/min & 10,000/day. 429 responses include Retry-After.
Errors: { "error": { "code", "message" }, "requestId" }. Success: { "data": … }.

2. Compute tax

curl -X POST https://taxsense.mnbresearch.com/api/v1/compute \
  -H "Authorization: Bearer $TAXSENSE_KEY" -H "Content-Type: application/json" \
  -d '{"profile":{"age":32,"residentialStatus":"resident","houseProperties":[],
       "salary":{"grossSalary":1800000,"basicPlusDA":900000,"hraReceived":360000,
                 "rentPaid":420000,"isMetroCity":true,"professionalTax":2500},
       "deductions":{"section80C":150000,"section80D_selfFamily":25000},"taxesPaid":0}}'

Returns both regimes (taxable income, rebate, surcharge, cess, total tax, net payable), the recommended regime, the right ITR form and ranked saving moves.

3. Other endpoints

Endpoint	Scope	What it does
`POST /documents/parse`	`documents:parse`	Form 16 Part B / AIS text → amounts. Deterministic, no AI, nothing stored.
`GET /deadlines`	`deadlines:read`	Income-tax due dates (?from=YYYY-MM-DD&limit=).
`GET /profiles`	`profiles:read`	Your saved profiles, newest first (?limit=&cursor=).
`GET /profiles/{id}`	`profiles:read`	One profile with its full inputs.
`POST /profiles`	`profiles:write`	Create/update by label (idempotent per label).
`DELETE /profiles/{id}`	`profiles:write`	Delete a profile.
`GET\|POST /webhooks`	`webhooks:manage`	List / register endpoints.
`POST /webhooks/{id}/test`	`webhooks:manage`	Send a signed test event.
`GET /health`	`—`	Integration health check (no auth).

4. Webhooks

Events: profile.saved, profile.deleted, plan.activated (sent only after a verified payment). Payloads carry IDs and summaries, not full tax inputs. Retries: 0 s, 2 s, 8 s, then once more within 24 h. Redirects are not followed.

// Node — verify TaxSense-Signature: t=<unix>,v1=<hex>
import { createHmac, timingSafeEqual } from "crypto";
function verify(secret, rawBody, header) {
  const p = Object.fromEntries(header.split(",").map((x) => x.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const want = createHmac("sha256", secret).update(p.t + "." + rawBody).digest("hex");
  return want.length === p.v1.length && timingSafeEqual(Buffer.from(want), Buffer.from(p.v1));
}
// Use the TaxSense-Delivery header as an idempotency key.

5. Your keys & endpoints

Loading…

Computations are informational, not tax advice. API use is covered by our Terms and Privacy Policy. Questions: contact@mnbresearch.com.