BulkResultRow

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gstinapi/main/json-schema/gstinapi-bulk-result-row-schema.json",
  "title": "BulkResultRow",
  "description": "One submitted row and what became of it.",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gstinapi-openapi.yml#/components/schemas/BulkResultRow",
  "type": "object",
  "properties": {
    "row": {
      "type": "integer",
      "description": "Position in the submitted list, 1-based."
    },
    "input": {
      "type": "string",
      "description": "What was submitted for this row, verbatim."
    },
    "gstin": {
      "type": [
        "string",
        "null"
      ],
      "description": "The normalised GSTIN, or null if the entry was not a usable one."
    },
    "outcome": {
      "$ref": "#/$defs/Outcome"
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why this row is not `ok`. Null when it is."
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/$defs/TaxpayerProfile"
        },
        {
          "type": "null"
        }
      ],
      "description": "The verified profile. Present only when `outcome` is `ok`."
    }
  },
  "$defs": {
    "Outcome": {
      "type": "string",
      "enum": [
        "ok",
        "not_found",
        "invalid_format",
        "upstream_error",
        "skipped",
        "pending"
      ],
      "description": "What happened to a row, and whether it cost anything:\n\n- `ok` — a live registration was found. **One credit.**\n- `not_found` — well-formed, but no registration exists. Free.\n- `invalid_format` — not a valid GSTIN; rejected on its checksum without contacting the government source. Free.\n- `upstream_error` — the government source could not answer. Free; resubmit the row.\n- `skipped` — the job was cancelled or ran out of credits before reaching this row. Free.\n- `pending` — not verified yet. Only seen while a job is still running."
    },
    "TaxpayerProfile": {
      "type": "object",
      "description": "A verified registration, normalised. This is the shape bulk results carry; the single endpoint returns the raw envelope instead.",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "gstin": {
          "type": "string"
        },
        "legal_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "trade_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Falls back to the legal name when the business reports no separate trade name."
        },
        "status": {
          "type": "string",
          "description": "Active, Cancelled, Suspended, Provisional, …"
        },
        "taxpayer_type": {
          "type": [
            "string",
            "null"
          ]
        },
        "constitution": {
          "type": [
            "string",
            "null"
          ]
        },
        "registration_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "cancellation_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "last_updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "active_years": {
          "type": [
            "integer",
            "null"
          ]
        },
        "nature_of_business": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "jurisdiction": {
          "type": "object",
          "properties": {
            "centre": {
              "type": [
                "string",
                "null"
              ]
            },
            "centre_code": {
              "type": [
                "string",
                "null"
              ]
            },
            "state": {
              "type": [
                "string",
                "null"
              ]
            },
            "state_code": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "principal_address": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "formatted": {
              "type": "string"
            },
            "building": {
              "type": [
                "string",
                "null"
              ]
            },
            "street": {
              "type": [
                "string",
                "null"
              ]
            },
            "locality": {
              "type": [
                "string",
                "null"
              ]
            },
            "district": {
              "type": [
                "string",
                "null"
              ]
            },
            "state": {
              "type": [
                "string",
                "null"
              ]
            },
            "pincode": {
              "type": [
                "string",
                "null"
              ]
            },
            "nature": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "additional_address_count": {
          "type": "integer"
        },
        "e_invoice": {
          "type": "object",
          "properties": {
            "enabled": {
              "type": "boolean"
            },
            "generating": {
              "type": "boolean"
            },
            "turnover_slab": {
              "type": [
                "string",
                "null"
              ]
            },
            "eligibility": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "filing_counts": {
          "type": "object",
          "description": "Count of filings held per return type.",
          "additionalProperties": {
            "type": "integer"
          }
        },
        "derived": {
          "type": "object",
          "description": "Read from the GSTIN itself, not reported by the register.",
          "properties": {
            "state_code": {
              "type": [
                "string",
                "null"
              ]
            },
            "state_name": {
              "type": [
                "string",
                "null"
              ]
            },
            "pan": {
              "type": [
                "string",
                "null"
              ]
            },
            "pan_holder_type": {
              "type": [
                "string",
                "null"
              ]
            },
            "entity_code": {
              "type": [
                "string",
                "null"
              ]
            },
            "registration_number_in_state": {
              "type": [
                "integer",
                "null"
              ]
            }
          }
        },
        "source": {
          "type": "object",
          "properties": {
            "fetched_at": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "served_from_cache": {
              "type": "boolean",
              "description": "The register itself refreshes a few times a day, so recent lookups are served from cache. Cached rows are charged the same as fresh ones."
            }
          }
        }
      }
    }
  }
}