Get GSTIN from PAN

Module ID

Name of the Module	Document Supported
module_kyb_gstin_from_pan	PAN for Business

Module Description

This module fetches the Goods and Services Tax Identification Number(GSTIN) against a business' Permanent Account Number(PAN) input.

Module Inputs

The following table provides the details of the parameter required for the module.

Parameter	Mandatory or Optional	Description
pan_id	Mandatory	The unique 10-digit alphanumeric PAN ID input. It should follow the 'CCCCCDDDDC' format 'C' represents a character and 'D' represents a digit.

Module Configurations

This module does not support any additional configurations.

Module Outputs

The following section provides the sample and the corresponding details of the various responses you can expect from the module.

Success Response

You will receive a success response in a format similar to the following code sample if the request is correct.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "status": 200,
    "data": {
      "code": "1002",
      "message": "Found 2 records",
      "results": [
        {
          "document_type": "GSTIN",
          "document_id": <ID number of GST document>,
          "status": "Active",
          "state": <state of registration>,
          "state_code": <2 digit numeral code>
        },
        {
          "document_type": "GSTIN",
          "document_id": <ID number of GST document>,
          "status": "Active",
          "state": <state of registration>,
          "state_code": <2 digit numeral code>
        }
      ]
    },
    "timestamp": 1664424036317
  }
}

Success Response Details

A success response from the module reflects the success status with a status code of 200 and a result object containing the response data with the following attributes-value pair.

Attributes	Description	Values Returned
message	This field provides a summary of the response. For a success response this field returns the count of the number of records found against the PAN input. For a failure response this field returns a summary of the reason for failure.	"Found [[number]] records" or "No matching GSTIN found for the given PAN".
document_type	It returns the type of the document fetched, which will always be GSTIN in this case.	"GSTIN".
document_id	It returns the unique ID number of the GST document.	"GSTIN".
status	It returns the validity of the document.	For example, "Active".
state	It returns the name of the state under which the GSTIN is registered.	N/A - It depends on the actual value in the input document.
state_code	It returns the 2 digit numeral code of the state under which the GSTIN is registered.	N/A - It depends on the actual value in the input document.

Failure Response Samples

You will receive a failure response similar to the following code sample if the PAN input does not have a match in the database.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "status": 200,
    "data": {
      "code": "1004",
      "message": "No matching GSTIN found for the given PAN"
    },
    "timestamp": 1684756331847
  }
}

Error Response Samples

Error Response Sample - Consent Not Provided

You will receive an error response in a format similar to the following code sample if the request is incorrect.

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "status": 400,
    "error": {
      "code": "CONSENT_NOT_GIVEN",
      "message": "Consent not provided."
    },
    "timestamp": 1664424599105
  }
}

Error Response Sample - Missing PAN Input

You will receive an error response in a format similar to the following code if the request is incorrect.

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "status": 400,
    "error": {
      "code": "BAD_REQUEST",
      "message": "Bad request.",
      "metadata": {
        "fields": [
          {
            "field": "pan_number",
            "message": "PAN number is required"
          }
        ]
      }
    },
    "timestamp": 1664424498900
  }
}

Error Response Details

An error response from the module contains a failure status, with a relevant status code and error message. The following table lists all error responses.

Status Code	Error Code	Error Description
400	CONSENT_NOT_GIVEN	The request did not have the consent input set to 'Y'.
400	BAD_REQUEST	The request is missing the mandatory PAN input.
503	UPSTREAM_SERVICE_UNAVAILABLE	The upstream source service (or government source service) was unavailable. Please restart the process.