Filing Preference

Retrieve the GST return filing preferences (monthly vs quarterly) and filing history for a GSTIN in a given financial year. Returns filing status, ARN numbers, filing dates, and modes for each return type.

Endpoint

GET /vas-api/v1/filing-preference

Authentication

Requires OAuth2 Bearer token. Get your credentials →

Request

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer YOUR_ACCESS_TOKEN

Query parameters

Parameter	Type	Required	Description	Example
gstin	string	Yes	15-character GSTIN	29ABCDE1234F1Z5
financialYear	string	Yes	Financial year (YYYY-YYYY)	2024-2025

Example request

curl

curl -X GET "https://api.api4business.com/vas-api/v1/filing-preference?gstin=29ABCDE1234F1Z5&financialYear=2024-2025" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

response = requests.get(
  "https://api.api4business.com/vas-api/v1/filing-preference",
  params={"gstin": "29ABCDE1234F1Z5", "financialYear": "2024-2025"},
  headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)
print(response.json())

Node.js

const url = new URL("https://api.api4business.com/vas-api/v1/filing-preference");
url.searchParams.set("gstin", "29ABCDE1234F1Z5");
url.searchParams.set("financialYear", "2024-2025");
const response = await fetch(url, {
  headers: { "Authorization": "Bearer YOUR_ACCESS_TOKEN" }
});
console.log(await response.json());

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.api4business.com/vas-api/v1/filing-preference?gstin=29ABCDE1234F1Z5&financialYear=2024-2025"))
  .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
  .GET().build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

Success (200)

The body is an array of filing records.

Field	Type	Description
ok	boolean	true if successful
responseCode	integer	HTTP status code
message	string	Status message
body[].gstin	string	The GSTIN queried
body[].financialYear	string	Financial year
body[].gstReturnType	string	Return type (GSTR1, GSTR3B, etc.)
body[].filingPeriod	string	Filing period (MMYYYY format)
body[].filingDate	string	Date filed (YYYY-MM-DD)
body[].filingStatus	string	Filed or Not Filed
body[].filingValidity	string	Filing validity (Y = valid, N = invalid)
body[].filingMode	string	ONLINE or OFFLINE
body[].arnNumber	string	Acknowledgement Reference Number
body[].lastSynced	integer	Last sync timestamp from GSTN portal

Example response

{
  "ok": true,
  "responseCode": 200,
  "message": "Transmission OK",
  "body": [
    {
      "gstin": "29ABCDE1234F1Z5",
      "financialYear": "2024-2025",
      "gstReturnType": "GSTR1",
      "filingPeriod": "012024",
      "filingDate": "2024-03-09",
      "filingStatus": "Filed",
      "filingValidity": "Y",
      "filingMode": "ONLINE",
      "arnNumber": "AA290124012345A",
      "lastSynced": 1725349448808
    }
  ]
}

Response headers

Header	Description
x-request-id	Unique request identifier — log this for debugging and support

Error responses

Status	Error Code	Message	Resolution
400	400	Invalid GSTIN	Check 15-character GSTIN format
400	400	Invalid Request	Verify both gstin and financialYear parameters are present
401	401	Invalid Credentials	Access token expired — request a new one
429	429	Quota Violation	Rate limit exceeded — retry with backoff
500	500	Internal Server Error	Retry after delay
503	503	Service Not Available	GSTN service temporarily down — retry

Related

• GST Filing Details — Detailed filing history
• GSTIN Status — Check registration status
• GST Overview