{
  "openapi": "3.0.3",
  "info": {
    "title": "USAVerify Pro REST API",
    "description": "Enterprise-grade USA Non-VoIP physical SIM SMS verification and OTP delivery API for automated software, bots, and registration systems.",
    "version": "1.0.0",
    "contact": {
      "name": "USAVerify Support",
      "url": "https://usaverifypro.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://usaverifypro.com/api",
      "description": "Production API Server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Enter your USAVerify Developer API Key as a Bearer token."
      }
    },
    "schemas": {
      "UserResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "example": true },
          "email": { "type": "string", "example": "user@example.com" },
          "balance": { "type": "number", "format": "float", "example": 25.50 },
          "currency": { "type": "string", "example": "USD" }
        }
      },
      "OrderRequest": {
        "type": "object",
        "required": ["service"],
        "properties": {
          "service": {
            "type": "string",
            "description": "Service code identifier (e.g. 'wa' for WhatsApp, 'tg' for Telegram, 'openai' for ChatGPT, 'go' for Google)",
            "example": "wa"
          }
        }
      },
      "OrderResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "example": true },
          "id": { "type": "string", "example": "1948201" },
          "phone": { "type": "string", "example": "+12148329910" },
          "cost": { "type": "number", "format": "float", "example": 0.75 },
          "expires_in": { "type": "integer", "example": 1200 }
        }
      },
      "CheckSmsResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "example": true },
          "status": { "type": "string", "enum": ["waiting", "received", "cancelled"], "example": "received" },
          "code": { "type": "string", "nullable": true, "example": "849201" }
        }
      },
      "CancelRequest": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": { "type": "string", "example": "1948201" },
          "status": { "type": "string", "example": "8", "description": "Status code '8' indicates manual cancellation and refund request." }
        }
      },
      "CancelResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "example": true },
          "message": { "type": "string", "example": "Order cancelled and balance refunded" }
        }
      }
    }
  },
  "paths": {
    "/me": {
      "get": {
        "summary": "Get Account Balance & Profile",
        "description": "Returns account profile details, verified status, and real-time wallet balance.",
        "responses": {
          "200": {
            "description": "Successful retrieval of user profile and balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token"
          }
        }
      }
    },
    "/order": {
      "post": {
        "summary": "Rent USA Physical Non-VoIP Number",
        "description": "Rents a real physical cellular line (AT&T, Verizon, T-Mobile) dedicated to receiving an SMS verification code for the requested service.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request or Insufficient Balance"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/check_sms": {
      "get": {
        "summary": "Check SMS OTP Code Status",
        "description": "Polls the status of an active phone number rental to retrieve the received OTP code.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "Order ID returned by /order",
            "schema": {
              "type": "string",
              "example": "1948201"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SMS status check response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckSmsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/cancel": {
      "post": {
        "summary": "Cancel Order & Auto-Refund",
        "description": "Cancels an active rental session and immediately returns 100% of the held credit to your wallet balance.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order cancelled and balance refunded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                }
              }
            }
          },
          "400": {
            "description": "Cannot cancel completed order"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    }
  }
}