Numbers API

Programmatically provision virtual phone numbers, manage active rentals, and validate whether numbers are rented and active.

POST

Create / Rent a Number

Allocates and activates a virtual number for your platform. The rental fee is automatically deducted from your wallet balance.

https://vchats.site/api/v1/numbers/
Automatic Billing: The cost of the rental duration is deducted immediately upon activation. Ensure your platform owner account has approved KYC and sufficient wallet balance.

Request Body (JSON)

Field Type Required Description
rental_period integer Yes Rental duration in hours (e.g. 24 for 1 day, 168 for 1 week). Alias: duration_hours.
country string Yes Country ISO code (e.g. "US", "BW", "GB"). Alias: country_code, iso_code.
number string No Optional specific number to rent (e.g. "+15550019872"). If omitted, an available number is automatically allocated.

Example Request (curl)

POST /api/v1/numbers/
curl -X POST https://vchats.site/api/v1/numbers/ \
  -H "Authorization: Bearer vn_live_<your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "rental_period": 24
  }'

Example Response (201 Created)

201 Created
{
  "id": 108,
  "number": "+15550198273",
  "status": "active",
  "duration_hours": 24,
  "activated_at": "2026-10-05T12:00:00Z",
  "expires_at": "2026-10-06T12:00:00Z",
  "country": {
    "name": "United States",
    "iso_code": "US",
    "dial_code": "+1"
  },
  "charged": {
    "amount": 2.00,
    "currency": "USD"
  },
  "wallet": {
    "remaining_balance": 18.00
  },
  "message": "Number +15550198273 successfully created and activated for 24 hours."
}

Error Responses

402 Payment Required — {"error": "insufficient_funds", "detail": "Insufficient wallet balance. Required: $2.00, current balance: $0.50. Please top up your wallet."}
403 Forbidden — {"error": "kyc_not_approved", "detail": "Your identity (KYC) has not been verified. Please submit KYC documents and wait for approval."}
400 Bad Request — {"error": "invalid_rental_period", "detail": "Duration of 5 hours is not available for United States. Available durations: [24, 168] hours."}
GET

List Rented Numbers

Returns all currently active numbers rented by your platform account.

https://vchats.site/api/v1/numbers/
curl (GET)
curl -X GET https://vchats.site/api/v1/numbers/ \
  -H "Authorization: Bearer vn_live_<your_api_key>"
200 OK
{
  "count": 1,
  "numbers": [
    {
      "id": 108,
      "number": "+15550198273",
      "status": "active",
      "duration_hours": 24,
      "activated_at": "2026-10-05T12:00:00Z",
      "expires_at": "2026-10-06T12:00:00Z",
      "country": {
        "name": "United States",
        "iso_code": "US",
        "dial_code": "+1"
      }
    }
  ]
}
GET POST

Check If a Number is Valid

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

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

Parameters

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

Example (curl GET)

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

Example Response (200 OK — Valid / Rented)

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

Example Response (200 OK — Unrented Number)

200 OK — Unrented
{
  "number": "+15550010000",
  "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."
}