Job

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mobilevalidate-com/json-schema/mobilevalidate-com-job-schema.json",
  "title": "Job",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mobilevalidate-com-openapi.yaml#/components/schemas/Job",
  "type": "object",
  "required": [
    "object",
    "id",
    "status",
    "created_at"
  ],
  "properties": {
    "object": {
      "type": "string",
      "const": "job"
    },
    "id": {
      "type": "string",
      "pattern": "^job_"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "preflight",
        "running",
        "merging",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "livemode": {
      "type": "boolean"
    },
    "checks": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "progress": {
      "$ref": "#/$defs/JobProgress"
    },
    "eta_seconds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "cost": {
      "type": "object",
      "properties": {
        "estimated_max": {
          "$ref": "#/$defs/Money"
        },
        "reserved": {
          "$ref": "#/$defs/Money"
        },
        "charged": {
          "$ref": "#/$defs/Money"
        },
        "released": {
          "$ref": "#/$defs/Money"
        },
        "breakdown": {
          "type": "array",
          "description": "Unit prices fixed when the job was created (same lines as the estimate's breakdown). Only conclusive checks are charged.",
          "items": {
            "$ref": "#/$defs/PriceLine"
          }
        }
      }
    },
    "estimate": {
      "$ref": "#/$defs/Estimate"
    },
    "retention_days": {
      "type": "integer"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "purged_at": {
      "type": "string",
      "format": "date-time",
      "description": "Set when the results were deleted with DELETE /v1/jobs/{id}."
    }
  },
  "$defs": {
    "Estimate": {
      "type": "object",
      "properties": {
        "object": {
          "type": "string",
          "const": "estimate"
        },
        "total": {
          "type": "integer"
        },
        "valid": {
          "type": "integer"
        },
        "invalid": {
          "type": "integer"
        },
        "duplicate": {
          "type": "integer"
        },
        "unsupported": {
          "type": "integer"
        },
        "suppressed": {
          "type": "integer"
        },
        "checks": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "checks_total": {
          "type": "integer",
          "description": "Σ rows × checks of the row's input type"
        },
        "cached": {
          "type": "integer",
          "description": "Checks (row × check) with a fresh answer in your account's cache now; free if still fresh when the job runs."
        },
        "billable_max": {
          "type": "integer",
          "description": "Checks (row × check) that may be billed, worst case (includes `cached`)."
        },
        "max_cost": {
          "$ref": "#/$defs/Money",
          "description": "Worst-case cost; equals the reservation made by POST /v1/jobs, so it can be passed as that request's max_cost."
        },
        "breakdown": {
          "type": "array",
          "description": "Price lines per check: one `batch` line, plus a `realtime` line (reason `small_batch`) for checks in parts too small for the bulk price, or a `country_minimum` line for countries of a bulk-only check below its minimum per country. Σ max_cost of the lines = max_cost.",
          "items": {
            "$ref": "#/$defs/PriceLine"
          }
        },
        "unsupported_checks": {
          "type": "array",
          "description": "Checks that will not run for some countries of the list because the check does not cover them (see `unsupported_countries` in GET /v1/services). They are stored as `unsupported_country`, never reserved or billed, and are not part of `billable_max`. Empty when every check covers every country of the list.\n",
          "items": {
            "type": "object",
            "required": [
              "check",
              "checks",
              "countries",
              "country_checks"
            ],
            "properties": {
              "check": {
                "type": "string",
                "description": "Service code."
              },
              "checks": {
                "type": "integer",
                "description": "Checks (row × check) not run."
              },
              "countries": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "ISO 3166-1 alpha-2 countries not covered."
              },
              "country_checks": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "description": "Checks not run per country."
              }
            }
          }
        }
      }
    },
    "JobProgress": {
      "type": "object",
      "description": "total = rows (numbers + e-mails); checks_total = Σ rows × checks of their input type; done/conclusive/non_billable count checks.",
      "properties": {
        "total": {
          "type": "integer"
        },
        "checks_total": {
          "type": "integer"
        },
        "done": {
          "type": "integer"
        },
        "conclusive": {
          "type": "integer"
        },
        "non_billable": {
          "type": "integer"
        }
      }
    },
    "Money": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "string",
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "description": "Decimal USD amount."
        },
        "currency": {
          "type": "string",
          "enum": [
            "USD"
          ]
        }
      }
    },
    "PriceLine": {
      "type": "object",
      "required": [
        "check",
        "price_mode",
        "reason",
        "checks",
        "unit_price",
        "max_cost"
      ],
      "properties": {
        "check": {
          "type": "string",
          "description": "Service code."
        },
        "price_mode": {
          "type": "string",
          "enum": [
            "batch",
            "realtime"
          ],
          "description": "Which of the check's prices applies to these checks."
        },
        "reason": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "small_batch",
            "country_minimum",
            null
          ],
          "description": "Why a bulk-job line is priced differently. `small_batch`: the numbers of these countries form a part smaller than the bulk minimum (`batch_minimum` numbers per country for this check in one job), so they are checked the real-time way at the real-time price. Send at least `batch_minimum` numbers per country to get the bulk price. `country_minimum`: a bulk-only check (no real-time price); each country group (numbers of one country for this check in one job) is billed max(conclusive answers × unit_price, `minimum_charge`) when it returns at least one conclusive answer, and nothing otherwise. The line lists the countries with fewer than `minimum_checks` numbers; countries with more stay on the `batch` line (same rule, which only matters when fewer than `minimum_checks` of their numbers answer). New values may be added.\n"
        },
        "checks": {
          "type": "integer",
          "description": "Checks (row × check) at this unit price; valid rows only."
        },
        "unit_price": {
          "$ref": "#/$defs/Money",
          "description": "Price per conclusive check (your account's price). Shown for test keys too."
        },
        "max_cost": {
          "$ref": "#/$defs/Money",
          "description": "checks × unit_price; for country_minimum lines minimum_charge × countries (0 for test keys)."
        },
        "countries": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "small_batch / country_minimum lines: ISO 3166-1 alpha-2 countries of the line."
        },
        "batch_minimum": {
          "type": "integer",
          "description": "small_batch lines: numbers per country (for this check, in one job) needed for the bulk price."
        },
        "country_checks": {
          "type": "object",
          "additionalProperties": {
            "type": "integer"
          },
          "description": "country_minimum lines: numbers per country (for this check, in this job)."
        },
        "minimum_checks": {
          "type": "integer",
          "description": "country_minimum lines: checks billed at least per country that returns an answer (e.g. 500)."
        },
        "minimum_charge": {
          "$ref": "#/$defs/Money",
          "description": "country_minimum lines: minimum charge per country = minimum_checks × unit_price."
        },
        "note": {
          "type": "string",
          "description": "country_minimum lines: plain-English explanation of the line."
        }
      }
    }
  }
}