Estimate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mobilevalidate-com/json-schema/mobilevalidate-com-estimate-schema.json",
  "title": "Estimate",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mobilevalidate-com-openapi.yaml#/components/schemas/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."
          }
        }
      }
    }
  },
  "$defs": {
    "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."
        }
      }
    }
  }
}