{
  "openapi": "3.0.0",
  "info": {
    "title": "DQVerify — Phone Validation",
    "version": "1.0.0",
    "description": "Validate phone numbers with carrier lookup, line type detection, and portability data.\n\nNo API key required for the guest endpoint. Contact [support@dqverify.com](mailto:support@dqverify.com) for a dedicated API key with higher limits."
  },
  "servers": [
    { "url": "https://api.dqverify.com/api", "description": "Production" }
  ],
  "paths": {
    "/external/validate/phone": {
      "post": {
        "summary": "Validate a phone number",
        "description": "Returns carrier, line type (MOBILE / LANDLINE / VOIP), portability status, and geolocation.",
        "operationId": "validatePhone",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PhoneRequest" },
              "example": {
                "phone": "+12125551234",
                "country": "USA"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PhoneResponse" },
                "example": {
                  "mode": "phone_validate",
                  "tel": "+12125551234",
                  "result": {
                    "1": {
                      "TelOrigine": "+12125551234",
                      "Tel": "2125551234",
                      "Geolocation": "UNITED STATES",
                      "Type": "LANDLINE",
                      "Operator": "AT&T",
                      "OldOperator": "",
                      "Ported": "N",
                      "IdError": 1
                    }
                  }
                }
              }
            }
          },
          "429": { "description": "Guest daily limit reached (5 requests/day per IP)" },
          "422": { "description": "Invalid request body" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PhoneRequest": {
        "type": "object",
        "required": ["phone"],
        "properties": {
          "phone": {
            "type": "string",
            "description": "Phone number to validate (E.164 or local format)",
            "example": "+12125551234"
          },
          "country": {
            "type": "string",
            "description": "ISO country code (default: auto-detected from E.164 prefix)",
            "example": "USA"
          }
        }
      },
      "PhoneResponse": {
        "type": "object",
        "properties": {
          "mode": { "type": "string", "example": "phone_validate" },
          "tel": { "type": "string", "example": "+12125551234" },
          "result": {
            "type": "object",
            "description": "Key fields inside result[\"1\"]: IdError (1 = valid), Type (MOBILE / LANDLINE / VOIP), Operator, Ported, Geolocation."
          }
        }
      }
    }
  }
}
