> ## Documentation Index
> Fetch the complete documentation index at: https://docs.konnectnxt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GST Certificate v2

> Verify GST certificate details including registration information, filing history, and e-invoice status without document parsing

## Overview

The GST Certificate Verification API provides comprehensive GST information by verifying the GSTIN directly against government records. Unlike document parsing, this API fetches real-time data including business details, filing history, and compliance status.

### Key Features

* **Real-time Verification**: Fetches live data from GST portal
* **Complete Business Details**: Legal name, trade name, registration dates
* **Filing History**: GSTR-1 and GSTR-3B filing records
* **E-Invoice Status**: Check e-invoice applicability
* **Address Information**: Principal and additional business locations

***

## GSTIN Validation

### Format Requirements

A valid GSTIN must follow this structure:

* **Position 1-2**: State code (27 = Maharashtra)
* **Position 3-12**: PAN of the business (AABCI6363G)
* **Position 13**: Entity number (1 = First registration)
* **Position 14**: Default alphabet 'Z'
* **Position 15**: Check digit (J)

Example: `27AABCI6363G1ZJ`

### Valid State Codes

| Code Range | States/UTs                     |
| ---------- | ------------------------------ |
| 01-19      | Jammu & Kashmir to West Bengal |
| 20-37      | Jharkhand to Andhra Pradesh    |
| 38         | Ladakh                         |
| 97         | Other Territory                |

*Note: Code 25 is not used (reserved)*

[Check Detailed State Codes](https://cleartax.in/s/gst-state-code-jurisdiction)

### Validation Errors

Common validation errors include:

* **Invalid Length**: GSTIN must be exactly 15 characters
* **Invalid State Code**: First 2 digits must be a valid Indian state/UT code
* **Invalid Format**: Must match the required pattern
* **Invalid Characters**: Only alphanumeric characters allowed


## OpenAPI

````yaml POST /v2/verification/gst-certificate/
openapi: 3.0.0
info:
  title: KonnectNXT API Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://bgv.konnectnxt.com/api
    description: Production
  - url: https://testbgv.konnectnxt.com/api
    description: QA
security:
  - bearerAuth: []
paths:
  /v2/verification/gst-certificate/:
    post:
      tags:
        - Business Verification
      summary: Verify GST Certificate
      description: >-
        Verifies GST certificate details including registration information,
        filing history, and e-invoice status. This API provides comprehensive
        GST data without parsing documents.
      operationId: verifyGstCertificate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GSTCertificateRequest'
            examples:
              Example:
                summary: GST Certificate verification with filing details
                value:
                  gstin: 27AABCI6363G1ZJ
                  filing_details: true
                  e_invoice_details: true
      responses:
        '200':
          description: GST certificate verified successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/GSTCertificateData'
                  - $ref: '#/components/schemas/Credits'
              examples:
                Success:
                  summary: Successful GST certificate verification
                  value:
                    status: success
                    code: 200
                    message: Operation completed successfully
                    data:
                      gstin: 27AABCI6363G1ZJ
                      gstinStatus: Active
                      verificationStatus: VERIFIED
                      legalName: SAMPLE COMPANY PRIVATE LIMITED
                      tradeName: SAMPLE COMPANY
                      dateOfRegistration: '2017-07-01'
                      dateOfCancellation: ''
                      constitutionOfBusiness: Private Limited Company
                      taxpayerType: Regular
                      isSez: false
                      eInvoiceStatus: ACT
                      lastUpdatedDate: '2025-12-19'
                      centreJurisdiction: RANGE-IV
                      centreJurisdictionCode: VU0404
                      stateJurisdictionCode: MHCG0491
                      natureOfBusinessActivity:
                        - Office / Sale Office
                        - Warehouse / Depot
                        - Supplier of Services
                      principalPlaceOfBusiness:
                        nature: Office / Sale Office
                        address:
                          buildingName: Example Building
                          doorNumber: '123'
                          floorNumber: 2nd Floor
                          street: Main Street
                          location: Business District
                          city: Mumbai
                          district: Mumbai Suburban
                          stateName: Maharashtra
                          pincode: '400001'
                          latitude: ''
                          longitude: ''
                      additionalPlaceOfBusiness: null
                      filingDetails:
                        gstr1:
                          - financialYear: 2025-2026
                            taxPeriod: December
                            dateOfFiling: '2026-01-10'
                            status: Filed
                          - financialYear: 2025-2026
                            taxPeriod: November
                            dateOfFiling: '2025-12-11'
                            status: Filed
                        gstr3b:
                          - financialYear: 2025-2026
                            taxPeriod: December
                            dateOfFiling: '2026-01-20'
                            status: Filed
                          - financialYear: 2025-2026
                            taxPeriod: November
                            dateOfFiling: '2025-12-20'
                            status: Filed
                    credits_used: 10
                    credits_remaining: 984106.5
        '400':
          $ref: '#/components/responses/400'
          description: Bad request due to invalid input data
          content:
            application/json:
              examples:
                Invalid GSTIN Format:
                  summary: Invalid GSTIN format
                  value:
                    status: error
                    code: 400
                    message: >-
                      Invalid GSTIN format. Expected format: 2 digits (state) +
                      10 chars (PAN) + 3 chars (entity/check)
                    data: null
                Invalid State Code:
                  summary: Invalid state code in GSTIN
                  value:
                    status: error
                    code: 400
                    message: >-
                      Invalid GSTIN: State code is not a valid Indian state/UT
                      code
                    data: null
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: GST number not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Error'
                  - $ref: '#/components/schemas/APIErrorData'
              examples:
                GSTIN Not Found:
                  summary: GSTIN not found in database
                  value:
                    status: error
                    code: 404
                    message: No records found for the provided GSTIN
                    data: null
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    GSTCertificateRequest:
      type: object
      required:
        - gstin
      properties:
        gstin:
          type: string
          description: >-
            GST Identification Number (15 characters: 2 digits state code + 10
            characters PAN + 3 characters entity/check digit)
          pattern: ^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$
          minLength: 15
          maxLength: 15
          example: 27AABCI6363G1ZJ
        filing_details:
          type: boolean
          description: Whether to include GSTR-1 and GSTR-3B filing history
          default: true
          example: true
        e_invoice_details:
          type: boolean
          description: Whether to include e-invoice status details
          default: true
          example: true
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    GSTCertificateData:
      type: object
      required:
        - gstin
        - gstinStatus
        - verificationStatus
        - legalName
        - taxpayerType
      properties:
        gstin:
          type: string
          description: GST Identification Number
          example: 27AABCI6363G1ZJ
        gstinStatus:
          type: string
          enum:
            - Active
            - Cancelled
            - Suspended
            - Inactive
          description: Current status of the GSTIN
          example: Active
        verificationStatus:
          type: string
          enum:
            - VERIFIED
            - NOT_VERIFIED
            - PENDING
          description: Verification status of the GST certificate
          example: VERIFIED
        legalName:
          type: string
          description: Legal name of the business as registered
          example: SAMPLE COMPANY PRIVATE LIMITED
        tradeName:
          type: string
          description: Trade name of the business
          example: SAMPLE COMPANY
        dateOfRegistration:
          type: string
          format: date
          description: Date of GST registration (YYYY-MM-DD format)
          example: '2017-07-01'
        dateOfCancellation:
          type: string
          description: Date of cancellation if applicable (empty if active)
          example: ''
        constitutionOfBusiness:
          type: string
          description: Type of business constitution
          example: Private Limited Company
        taxpayerType:
          type: string
          enum:
            - Regular
            - Composition
            - Input Service Distributor
            - SEZ Developer
            - SEZ Unit
          description: Type of taxpayer registration
          example: Regular
        isSez:
          type: boolean
          description: Whether the business is registered in a Special Economic Zone
          example: false
        eInvoiceStatus:
          type: string
          enum:
            - ACT
            - INACT
            - NA
          description: E-invoice applicability status
          example: ACT
        lastUpdatedDate:
          type: string
          format: date
          description: Date when GST data was last updated
          example: '2025-12-19'
        centreJurisdiction:
          type: string
          description: Central jurisdiction name
          example: RANGE-IV
        centreJurisdictionCode:
          type: string
          description: Central jurisdiction code
          example: VU0404
        stateJurisdictionCode:
          type: string
          description: State jurisdiction code
          example: MHCG0491
        natureOfBusinessActivity:
          type: array
          description: List of business activities
          items:
            type: string
          example:
            - Office / Sale Office
            - Warehouse / Depot
            - Supplier of Services
        principalPlaceOfBusiness:
          $ref: '#/components/schemas/GSTBusinessPlace'
        additionalPlaceOfBusiness:
          type: array
          nullable: true
          description: Additional business locations (if any)
          items:
            $ref: '#/components/schemas/GSTBusinessPlace'
        filingDetails:
          $ref: '#/components/schemas/GSTFilingDetails'
    Credits:
      type: object
      properties:
        credits_used:
          $ref: '#/components/schemas/CreditsUsed'
        credits_left:
          $ref: '#/components/schemas/CreditsLeft'
      required:
        - credits_used
        - credits_left
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
    APIStatus:
      type: string
      enum:
        - success
        - error
      description: Overall status of the API
    HTTPCode:
      type: integer
      description: HTTP status code
      example: 400
    APIMessage:
      type: string
      description: Description of the response or error
      example: Invalid request parameters
    GSTBusinessPlace:
      type: object
      properties:
        nature:
          type: string
          description: Nature of business place
          example: Office / Sale Office
        address:
          $ref: '#/components/schemas/GSTAddress'
    GSTFilingDetails:
      type: object
      properties:
        gstr1:
          type: array
          description: GSTR-1 return filing history
          items:
            $ref: '#/components/schemas/GSTFilingEntry'
        gstr3b:
          type: array
          description: GSTR-3B return filing history
          items:
            $ref: '#/components/schemas/GSTFilingEntry'
    CreditsUsed:
      type: integer
      description: Represents the total number of credits used in this request.
      example: 3
    CreditsLeft:
      type: integer
      description: 'Represents the remaining credits available for use. '
      example: 4040
    GSTAddress:
      type: object
      properties:
        buildingName:
          type: string
          description: Building or complex name
          example: Example Building
        doorNumber:
          type: string
          description: Door or flat number
          example: '123'
        floorNumber:
          type: string
          description: Floor number
          example: 2nd Floor
        street:
          type: string
          description: Street name
          example: Main Street
        location:
          type: string
          description: Location or area
          example: Business District
        city:
          type: string
          description: City name
          example: Mumbai
        district:
          type: string
          description: District name
          example: Mumbai Suburban
        stateName:
          type: string
          description: State name
          example: Maharashtra
        pincode:
          type: string
          pattern: ^[0-9]{6}$
          description: 6-digit PIN code
          example: '400001'
        latitude:
          type: string
          description: Geographical latitude (if available)
          example: ''
        longitude:
          type: string
          description: Geographical longitude (if available)
          example: ''
    GSTFilingEntry:
      type: object
      required:
        - financialYear
        - taxPeriod
        - dateOfFiling
        - status
      properties:
        financialYear:
          type: string
          description: Financial year for the filing
          example: 2025-2026
        taxPeriod:
          type: string
          description: Tax period/month
          example: December
        dateOfFiling:
          type: string
          format: date
          description: Date when return was filed (YYYY-MM-DD format)
          example: '2026-01-10'
        status:
          type: string
          enum:
            - Filed
            - Not Filed
            - Late Filed
          description: Filing status
          example: Filed
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Missing Token:
              summary: Bearer token is missing or invalid.
              value:
                status: error
                code: 401
                message: Bearer token is missing or invalid.
                data: null
            Incorrect Token Format:
              summary: Token format is incorrect
              value:
                status: error
                code: 401
                message: Token format is incorrect
                data: null
            No Admin Found:
              summary: No admin found for this request
              value:
                status: error
                code: 401
                message: No admin user found for this organization
                data: null
            Invalid API Key:
              summary: Invalid API Key
              value:
                status: error
                code: 401
                message: Invalid API key (organization ID)
                data: null
            User not Found:
              summary: User not found
              value:
                status: error
                code: 401
                message: User not found.
                data: null
    '402':
      description: Payment Required
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Credit Limit Exceed:
              summary: Credit Limit Exceeded.
              value:
                status: error
                code: 402
                message: Credit Limit Exceeded.
                data: null
            Insufficient Credits:
              summary: Insufficient credits
              value:
                status: error
                code: 402
                message: 'Insufficient credits: 2 required, 1 remaining.'
                data: null
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Token Revoked:
              summary: Token access has been Revoked, Contact Support.
              value:
                status: error
                code: 403
                message: Token access has been Revoked, Contact Support.
                data: null
            Token Inactive:
              summary: Token is Inactive, Contact Support.
              value:
                status: error
                code: 403
                message: Token is Inactive, Contact Support.
                data: null
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
          examples:
            Internal Server Error:
              summary: Internal Server Error.
              value:
                status: error
                code: 500
                message: Internal Server Error.
                data: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued by KonnectNXT. Pass as `Authorization: Bearer
        <your_api_key>`.

````