{
  "openapi": "3.0.3",
  "info": {
    "title": "Phone Number Validation & Formatter API",
    "version": "1.0.0",
    "description": "Validate, parse, and format phone numbers for 230+ countries using libphonenumber-js. Supports E.164, INTERNATIONAL, NATIONAL, and RFC3966 format output. Detects number type (mobile, fixed-line, toll-free, etc.), extracts country code and national number, and returns all available formats in a single info call.\n",
    "contact": {
      "name": "Phone Number API Support",
      "email": "api@hiroapp.cc"
    }
  },
  "servers": [
    {
      "url": "https://api.sprytools.com/v1/phone",
      "description": "Production (SpryTools API Gateway)"
    }
  ],
  "tags": [
    {
      "name": "Validation",
      "description": "Validate phone numbers"
    },
    {
      "name": "Parsing",
      "description": "Parse and normalize phone numbers"
    },
    {
      "name": "Formatting",
      "description": "Format phone numbers"
    },
    {
      "name": "Info",
      "description": "Full phone number information"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "RapidApiProxy": []
    }
  ],
  "paths": {
    "/api/v1/validate": {
      "get": {
        "operationId": "validatePhone",
        "summary": "Validate a phone number",
        "description": "Check whether a phone number is valid for the given (or auto-detected) country.",
        "tags": [
          "Validation"
        ],
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": true,
            "description": "Phone number to validate (with or without country code)",
            "schema": {
              "type": "string"
            },
            "example": "+49891234567"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 country code hint (e.g. DE, US). Required for national-format numbers.",
            "schema": {
              "type": "string"
            },
            "example": "DE"
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResult"
                },
                "examples": {
                  "valid": {
                    "value": {
                      "number": "+49891234567",
                      "valid": true,
                      "country": "DE",
                      "type": "FIXED_LINE"
                    }
                  },
                  "invalid": {
                    "value": {
                      "number": "12345",
                      "valid": false,
                      "country": null,
                      "reason": "NOT_A_NUMBER"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/parse": {
      "get": {
        "operationId": "parsePhone",
        "summary": "Parse and normalize a phone number",
        "description": "Parse a phone number and return its normalized components (country code, national number, E.164 form).",
        "tags": [
          "Parsing"
        ],
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": true,
            "description": "Phone number to parse",
            "schema": {
              "type": "string"
            },
            "example": "+49891234567"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country code hint for national-format numbers",
            "schema": {
              "type": "string"
            },
            "example": "DE"
          }
        ],
        "responses": {
          "200": {
            "description": "Parsed phone number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseResult"
                },
                "example": {
                  "number": "+49891234567",
                  "valid": true,
                  "countryCallingCode": "49",
                  "nationalNumber": "891234567",
                  "country": "DE",
                  "e164": "+49891234567"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/format": {
      "get": {
        "operationId": "formatPhone",
        "summary": "Format a phone number in a specific format",
        "description": "Format a phone number as E.164, INTERNATIONAL, NATIONAL, or RFC3966.\n",
        "tags": [
          "Formatting"
        ],
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": true,
            "description": "Phone number to format",
            "schema": {
              "type": "string"
            },
            "example": "+49891234567"
          },
          {
            "name": "format",
            "in": "query",
            "required": true,
            "description": "Output format",
            "schema": {
              "type": "string",
              "enum": [
                "E.164",
                "INTERNATIONAL",
                "NATIONAL",
                "RFC3966"
              ]
            },
            "example": "INTERNATIONAL"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country code hint",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Formatted phone number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormatResult"
                },
                "example": {
                  "number": "+49891234567",
                  "format": "INTERNATIONAL",
                  "formatted": "+49 89 1234567"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/info": {
      "get": {
        "operationId": "phoneInfo",
        "summary": "Full phone number information",
        "description": "Returns complete phone number information: validation status, type, country, all format variants (E.164, INTERNATIONAL, NATIONAL, RFC3966), and country calling code.\n",
        "tags": [
          "Info"
        ],
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": true,
            "description": "Phone number to inspect",
            "schema": {
              "type": "string"
            },
            "example": "+49891234567"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country code hint",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full phone number info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InfoResult"
                },
                "example": {
                  "number": "+49891234567",
                  "valid": true,
                  "country": "DE",
                  "countryCallingCode": "49",
                  "nationalNumber": "891234567",
                  "type": "FIXED_LINE",
                  "formats": {
                    "e164": "+49891234567",
                    "international": "+49 89 1234567",
                    "national": "089 1234567",
                    "rfc3966": "tel:+49-89-1234567"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "RapidApiProxy": {
        "type": "apiKey",
        "in": "header",
        "name": "x-rapidapi-proxy-secret"
      }
    },
    "schemas": {
      "ValidateResult": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ParseResult": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "countryCallingCode": {
            "type": "string",
            "nullable": true
          },
          "nationalNumber": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "e164": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "FormatResult": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "formatted": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "InfoResult": {
        "type": "object",
        "properties": {
          "number": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "countryCallingCode": {
            "type": "string",
            "nullable": true
          },
          "nationalNumber": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "nullable": true
          },
          "formats": {
            "type": "object",
            "properties": {
              "e164": {
                "type": "string",
                "nullable": true
              },
              "international": {
                "type": "string",
                "nullable": true
              },
              "national": {
                "type": "string",
                "nullable": true
              },
              "rfc3966": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request — missing or invalid parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "'number' query param is required"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "API key missing",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "API key required"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded (100 requests per minute)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Rate limit exceeded"
            }
          }
        }
      }
    }
  }
}