> ## 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.

# Status

> Fetches the GST verification result using the `request_id`
returned from the initiate API.


### Overview

The **GST Verification – Status API** is used to **fetch the final verification result** of a GSTIN using the `request_id` generated by the **GST Verification – Initiate API**. This endpoint returns detailed and authoritative information about the GST registration, including legal entity details, registration status, filing history, jurisdiction, business nature, and other compliance-related metadata.

This API is intended to be called **after** a verification request has been successfully initiated. It completes the asynchronous verification workflow by providing the verified GST data once processing is finished.

### Workflow Context

1. Call **GST Verification – Initiate API** with a valid GSTIN.
2. Store the returned `request_id`.
3. Call **GST Verification – Status API** using the `request_id` to retrieve the verification result.

<Note>
  If the verification is still in progress or failed, the API response will
  reflect the appropriate status or error message.
</Note>

### Important Notes

* This API **must be called only after** initiating GST verification.
* The `request_id` is mandatory and uniquely identifies the verification request.
* Data returned is sourced from **authorized GST service providers (GSPs)**.
* The response represents the **latest available GST information** at the time of verification.
* Field availability may vary depending on the GSTIN and data source.


## OpenAPI

````yaml GET /gst/status
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:
  /gst/status:
    get:
      tags:
        - Business Verification
        - GST Verification
      summary: Fetch GST Verification Status
      description: |
        Fetches the GST verification result using the `request_id`
        returned from the initiate API.
      operationId: fetchGstVerificationStatus
      parameters:
        - in: query
          name: request_id
          required: true
          schema:
            type: string
            format: uuid
          description: Request ID received from the initiate API.
      responses:
        '200':
          description: GST verification success response .
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/GSTStatusResponse'
        '400':
          '401':
            $ref: '#/components/responses/401'
          '402':
            $ref: '#/components/responses/402'
          '403':
            $ref: '#/components/responses/403'
          '404':
            description: No Records Found
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/APIBaseResponse'
                    - type: object
                      required:
                        - data
                      properties:
                        data:
                          type: object
                          required:
                            - case_id
                          properties:
                            case_id:
                              $ref: '#/components/schemas/CaseId'
                    - $ref: '#/components/schemas/Credits'
                examples:
                  No records found:
                    summary: No records Found
                    value:
                      status: error
                      code: 404
                      message: '`request_id` does not exist or not found'
                      data:
                        case_id: 8a3b2d79e91c4ff1b2e97b9f2b36c123
                      credits_used: 0
                      credits_remaining: 499
          '500':
            $ref: '#/components/responses/500_WithCredits'
            description: Internal server error.
          $ref: '#/components/responses/400_WithCredits'
          description: Bad request due to invalid input data.
          content:
            application/json:
              examples:
                Invalid Request Id:
                  summary: Invalid Request Id
                  value:
                    status: error
                    code: 400
                    message: Invalid request_id provided in query params
                    data: null
                    credits_used: 0
                    credits_remaining: 8858
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Not Found - No GST verification found for the provided request_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithoutCredits'
              examples:
                No Record Found:
                  summary: No record found for this `request_id.
                  value:
                    status: error
                    code: 404
                    message: No record found for this `request_id.
                    data: null
        '500':
          $ref: '#/components/responses/500_WithCredits'
components:
  schemas:
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    GSTStatusResponse:
      type: object
      properties:
        gstin:
          type: string
          example: 27AABCI6363G1ZJ
          description: GSTIN of the company
        legal_name:
          type: string
          example: SUSTENANCE'S GROWTH CULTIVATION PRIVATE LIMITED
          description: Legal name of the company
        trade_name:
          type: string
          example: SUSTENANCE'S GROWTH CULTIVATION PRIVATE LIMITED
          description: Trade name of the company
        status:
          type: string
          example: Active
          description: Current status of the GST registration
        is_active:
          type: boolean
          example: true
          description: Indicates whether the GST registration is currently active
        constitution:
          type: string
          description: Type of business constitution
          example: Private Limited Company
        registration_date:
          type: string
          format: date
          example: '2019-03-01T00:00:00.000Z'
          description: Date when the GST registration was completed
        cancellation_date:
          type: string
          nullable: true
          example: null
          description: Date when the GST registration was cancelled, if applicable
        business_nature:
          type: array
          items:
            type: string
          description: Nature of business activities
        is_sez:
          type: boolean
          example: false
          description: Indicates whether the business is located in a Special Economic Zone
        turnover:
          type: object
          description: Turnover information of the business
          properties:
            slab:
              type: string
              example: 'Slab: Rs. 0 to 40 lakhs'
              description: Turnover range or slab
            financial_year:
              type: string
              example: 2024-2025
              description: Financial year for the turnover data
        principal_address:
          type: object
          description: Principal place of business address
          properties:
            address:
              type: string
              description: Full address of the principal place of business
            pincode:
              type: string
              description: Postal code
            state:
              type: string
              description: State name
            district:
              type: string
              description: District name
        jurisdiction:
          type: object
          description: Tax jurisdiction details
          properties:
            center:
              type: string
              description: Central jurisdiction name
            center_code:
              type: string
              description: Central jurisdiction code
            state_code:
              type: string
              description: State jurisdiction code
        filing_summary:
          type: object
          description: Summary of GST return filings
          properties:
            gstr1_filed_count:
              type: integer
              description: Total number of GSTR-1 returns filed
            gstr3b_filed_count:
              type: integer
              description: Total number of GSTR-3B returns filed
            last_gstr1_filed_on:
              type: string
              format: date
              description: Date when the last GSTR-1 return was filed
            last_gstr3b_filed_on:
              type: string
              format: date
              description: Date when the last GSTR-3B return was filed
        hsn_codes:
          type: array
          description: List of HSN (Harmonized System of Nomenclature) codes registered
          items:
            type: object
            properties:
              hsn_code:
                type: string
                description: HSN code number
              hsn_description:
                type: string
                description: Description of goods or services for this HSN code
              type:
                type: string
                example: service
                description: Type of HSN code (goods or service)
        promoters:
          type: array
          items:
            type: string
          description: List of promoters or directors of the company
        source:
          type: string
          example: GSP
          description: Source of the GST data
        last_updated:
          type: string
          format: date
          example: '2024-07-26T00:00:00.000Z'
          description: Date when the GST information was last updated
    ErrorWithoutCredits:
      allOf:
        - $ref: '#/components/schemas/Error'
        - $ref: '#/components/schemas/APIErrorData'
    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
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
    Credits:
      type: object
      properties:
        credits_used:
          $ref: '#/components/schemas/CreditsUsed'
        credits_left:
          $ref: '#/components/schemas/CreditsLeft'
      required:
        - credits_used
        - credits_left
    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
  responses:
    '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
    400_WithCredits:
      description: Bad Request
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
              - $ref: '#/components/schemas/Credits'
    500_WithCredits:
      description: Internal Server Error
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - $ref: '#/components/schemas/APIErrorData'
              - $ref: '#/components/schemas/Credits'
          examples:
            Internal Server Error:
              summary: Internal Server Error.
              value:
                status: error
                code: 500
                message: Internal Server Error.
                data: null
                credits_used: 3
                credits_remaining: 178
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key issued by KonnectNXT. Pass as `Authorization: Bearer
        <your_api_key>`.

````