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."
}