TaxBuddy API integration & ITR data export services

ITR filing & history API

Read a user's filed returns across AY 2021-22 onward: ITR type, gross total income, taxable income, refund due, acknowledgement number, filing mode (expert-assisted / DIY / AI) and e-verification timestamp. Use case: client onboarding for wealth managers that need verified income proof.

Form 16 & salary parser

Structured extraction of Part A / Part B Form 16 fields — employer TAN, gross salary, Section 10 exemptions, Chapter VI-A deductions, TDS deducted quarter-wise. Use case: salary verification for digital lending and BNPL underwriting.

AIS / TIS / 26AS sync

Paginated pull of AIS categories (SFT, TDS, TCS, GST turnover, interest, dividend, mutual fund redemptions) and reconciled TIS totals. Use case: cross-verification between brokerage CRMs and the Income Tax Department's own data.

Refund tracker webhook

Event-driven callbacks whenever refund status changes on the ITR e-filing portal (processed, partially adjusted, sent to bank, failed). Use case: in-app notifications and CA-client status dashboards replacing daily manual checks.

GST & TDS workflow

GSTIN validation, period-wise GSTR-1 invoice lists, GSTR-3B summary totals, TDS / TCS return filings and 24Q/26Q data. Use case: ERP-side reconciliation of input tax credit for SMEs and traders.

Tax notice response pipeline

Upload e-proceedings notices (u/s 143(1), 139(9), 148) via API, fetch AI-generated draft responses, and submit the final reply back to the ITR e-filing portal. Use case: notice-handling SaaS for mid-tier CA firms.

1. Digital lender income verification

A BNPL platform needs verified salary and tax liability before approving a ₹2 lakh limit. Under the customer's DPDP-compliant consent, the lender calls /taxbuddy/itr/history and /taxbuddy/form16/parsed, receives a normalized JSON of last three AYs' gross salary, net taxable income and TDS pattern, and feeds it into its scorecard — replacing PDF uploads.

2. Wealth manager onboarding

A wealth platform imports a prospect's Portfolio Doctor output plus AIS dividend + capital-gains entries at onboarding. The mapping to OpenFinance is straightforward: assets, holdings and realized gains become a single accountSummary object consumed by the PMS engine to propose a tax-efficient rebalance.

3. SME accounting & GST ITC

A mid-size trader syncs GSTR-1 invoices from TaxBuddy into its Tally / Zoho Books instance every 24 hours. Our integration maps GSTIN, HSN, CGST/SGST/IGST to the ERP schema and flags mismatched ITC versus GSTR-2B — an OpenData feed replacing spreadsheet reconciliations.

4. CA firm refund & notice dashboard

A chartered accountancy with 400 clients receives a webhook every time any client's ITR refund status advances or a 143(1) intimation arrives. Staff see a live board with PAN-level deltas, skipping repeat logins to the ITR e-filing portal. Maps to the OpenBanking pattern of event-streamed account state.

5. Embedded tax filing (white-label)

A neobank embeds a "File ITR" button inside its app. SSO hands the user to a TaxBuddy-backed flow; once filed, the neobank receives acknowledgement number, refund estimate and a downloadable ITR-V via a signed callback. Mirrors TaxBuddy's own white-label partner model, but integrated by our studio end-to-end.

1. Authorized login (OAuth + OTP)

POST /api/v1/taxbuddy/auth/login
Content-Type: application/json

{
  "pan": "ABCDE1234F",
  "mobile": "+91XXXXXXXXXX",
  "otp_token": "<otp_session_id>",
  "consent_artifact_id": "dpdp-2026-abc123"
}

200 OK
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rtk_9f...",
  "expires_in": 3600,
  "scopes": ["itr.read", "ais.read", "gst.read", "refund.track"]
}

2. ITR history query

GET /api/v1/taxbuddy/itr/history?pan=ABCDE1234F&from_ay=2022-23&to_ay=2025-26
Authorization: Bearer <ACCESS_TOKEN>

200 OK
{
  "pan": "ABCDE1234F",
  "returns": [
    {
      "assessment_year": "2025-26",
      "itr_form": "ITR-2",
      "ack_no": "4700XXXXXXXXXXXXXX",
      "filed_on": "2025-07-18T14:02:11+05:30",
      "gross_total_income": 1842500,
      "refund_due": 27840,
      "status": "PROCESSED",
      "mode": "AI_ASSISTED"
    }
  ],
  "next_cursor": null
}

3. Refund status webhook

POST https://partner.example.com/hooks/taxbuddy
X-TB-Signature: t=1714857600,v1=8f2a...

{
  "event": "refund.status_changed",
  "pan": "ABCDE1234F",
  "assessment_year": "2025-26",
  "ack_no": "4700XXXXXXXXXXXXXX",
  "old_status": "UNDER_PROCESSING",
  "new_status": "REFUND_SENT_TO_BANK",
  "amount": 27840,
  "as_of": "2026-04-15T09:12:04+05:30"
}

// Partner replies 2xx within 5s or we retry with exp-backoff.

4. Error & retry semantics

// Uniform error envelope
{
  "error": {
    "code": "TB_AIS_UNAVAILABLE",
    "http": 503,
    "retryable": true,
    "retry_after_ms": 15000,
    "trace_id": "01J...",
    "message": "Upstream AIS service timed out"
  }
}

// Classes:
// TB_AUTH_*     → refresh token, no retry
// TB_RATE_LIMIT → backoff per Retry-After
// TB_UPSTREAM_* → retry up to 3x with jitter
// TB_CONSENT_*  → re-collect DPDP consent artifact

Deliverables checklist

• OpenAPI 3.1 specification covering login, ITR, AIS, GST, refund, webhook
• Protocol and auth flow report (OTP, OAuth, session refresh, signing)
• Runnable source code (Python / Node.js / Go) with Docker compose
• Postman collection + automated test suite (pytest / Jest)
• DPDP / RBI / ITD-ERI compliance notes and retention policy template
• Operations guide: rate limits, retry, observability, trace IDs

Engagement models

• Source code delivery from $300 — you receive runnable API source code and full documentation; pay after delivery once you confirm acceptance tests pass.
• Pay-per-call API billing — call our hosted TaxBuddy integration endpoints and pay per call only; no upfront fee, ideal for teams validating a use case.

Typical modules shipped

• OAuth + OTP login and consent artefact handling
• ITR filing history, refund tracker, Form 16 parser
• AIS / TIS / 26AS sync and reconciliation
• GSTR-1 / 3B, TDS / TCS and ROC compliance exports
• Webhook dispatcher with HMAC signing and retry

About our studio

We are an independent technical services studio specializing in App interface integration and authorized API integration for fintech, tax and financial data apps. Our engineers have shipped OpenBanking / OpenFinance integrations for payment gateways, neobanks, wealth platforms and accounting SaaS across India, Southeast Asia and Europe.

• Hands-on expertise in protocol analysis, interface refactoring and Open Data integration
• Deep familiarity with Indian tax rails (ITD ERI APIs, DigiLocker, NSDL, GSTN)
• Third-party API integration, automated data scripting and delivery of interface documentation
• End-to-end pipeline: protocol analysis → build → validation → compliance → handover

Contact

To request a quote for a TaxBuddy integration or any other target app, share the app name and concrete requirements on our contact page.

Open contact page

Mention TaxBuddy, your target data types (e.g. ITR history, AIS, refund status) and preferred engagement model (source code or pay-per-call).

Engagement workflow

1. Scope confirmation — integration scenarios, required data types, target regions.
2. Protocol analysis & API design — 2–5 business days depending on complexity.
3. Build and internal validation — 3–8 business days, including test data against sample PANs.
4. Docs, samples, and test cases — 1–2 business days.
5. Typical first delivery: 5–15 business days; ITD / GSTN approvals may extend timelines.

FAQ

What do you need from me?

How long does delivery take?

How do you handle compliance?

Do you support non-Indian clients?