{
 "openapi": "3.1.0",
 "info": {
  "title": "Get Virtual Phone Number API",
  "version": "1.0.0",
  "description": "Free public phone numbers with a shared SMS inbox. No key, CORS open. New numbers every day at 00:00 UTC. Codes are shown in full for 10 minutes, then partly masked."
 },
 "servers": [
  {
   "url": "https://getvirtualphonenumber.com"
  }
 ],
 "paths": {
  "/api/v1/countries": {
   "get": {
    "operationId": "listCountries",
    "summary": "Countries with free numbers (online and used counts)",
    "responses": {
     "200": {
      "description": "Countries",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "updated": {
           "type": "string",
           "format": "date-time"
          },
          "countries": {
           "type": "array",
           "items": {
            "type": "object"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/numbers": {
   "get": {
    "operationId": "listNumbers",
    "summary": "Online numbers, newest first, optionally for one country",
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Country slug (usa, uk, canada, netherlands…) or ISO 3166-1 alpha-2 code (us, gb, ca, nl…)"
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 500
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Online numbers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total": {
           "type": "integer"
          },
          "numbers": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Number"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/numbers/used": {
   "get": {
    "operationId": "listUsedNumbers",
    "summary": "Used (offline) numbers with their SMS history still readable",
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Country slug (usa, uk, canada, netherlands…) or ISO 3166-1 alpha-2 code (us, gb, ca, nl…)"
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 500
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Used numbers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total": {
           "type": "integer"
          },
          "numbers": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Number"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sms": {
   "get": {
    "operationId": "listSms",
    "summary": "SMS received by one number, full text, newest first",
    "parameters": [
     {
      "name": "number",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "E.164, e.g. +12025550123 (encode + as %2B)"
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0
      }
     },
     {
      "name": "since",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "ISO time or unix ms"
     }
    ],
    "responses": {
     "200": {
      "description": "Messages",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "number": {
           "type": "string"
          },
          "messages": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Sms"
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Unknown number"
     }
    }
   }
  },
  "/api/v1/drops": {
   "get": {
    "operationId": "latestDrop",
    "summary": "Numbers of the latest daily drop (00:00 UTC), the next drop and the queue",
    "parameters": [
     {
      "name": "date",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Drop",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Number": {
    "type": "object",
    "properties": {
     "number": {
      "type": "string"
     },
     "country": {
      "type": "string"
     },
     "country_slug": {
      "type": "string"
     },
     "country_code": {
      "type": "string"
     },
     "dial_code": {
      "type": "string"
     },
     "added": {
      "type": "string",
      "format": "date"
     },
     "online": {
      "type": "boolean"
     },
     "offline_since": {
      "type": "string",
      "format": "date-time"
     },
     "sms_total": {
      "type": "integer"
     },
     "last_sms": {
      "type": "string",
      "format": "date-time"
     },
     "page": {
      "type": "string"
     },
     "sms_api": {
      "type": "string"
     }
    }
   },
   "Sms": {
    "type": "object",
    "properties": {
     "service": {
      "type": "string"
     },
     "from": {
      "type": "string"
     },
     "text": {
      "type": "string"
     },
     "code": {
      "type": "string"
     },
     "received": {
      "type": "string",
      "format": "date-time"
     }
    }
   }
  }
 }
}