How to verify a GST number in Java

1. The call, with java.net.http.HttpClient

There is no Java SDK, and you do not need one — the API is a single GET request with one header.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://gstinapi.in/v1/gstin/33AAACC1206D1ZN"))
    .header("x-api-key", "gak_your_key_here")
    .timeout(Duration.ofSeconds(10))
    .GET()
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.statusCode());
System.out.println(response.body());   // JSON: legal_name, status, address ...

2. Validate the GSTIN offline first

A malformed GSTIN returns 400 and costs no credit, but the round trip is still wasted. Validate the check digit locally and typos never reach the network.

private static final String CODES = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";

public static boolean isValidGstin(String gstin) {
    String value = gstin == null ? "" : gstin.trim().toUpperCase();
    if (value.length() != 15) return false;

    int total = 0;
    for (int i = 0; i < 14; i++) {
        int index = CODES.indexOf(value.charAt(i));
        if (index < 0) return false;
        int product = index * (i % 2 == 1 ? 2 : 1);
        total += product / 36 + product % 36;
    }

    char expected = CODES.charAt((36 - total % 36) % 36);
    return value.charAt(14) == expected;
}

isValidGstin("33AAACC1206D1ZN"); // true
isValidGstin("33AAACC1206D1ZZ"); // false

This proves the GSTIN is well-formed. It cannot tell you whether the registration exists or is still active — only a live lookup does that, because registrations get cancelled.

3. Handle every status code

private static final Set<Integer> RETRYABLE = Set.of(429, 502);

/** Returns the JSON body, or null when the GSTIN is not registered. */
public static String verify(HttpClient client, String gstin, String apiKey)
        throws IOException, InterruptedException {
    int attempts = 3;

    for (int attempt = 0; attempt < attempts; attempt++) {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://gstinapi.in/v1/gstin/" + gstin))
            .header("x-api-key", apiKey)
            .timeout(Duration.ofSeconds(10))
            .GET()
            .build();

        HttpResponse<String> res =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        int status = res.statusCode();

        if (status == 200) return res.body();
        if (status == 404) return null;                  // not registered
        if (status == 402) throw new IllegalStateException("Out of credits");

        if (!RETRYABLE.contains(status))
            throw new IOException("Lookup failed with HTTP " + status);

        if (attempt < attempts - 1)
            Thread.sleep(1000L << attempt);              // 1s, then 2s
    }

    throw new IOException("GST provider unavailable after retries");
}

4. Wiring it into Spring Boot

Build one RestClient bean and inject it, rather than creating a client per call. Read the key from configuration or an environment variable, never from source. Spring maps the JSON onto a record for you, so no parsing code is needed.

@JsonIgnoreProperties(ignoreUnknown = true)
public record GstinResult(
    String gstin,
    @JsonProperty("legal_name") String legalName,
    @JsonProperty("trade_name") String tradeName,
    String status,
    @JsonProperty("taxpayer_type") String taxpayerType) {}

@Configuration
class GstinConfig {
    @Bean
    RestClient gstinClient(@Value("${gstin.api-key}") String apiKey) {
        return RestClient.builder()
            .baseUrl("https://gstinapi.in")
            .defaultHeader("x-api-key", apiKey)
            .build();
    }
}

// In a service:
GstinResult result = gstinClient.get()
    .uri("/v1/gstin/{gstin}", gstin)
    .retrieve()
    .body(GstinResult.class);

Frequently asked questions

The same guide in another language