ApprovedVerificationResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/n0t1fy-dev/json-schema/n0t1fy-dev-approved-verification-response-schema.json",
  "title": "ApprovedVerificationResponse",
  "description": "The only success a check has. As the check's response model it makes the rule\n\"a 2xx is only an approval\" the code's own: anything else answers 500, not 200\n(the 2026-10-15 checkpoint, item 4). The MCP check tool validates through it too.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/n0t1fy-dev-api-openapi.json#/components/schemas/ApprovedVerificationResponse",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Opaque verification identifier: the check needs it."
    },
    "object": {
      "type": "string",
      "const": "verification",
      "title": "Object",
      "description": "Always `verification`."
    },
    "to": {
      "type": "string",
      "title": "To",
      "description": "Masked number: country code and first digit, then the last two digits."
    },
    "status": {
      "type": "string",
      "const": "approved",
      "title": "Status",
      "description": "Always `approved`: every other outcome of a check is an error."
    },
    "template": {
      "type": "string",
      "title": "Template",
      "description": "The template of the SMS that carried the code."
    },
    "locale": {
      "type": "string",
      "enum": [
        "ka",
        "en"
      ],
      "title": "Locale",
      "description": "The language of that SMS."
    },
    "attempts_remaining": {
      "type": "integer",
      "title": "Attempts Remaining",
      "description": "Checks left before the code stops working: 5 at the start, one fewer for each wrong code, and 0 once the verification is no longer `pending` (approved, expired, canceled, or ended by wrong codes)."
    },
    "expires_at": {
      "type": "string",
      "title": "Expires At",
      "description": "ISO 8601 UTC: 10 minutes after the start request. No check works after it."
    },
    "approved_at": {
      "type": "string",
      "title": "Approved At",
      "description": "ISO 8601 UTC: when this check approved it."
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/$defs/VerificationError"
        },
        {
          "type": "null"
        }
      ],
      "description": "`null` unless it ended without an approval (not for `expired`)."
    },
    "message": {
      "$ref": "#/$defs/MessageResponse",
      "description": "The SMS that carried the code. Read its delivery with GET /v1/messages/{id}; show the code-entry field at once, without waiting for `delivered`."
    },
    "created_at": {
      "type": "string",
      "title": "Created At",
      "description": "ISO 8601 UTC, second precision, `Z` suffix."
    },
    "updated_at": {
      "type": "string",
      "title": "Updated At",
      "description": "ISO 8601 UTC time of the most recent change."
    }
  },
  "type": "object",
  "required": [
    "id",
    "object",
    "to",
    "status",
    "template",
    "locale",
    "attempts_remaining",
    "expires_at",
    "approved_at",
    "message",
    "created_at",
    "updated_at"
  ],
  "$defs": {
    "MessageError": {
      "properties": {
        "code": {
          "type": "string",
          "title": "Code",
          "description": "Stable machine-readable code, safe to branch on."
        },
        "message": {
          "type": "string",
          "title": "Message",
          "description": "Human-readable explanation. Wording may change; the code will not."
        }
      },
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "title": "MessageError",
      "description": "A safe, provider-neutral explanation attached to a message."
    },
    "MessageResponse": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "Opaque message identifier. Store it to read the status later."
        },
        "object": {
          "type": "string",
          "const": "message",
          "title": "Object",
          "description": "Always `message`."
        },
        "to": {
          "type": "string",
          "title": "To",
          "description": "Masked recipient: country code and first digit, then the last two digits."
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "submitted",
            "delivered",
            "undeliverable",
            "failed",
            "unknown"
          ],
          "title": "Status",
          "description": "Normalized delivery state. `submitted` means the provider accepted the request, not that a handset received it."
        },
        "segments": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Segments",
          "description": "SMS segments this message occupies — the unit the provider bills. `null` only for messages created before segment counting existed."
        },
        "error": {
          "anyOf": [
            {
              "$ref": "#/$defs/MessageError"
            },
            {
              "type": "null"
            }
          ],
          "description": "`null` unless the message failed or was undeliverable."
        },
        "created_at": {
          "type": "string",
          "title": "Created At",
          "description": "ISO 8601 UTC, second precision, `Z` suffix."
        },
        "updated_at": {
          "type": "string",
          "title": "Updated At",
          "description": "ISO 8601 UTC time of the most recent change."
        }
      },
      "type": "object",
      "required": [
        "id",
        "object",
        "to",
        "status",
        "segments",
        "created_at",
        "updated_at"
      ],
      "title": "MessageResponse",
      "description": "One message resource. Text, full recipient, and provider internals are never included."
    },
    "VerificationError": {
      "properties": {
        "code": {
          "type": "string",
          "title": "Code",
          "description": "`too_many_attempts`, `replaced` (a newer code was sent to the number), `project_claimed`, or the error of the SMS that carried the code when it was never sent (`provider_rejected`, `provider_unavailable`, …)."
        },
        "message": {
          "type": "string",
          "title": "Message",
          "description": "Human-readable explanation. Wording may change."
        }
      },
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "title": "VerificationError",
      "description": "Why a verification ended without an approval."
    }
  }
}