openapi: 3.2.0
info:
  title: GSTIN Verification API
  version: 1.1.0
  summary: Verify Indian GST registration numbers, one at a time or in bulk.
  description: 'Live GSTIN verification against the Indian GST register, sourced through a GST

    Suvidha Provider network rather than by scraping the public portal.'
  termsOfService: https://gstinapi.com/terms
  license:
    name: Commercial — see terms of service
    url: https://gstinapi.com/terms
  contact:
    name: GSTIN API support
    url: https://gstinapi.com/contact
    email: contact@gstinapi.com
  x-documentation: https://gstinapi.com/docs
servers:
- url: https://gstinapi.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Verification
  description: Verify a single GSTIN.
paths:
  /api/get-taxpayer-info/{gstin}:
    get:
      tags:
      - Verification
      operationId: getTaxpayerInfo
      summary: Verify one GSTIN
      description: 'Returns the taxpayer record for a single GSTIN.


        **This endpoint answers `200` for a GSTIN that does not exist.** A number

        with no registration behind it is a real answer rather than an error, and

        is reported inside the body as `taxpayer_data.status_code: 0` with an

        error code in `taxpayer_data.error`. The same is true of a GSTIN that

        fails its checksum, which is rejected without contacting the government

        source at all. Neither costs a credit — check `status_code`, not just the

        HTTP status.


        A `502` means our upstream source was unreachable. Nothing is charged;

        retry.'
      parameters:
      - name: gstin
        in: path
        required: true
        description: The 15-character GSTIN. Case-insensitive; spaces and dashes are stripped before validation.
        schema:
          type: string
          example: 27AAACR5055K1Z7
      responses:
        '200':
          description: The taxpayer record, or a structured "no such registration" answer. Charged only in the former case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxpayerEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
components:
  schemas:
    TaxpayerEnvelope:
      type: object
      description: The government data source payload, passed through verbatim. Check `taxpayer_data.status_code` — `1` is a live registration, `0` means no registration exists for this number and carries an error code instead.
      properties:
        taxpayer_data:
          type: object
          properties:
            status_code:
              type: integer
              enum:
              - 0
              - 1
            gstin:
              type: string
            name:
              type:
              - string
              - 'null'
              description: Legal name of the registered taxpayer.
            tradename:
              type:
              - string
              - 'null'
            status:
              type:
              - string
              - 'null'
            registrationDate:
              type:
              - string
              - 'null'
            constitution:
              type:
              - string
              - 'null'
            pradr:
              type:
              - object
              - 'null'
              description: Principal place of business, as a structured object.
            adadr:
              type:
              - array
              - 'null'
              items:
                type: object
              description: Additional places of business.
            einvoiceStatus:
              type:
              - string
              - 'null'
            error:
              type:
              - object
              - 'null'
              description: Present when `status_code` is 0.
              properties:
                error_cd:
                  type: string
                message:
                  type: string
        filing_data:
          type: array
          items:
            type: object
          description: Recent GSTR filings with period, ARN and filed status.
        preference_data:
          type: array
          items:
            type: object
        nc_data:
          type: object
          description: E-invoicing and e-way bill activity.
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        reason:
          type: string
          description: A stable code to branch on. The message is for people and may be reworded.
          enum:
          - no_gstins
          - too_many_gstins
          - too_many_active_jobs
          - insufficient_credits
          - already_finished
        message:
          type: string
      required:
      - success
      - message
  responses:
    PaymentRequired:
      description: The account has no credits left. Nothing was verified and nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Insufficient credits
    Unauthorized:
      description: The API key was missing, unknown, or not active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Invalid or missing API key
    UpstreamUnavailable:
      description: The government data source could not be reached. Nothing was charged; retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Per-account key, created and rotated from the dashboard at https://gstinapi.com/settings/api-keys. New accounts receive 20 free credits on email verification.