BulkJobEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/gstinapi/main/json-schema/gstinapi-bulk-job-envelope-schema.json",
  "title": "BulkJobEnvelope",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gstinapi-openapi.yml#/components/schemas/BulkJobEnvelope",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "job": {
      "$ref": "#/$defs/BulkJob"
    },
    "links": {
      "type": "object",
      "description": "Where to poll this job and collect its results.",
      "properties": {
        "self": {
          "type": "string",
          "format": "uri"
        },
        "results": {
          "type": "string",
          "format": "uri"
        },
        "csv": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  },
  "$defs": {
    "BulkJob": {
      "type": "object",
      "description": "A submitted list and how far through it we are.",
      "properties": {
        "job_id": {
          "type": "string",
          "format": "uuid"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "processing",
            "completed",
            "cancelled",
            "failed"
          ],
          "description": "Terminal states are `completed`, `cancelled` and `failed`. Stop polling on any of them."
        },
        "stopped_reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "insufficient_credits",
            "cancelled",
            null
          ],
          "description": "Why a job ended before reaching every row. Null on a job that ran to completion normally."
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "type": "string",
          "enum": [
            "api",
            "dashboard"
          ]
        },
        "progress": {
          "type": "object",
          "properties": {
            "percent": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "total_rows": {
              "type": "integer",
              "description": "Entries submitted, duplicates included."
            },
            "total_lookups": {
              "type": "integer",
              "description": "Distinct valid GSTINs — what actually reaches the government source, and the most this job can cost."
            },
            "completed_lookups": {
              "type": "integer"
            }
          }
        },
        "results": {
          "type": "object",
          "description": "Outcome tallies, counted over distinct GSTINs rather than rows.",
          "properties": {
            "succeeded": {
              "type": "integer"
            },
            "not_found": {
              "type": "integer"
            },
            "invalid": {
              "type": "integer"
            },
            "failed": {
              "type": "integer"
            },
            "skipped": {
              "type": "integer"
            }
          }
        },
        "credits_used": {
          "type": "integer",
          "description": "Credits charged so far. Equals `results.succeeded`."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "started_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    }
  }
}