How to verify a GST number in Go

1. The call, with net/http

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

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

type GstinResult struct {
	Gstin        string `json:"gstin"`
	LegalName    string `json:"legal_name"`
	TradeName    string `json:"trade_name"`
	Status       string `json:"status"`
	TaxpayerType string `json:"taxpayer_type"`
	Address      string `json:"address"`
}

func main() {
	client := &http.Client{Timeout: 10 * time.Second}

	req, _ := http.NewRequest("GET", "https://gstinapi.in/v1/gstin/33AAACC1206D1ZN", nil)
	req.Header.Set("x-api-key", "gak_your_key_here")

	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result GstinResult
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		panic(err)
	}
	fmt.Println(result.LegalName, result.Status)
}

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.

const codes = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"

// IsValidGstin checks the format and check digit without calling the API.
func IsValidGstin(gstin string) bool {
	value := strings.ToUpper(strings.TrimSpace(gstin))
	if len(value) != 15 {
		return false
	}

	total := 0
	for i := 0; i < 14; i++ {
		index := strings.IndexByte(codes, value[i])
		if index < 0 {
			return false
		}
		product := index
		if i%2 == 1 {
			product = index * 2
		}
		total += product/36 + product%36
	}

	expected := codes[(36-total%36)%36]
	return value[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

var ErrOutOfCredits = errors.New("out of credits")

// Verify returns nil, nil when the GSTIN is not registered.
func Verify(client *http.Client, gstin, apiKey string) (*GstinResult, error) {
	const attempts = 3

	for attempt := 0; attempt < attempts; attempt++ {
		req, err := http.NewRequest("GET", "https://gstinapi.in/v1/gstin/"+gstin, nil)
		if err != nil {
			return nil, err
		}
		req.Header.Set("x-api-key", apiKey)

		resp, err := client.Do(req)
		if err != nil {
			return nil, err
		}

		switch resp.StatusCode {
		case http.StatusOK:
			var result GstinResult
			err := json.NewDecoder(resp.Body).Decode(&result)
			resp.Body.Close()
			return &result, err
		case http.StatusNotFound:
			resp.Body.Close()
			return nil, nil // not registered
		case http.StatusPaymentRequired:
			resp.Body.Close()
			return nil, ErrOutOfCredits
		case http.StatusTooManyRequests, http.StatusBadGateway:
			resp.Body.Close()
			if attempt < attempts-1 {
				time.Sleep(time.Second << attempt) // 1s, then 2s
			}
		default:
			resp.Body.Close()
			return nil, fmt.Errorf("lookup failed with HTTP %d", resp.StatusCode)
		}
	}

	return nil, errors.New("GST provider unavailable after retries")
}

4. Sharing one client across your service

Create one http.Client when the service starts and reuse it for every lookup. It is safe for concurrent use and keeps connections alive between calls, while a new client per request opens a new connection each time. Read the key from the environment, never from source.

type GstinService struct {
	client *http.Client
	apiKey string
}

func NewGstinService() *GstinService {
	return &GstinService{
		client: &http.Client{Timeout: 10 * time.Second},
		apiKey: os.Getenv("GSTIN_API_KEY"),
	}
}

func (s *GstinService) Verify(gstin string) (*GstinResult, error) {
	if !IsValidGstin(gstin) {
		return nil, errors.New("invalid GSTIN")
	}
	return Verify(s.client, gstin, s.apiKey)
}

Frequently asked questions

The same guide in another language