Number Validation API

Check if a phone number is valid in the system. A valid number is defined as a virtual number that is already rented by a user.

GET POST https://vchats.site/api/v1/numbers/validate/

What is a valid number?

A valid number is a virtual number registered in vChats that is already rented by an active user. Unrented numbers in the pool, expired rentals, blocked numbers, or unregistered numbers are marked as invalid ("is_valid": false).

Parameters

Pass the phone number either as a query parameter (for GET) or in the JSON request body (for POST).

Parameter	Type	Required	Description
number	string	Yes	The phone number to validate in E.164 format (e.g. `+15550019872`). Aliases: `phone_number`, `destination`.
include_expired	boolean	No	Optional. Default is `false`. If set to `true`, numbers with expired user rentals will also be considered valid.

Request examples

Option 1 — GET Request

curl (GET)

curl -X GET "https://vchats.site/api/v1/numbers/validate/?number=+15550019872" \
  -H "Authorization: Bearer vn_live_..."

Option 2 — POST Request

curl (POST)

curl -X POST "https://vchats.site/api/v1/numbers/validate/" \
  -H "Authorization: Bearer vn_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+15550019872"
  }'

Response schemas

200 OK — Valid (Actively Rented Number)

JSON Response

{
  "number": "+15550019872",
  "is_valid": true,
  "rented": true,
  "status": "active",
  "country": {
    "name": "United States",
    "iso_code": "US",
    "dial_code": "+1"
  },
  "rental": {
    "id": 42,
    "status": "active",
    "activated_at": "2026-10-04T12:00:00Z",
    "expires_at": "2026-10-05T12:00:00Z",
    "duration_hours": 24
  },
  "message": "Number is valid and currently rented by a user."
}

200 OK — Invalid (Unrented Pool Number)

JSON Response

{
  "number": "+15550019872",
  "is_valid": false,
  "rented": false,
  "status": "unrented",
  "country": {
    "name": "United States",
    "iso_code": "US",
    "dial_code": "+1"
  },
  "message": "Number is registered in the system but is not rented by any user."
}

200 OK — Expired Rental

JSON Response

{
  "number": "+15550019872",
  "is_valid": false,
  "rented": false,
  "status": "expired",
  "country": {
    "name": "United States",
    "iso_code": "US",
    "dial_code": "+1"
  },
  "rental": {
    "id": 42,
    "status": "expired",
    "activated_at": "2026-10-01T12:00:00Z",
    "expires_at": "2026-10-02T12:00:00Z",
    "duration_hours": 24
  },
  "message": "Number was previously rented by a user, but the rental has expired."
}

400 Bad Request — Missing Number

JSON Response

{
  "error": "missing_number",
  "detail": "Phone number is required. Provide 'number' as a query parameter or in the request body."
}