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

# Initiate

> Initiates a GST verification request.
The response returns a `request_id` which should be used to fetch the verification result.


### Overview

The **GST Verification – Initiate API** is used to start the verification process for a given **GST Identification Number (GSTIN)**. This API validates the provided GSTIN and creates a verification request in the system. Upon successful initiation, the API returns a unique `request_id` which can be used to **track and fetch the final verification result** through the corresponding status or result API.

This API is designed for **asynchronous verification**, meaning the verification process may take some time to complete. Clients are expected to store the returned `request_id` and query the verification status separately.

***

### Use Cases

This API is commonly used in scenarios such as:

* Business onboarding and KYC verification
* Vendor or supplier validation
* Background verification (BGV) workflows
* Compliance and regulatory checks
* Automated GST authenticity validation in enterprise systems

### Important Notes

* This API **only initiates** the GST verification process.
* The actual verification result is not returned immediately.
* Always store the returned `request_id` and use it with the GST Verification Status/Result API to retrieve the final verification details.
* Credits are consumed only for **valid initiation requests**.
* Ensure the GSTIN follows the standard **15-character format** before making the request to avoid unnecessary failures.


## OpenAPI

````yaml POST /gst/initiate
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/initiate:
    post:
      tags:
        - Business Verification
        - GST Verification
      summary: Initiate GST Verification
      description: >
        Initiates a GST verification request.

        The response returns a `request_id` which should be used to fetch the
        verification result.
      operationId: initiateGstVerification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GSTInitiateRequest'
      responses:
        '202':
          description: GST verification successfully initiated.
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/APIBaseResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/GSTInitiateResponse'
                  - $ref: '#/components/schemas/Credits'
              examples:
                Success:
                  description: Success Response
                  value:
                    status: success
                    code: 200
                    message: string
                    data:
                      request_id: cbb66de8-83f3-47f9-90f5-4719340d2f39
                    credits_used: 3
                    credits_left: 34
        '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: No records 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 GST Number:
                  summary: Invalid GST Number
                  value:
                    status: error
                    code: 400
                    message: Invalid GST Number
                    data: null
                    credits_used: 0
                    credits_remaining: 8858
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500_WithCredits'
components:
  schemas:
    GSTInitiateRequest:
      type: object
      required:
        - gstin
      properties:
        gstin:
          type: string
          example: 36AAGCN9336F1Z9
          description: Valid 15-character GST Identification Number.
    APIBaseResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          $ref: '#/components/schemas/APIStatus'
        code:
          $ref: '#/components/schemas/HTTPCode'
        message:
          $ref: '#/components/schemas/APIMessage'
    GSTInitiateResponse:
      type: object
      properties:
        request_id:
          description: Unique ID for the GST Verification Request
          type: string
          format: uuid
          example: cbb66de8-83f3-47f9-90f5-4719340d2f39
    Credits:
      type: object
      properties:
        credits_used:
          $ref: '#/components/schemas/CreditsUsed'
        credits_left:
          $ref: '#/components/schemas/CreditsLeft'
      required:
        - credits_used
        - credits_left
    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
    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
    Error:
      allOf:
        - $ref: '#/components/schemas/APIBaseResponse'
    APIErrorData:
      type: object
      properties:
        data:
          type: object
          nullable: true
          example: null
  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>`.

````