VerificationResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hail-so/json-schema/hail-so-verification-response-schema.json",
  "title": "VerificationResponse",
  "description": "A carrier verification: its state and the name of the person or\ncompany it is for. No other personal data.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hail-so-openapi.json#/components/schemas/VerificationResponse",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "title": "Id",
      "description": "Unique identifier for this verification."
    },
    "country_code": {
      "type": "string",
      "title": "Country Code",
      "description": "ISO alpha-2 country code."
    },
    "number_type": {
      "type": "string",
      "title": "Number Type",
      "description": "Kind of number: 'local', 'mobile', 'toll_free', or 'national'."
    },
    "subject_type": {
      "type": "string",
      "title": "Subject Type",
      "description": "'person' or 'business'."
    },
    "subject_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Subject Name",
      "description": "Name of the person or company this verification is for, taken from the form (for example the business name, or the first and last name). Null when unknown."
    },
    "purpose": {
      "type": "string",
      "title": "Purpose",
      "description": "'number': permission to buy a number in this country. 'sms': registration to text US numbers from a US number."
    },
    "state": {
      "type": "string",
      "title": "State",
      "description": "'awaiting_review', 'submitting', 'submitted', 'approved', 'rejected', or 'cancelled'."
    },
    "rejection_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Rejection Reason",
      "description": "Why it was rejected. Null unless rejected."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At",
      "description": "When the verification was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated At",
      "description": "When it last changed."
    },
    "submitted_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Submitted At",
      "description": "When it was submitted to the carrier."
    },
    "approved_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Approved At",
      "description": "When the carrier approved it."
    },
    "confirmation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Confirmation",
      "description": "For a person's US texting registration: 'code' when you must enter the code the carrier texted (POST /verifications/{id}/confirm), 'reply' when you must answer the carrier's text, null when nothing is pending."
    },
    "step": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "confirm_identity",
            "filing",
            "carrier_review",
            "runtime_setup",
            "needs_information"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Step",
      "description": "For a US texting registration that is not yet approved or rejected: 'confirm_identity' while the person must confirm (see `confirmation`), 'filing' while Hail files the details with the carriers, 'carrier_review' once the carriers are reviewing them (1 to 7 business days), or runtime_setup when accepted but required messaging responses still need configuration; needs_information when the existing sender needs current campaign evidence before filing. Null otherwise."
    },
    "campaign_accepted": {
      "type": "boolean",
      "title": "Campaign Accepted",
      "description": "The carrier accepted the SMS campaign; this alone does not mean a number is ready to send.",
      "default": false
    },
    "runtime_ready": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Runtime Ready",
      "description": "True when required runtime configuration was verified, false while setup retries, null when not independently tracked."
    },
    "cancellable": {
      "type": "boolean",
      "title": "Cancellable",
      "description": "True when `DELETE /v1/verifications/{id}` accepts this verification now.",
      "default": false
    },
    "identity_confirmed": {
      "type": "boolean",
      "title": "Identity Confirmed",
      "description": "True on a person's newest US texting registration when it is cancelled, or rejected and not yet dismissed, and the person stays confirmed: the next filing with the same first name, last name, email and mobile needs no code and has no submission fee. Dismiss a rejected registration first. Ignore it on older registrations.",
      "default": false
    },
    "waiting_for_credit": {
      "type": "boolean",
      "title": "Waiting For Credit",
      "description": "True when a US texting registration waits for credit: its next step, filing the campaign, has a carrier fee your balance does not cover. Nothing is filed until it does. Add credit; Hail goes on at its next check.",
      "default": false
    },
    "credit_needed_cents": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Credit Needed Cents",
      "description": "The credit this registration still needs before Hail files its campaign, in US cents; null when `waiting_for_credit` is false. Per registration, not a running total: the first waiting registration shows the carrier's campaign fee less the credit left after the registrations already covered (more when the balance is short), each later one its whole fee. Add the sum over every registration with `waiting_for_credit` true, and one top-up lets them all go. It follows the balance, so read it again before you pay."
    }
  },
  "type": "object",
  "required": [
    "id",
    "country_code",
    "number_type",
    "subject_type",
    "purpose",
    "state",
    "created_at",
    "updated_at"
  ]
}