curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

GSTIN check (India) API

Check the state code, structure and check character of an Indian GSTIN and read the PAN inside it.

POST https://api.curatedapi.com/v1/calc/check/india-gstin

Checks a 15-character Goods and Services Tax Identification Number: a two-digit state code, the holder's ten-character PAN, an entity number, a default letter and a check character. The check character is worked out over the first 14 characters with the Luhn rule in base 36.

Formula

value each character 0 to 35 (digits, then A to Z); from the right, double every second value and add its base-36 digits; the check character makes the total a multiple of 36
  • The number is checked by arithmetic alone. Nothing is looked up, so a valid result means the number is well formed, not that the account, company or security exists.
  • Whether a GSTIN is registered and active is on the GST portal, which is not consulted.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
number required string The 15-character GSTIN. Spaces, dots, hyphens and slashes are ignored, and lower-case letters are read as upper case. At most 64 characters.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
validbooleanWhether the GSTIN passes every check.
normalizedstringThe number as it was checked: separators removed, letters in upper case.
problemstringWhat is wrong, when valid is false: CHARACTERS: a character that cannot appear in this kind of number; LENGTH: the wrong number of characters; COUNTRY: an unknown or unsupported country code; FORMAT: the right length but the wrong structure; CHECK_DIGIT: the check digit or check characters do not match the rest of the number.
messagestringThe result in a sentence, naming the rule that failed.
state_codestringThe first two digits.
statestringThe state or territory of the code.
kindstringA regular taxpayer's GSTIN (with a PAN inside) or another kind of registration.
panstringCharacters 3 to 12, for a regular taxpayer.
pan_holderstringThe kind of holder the PAN's fourth character stands for.
entity_numberstringCharacter 13: which of the holder's registrations in the state this is.
check_characterstringThe last character.
expected_check_characterstringThe check character the first 14 characters give.

Examples

A Maharashtra GSTIN

Requestcurl
curl https://api.curatedapi.com/v1/calc/check/india-gstin \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "27AAPFU0939F1ZV"
  }'
200 OKResponse
{
  "calculator": "check/india-gstin@1",
  "result": {
    "valid": true,
    "normalized": "27AAPFU0939F1ZV",
    "message": "A well-formed GSTIN registered in Maharashtra.",
    "state_code": "27",
    "state": "Maharashtra",
    "kind": "regular taxpayer",
    "pan": "AAPFU0939F",
    "pan_holder": "Firm or limited liability partnership",
    "entity_number": "1",
    "check_character": "V",
    "expected_check_character": "V"
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "number": "27AAPFU0939F1ZV"
  },
  "formula": "value each character 0 to 35 (digits, then A to Z); from the right, double every second value and add its base-36 digits; the check character makes the total a multiple of 36",
  "references": [
    {
      "title": "GST portal: search taxpayer by GSTIN",
      "url": "https://services.gst.gov.in/services/searchtp"
    },
    {
      "title": "Central Board of Indirect Taxes and Customs: GST state codes",
      "url": "https://cbic-gst.gov.in/"
    }
  ],
  "warnings": []
}

Last character wrong

Requestcurl
curl https://api.curatedapi.com/v1/calc/check/india-gstin \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "27AAPFU0939F1ZX"
  }'
200 OKResponse
{
  "calculator": "check/india-gstin@1",
  "result": {
    "valid": false,
    "normalized": "27AAPFU0939F1ZX",
    "problem": "CHECK_DIGIT",
    "message": "The last character is X, but the first 14 characters give V.",
    "state_code": "27",
    "state": "Maharashtra",
    "kind": "regular taxpayer",
    "pan": "AAPFU0939F",
    "pan_holder": "Firm or limited liability partnership",
    "entity_number": "1",
    "check_character": "X",
    "expected_check_character": "V"
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "number": "27AAPFU0939F1ZX"
  },
  "formula": "value each character 0 to 35 (digits, then A to Z); from the right, double every second value and add its base-36 digits; the check character makes the total a multiple of 36",
  "references": [
    {
      "title": "GST portal: search taxpayer by GSTIN",
      "url": "https://services.gst.gov.in/services/searchtp"
    },
    {
      "title": "Central Board of Indirect Taxes and Customs: GST state codes",
      "url": "https://cbic-gst.gov.in/"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.