Searches GSTN records to validate a GSTIN and retrieve taxpayer details.

Business Context

GSTIN is the primary identifier of a business under GST. This API is typically the first step in any GST workflow.

What this API does

• Validates whether a GSTIN is active and registered
• Retrieves taxpayer details such as legal name, trade name, and registration status
• Provides jurisdiction and registration metadata

Common Use Cases

• Merchant/vendor onboarding
• GST compliance validation
• KYC and identity verification

Important Notes

• Requires action=SEARCHGSTIN
• Response depends on GSTN availability
• Should be called before authentication or return APIs

Failure Scenarios

• Invalid GSTIN format → 400 error
• GSTIN not found → empty/failed response
• GSTN downtime → timeout or service unavailable

Fetches GST return filing status and available return periods from GSTN.

Business Context

GST returns must be filed periodically (monthly/quarterly), even if there is no business activity.

This API provides a summary view of return compliance, without fetching detailed data.

What this API does

• Lists available return types (GSTR-1, GSTR-3B, etc.)
• Shows filing status (Filed / Pending / Not Filed)
• Provides available tax periods for each return

Common Use Cases

• Compliance dashboards
• Pre-check before downloading returns
• Identifying missing filings

Important Notes

• Does NOT return invoice-level data
• Lightweight API for quick checks
• Should be used before calling return download APIs

Failure Scenarios

• Unauthorized access (if authentication required)
• Partial data due to GSTN latency

Fetches all GSTINs registered under a given PAN.

Business Context

A single PAN can have multiple GST registrations across different states or business verticals.

What this API does

• Maps PAN → multiple GSTINs
• Returns GST registrations across India linked to the PAN

Common Use Cases

• Business group discovery
• Risk profiling and underwriting
• Vendor ecosystem mapping

Important Notes

• PAN must be valid and active
• Response may include multiple GSTINs across states

Failure Scenarios

• Invalid PAN → error response
• No GSTIN mapped → empty list

Authenticates a GST taxpayer using an OTP-based consent mechanism.

GST Flow Context

GST data is sensitive and requires explicit taxpayer consent. Authentication is mandatory before accessing any taxpayer-specific data.

Authentication Flow

1. Initiate request with action=OTPREQUEST
2. OTP is sent to registered mobile/email of taxpayer
3. Submit OTP to complete authentication
4. Session is established for subsequent API calls

What this enables

• Access to taxpayer return data
• Return downloads (GSTR-1, GSTR-2A, GSTR-3B)
• Compliance and reconciliation workflows

Important Notes

• OTP is time-bound (typically valid for a few minutes)
• Session expires after inactivity
• app_key must be securely encrypted using GSTN public key

Failure Scenarios

• Incorrect OTP → authentication failure
• Expired OTP → retry required
• Invalid credentials → access denied

Retrieves summarized GST return data for an authenticated taxpayer.

Business Context

This API provides a consolidated view of a taxpayer’s GST compliance behavior.

What this API does

• Lists returns filed across periods
• Shows filing status and timestamps
• Indicates which returns are available for download

Common Use Cases

• Compliance monitoring
• Credit underwriting and risk assessment
• Financial reporting dashboards

Important Notes

• Requires successful authentication
• Data reflects GSTN system state and may have delays

Failure Scenarios

• Session expired → re-authentication required
• No returns filed → empty response

Fetches GSTR-1 return data containing outward supply (sales) details.

Business Context

GSTR-1 is the primary return where businesses report all sales transactions.

What this API includes

• B2B invoices
• B2C transactions
• Export invoices
• Credit/Debit notes and amendments

GST Flow Dependency

Data reported in GSTR-1 is used by buyers to generate their GSTR-2A/2B for ITC claims.

Use Cases

• Sales analytics
• Invoice reconciliation
• GST compliance checks

Important Notes

• High data volume possible
• Prefer file download API for bulk data

Fetches GSTR-2A auto-drafted return reflecting inward supplies (purchases).

Business Context

GSTR-2A is generated automatically based on suppliers’ GSTR-1 filings.

What this API includes

• Supplier invoices
• Input Tax Credit (ITC) eligibility data

Important Behavior

• Dynamic in nature (updates as suppliers file returns)
• Used for ITC reconciliation

Use Cases

• ITC validation and reconciliation
• Vendor compliance monitoring

Fetches GSTR-3B summary return used for tax declaration and payment.

Business Context

GSTR-3B is a mandatory summary return filed for each tax period.

What this API includes

• Total tax liability
• Input Tax Credit (ITC) claimed
• Net tax payable

GST Rule

Must be filed even if there is no business activity in the period.

Use Cases

• Financial analysis
• Tax liability tracking
• Compliance monitoring

Important Notes

• Does not contain invoice-level data

Fetches returns filed under the Composition Scheme.

Business Context

Composition scheme is for small taxpayers who pay tax at a fixed rate on turnover.

What this API includes

• Turnover details
• Tax payable summary

Important Notes

• Applicable only to composition taxpayers
• Not relevant for regular GST filers

Fetches GSTR-4 return table wise data filed by taxpayers under the Composition Scheme.

Business Context

GSTR-4 is an annual return that must be filed by taxpayers registered under the Composition Scheme. It provides a consolidated view of turnover, inward supplies, and tax liability for the entire financial year.

What this API includes

• Annual aggregate turnover
• Inward supplies (including purchases from registered and unregistered suppliers)
• Tax liability and tax paid
• Summary of amendments, if any

GST Rule

• Filed once per financial year
• Mandatory for all composition taxpayers
• Late filing attracts penalties

Use Cases

• Annual compliance validation
• Financial and tax reporting
• Risk assessment and underwriting for small businesses

Important Notes

• Applicable only to composition taxpayers
• Data is annual (not periodic like GSTR-1 or GSTR-3B)
• Should be used for summary-level insights, not invoice-level analysis

Failure Scenarios

• Taxpayer not under composition scheme → error response
• Return not filed → empty or not available
• Session expired → re-authentication required

Fetches GSTR-4 return summary data for taxpayers registered under the Composition Scheme.

Business Context

GSTR-4 is an annual return filed by composition taxpayers, providing a summarized view of their business activity for the financial year. Unlike regular taxpayers, composition dealers do not file detailed monthly returns.

What this API provides

• Annual turnover summary
• Consolidated inward supplies (registered & unregistered)
• Tax liability and tax paid
• Basic amendment summaries (if applicable)

What this API does NOT provide

• Invoice-level details
• Counterparty-level breakdown
• Monthly or periodic granularity

GST Rule & Compliance

• Filed once per financial year
• Mandatory for all composition scheme taxpayers
• Non-filing or delayed filing may attract penalties and compliance flags

Use Cases

• Annual compliance verification
• High-level business turnover assessment
• Credit underwriting for small / composition businesses
• Risk profiling where detailed GST data is unavailable

Important Considerations

• Applicable only for composition taxpayers
• Data is aggregated annually, hence not suitable for trend or cashflow analysis
• Should be used in conjunction with banking or alternate data for deeper insights

Failure Scenarios

• Taxpayer not registered under composition scheme → appropriate error response
• Return not filed for the financial year → data unavailable / empty response
• Invalid GSTIN or request parameters → validation error
• Session expired or invalid token → re-authentication required

Downloads detailed GST return files using a GSTN-provided file path.

Business Context

GST returns like GSTR-1 and GSTR-2A contain large, invoice-level datasets required for reconciliation and analytics.

Supported Returns

• GSTR-1 → Outward supplies (sales invoices)
• GSTR-2A → Inward supplies (auto-drafted from suppliers)
• GSTR-3B → Summary return for tax liability

How it works

1. Retrieve file path from GSTN (via FILEDET API)
2. Use proxy_path to download the file
3. Process file (JSON/ZIP)

Important Notes

• Supports large payload streaming
• Avoid loading entire file into memory
• Recommended to use streaming or chunk processing

Failure Scenarios

• Invalid file path → 404
• Expired file reference → regenerate path
• Network interruption → retry supported