API Documentation

Authentication

Include your API key in the X-API-KEY header on every request. Get your key from API Key page.

curl -H "X-API-KEY: rn_your_key_here" https://v2.rentnumber.net/api/v1/balance

Base URL

https://v2.rentnumber.net/api/v1

---

Endpoints

GET /api/v1/balance

Get your wallet balance.

{
  "success": true,
  "balance": 5000.00,
  "currency": "NGN"
}

GET /api/v1/services

List all available services. No auth required.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "slug": "whatsapp",
      "name": "WhatsApp",
      "provider_count": 3,
      "min_price": 450.00
    }
  ]
}

GET /api/v1/countries

List all available countries. No auth required.

{
  "success": true,
  "data": [
    { "id": 1, "iso_code": "NG", "name": "Nigeria", "flag": "🇳🇬" }
  ]
}

GET /api/v1/services/{slug}/prices

Get pricing options for a service. Optional ?country_id= filter. No auth required.

GET /api/v1/services/whatsapp/prices?country_id=1

{
  "success": true,
  "service": { "id": 1, "slug": "whatsapp", "name": "WhatsApp" },
  "data": [
    {
      "id": 42,
      "final_price": 450.00,
      "stock": 120,
      "provider_id": 1,
      "provider_name": "Alpha",
      "country_id": 1,
      "country_name": "Nigeria",
      "iso_code": "NG"
    }
  ]
}

POST /api/v1/rent

Rent a number. Requires auth. Debits your wallet.

Param	Type	Description
pricing_id	int	ID from the prices endpoint (data[].id)

curl -X POST -H "X-API-KEY: rn_xxx" \
  -d "pricing_id=42" \
  https://v2.rentnumber.net/api/v1/rent

{
  "success": true,
  "rental_id": 101,
  "phone": "+2348012345678",
  "cost": 450.00,
  "status": "waiting",
  "expires_at": "2026-04-12T15:30:00Z"
}

GET /api/v1/rental/{id}

Check rental status and retrieve SMS code. Auto-polls the provider.

{
  "success": true,
  "rental_id": 101,
  "phone": "+2348012345678",
  "status": "received",
  "code": "123456",
  "sms": "Your verification code is 123456",
  "cost": 450.00,
  "created_at": "2026-04-12 14:30:00",
  "expires_at": "2026-04-12 14:45:00"
}

Status values: pending, waiting, received, completed, cancelled, expired, refunded

POST /api/v1/rental/{id}/cancel

Cancel a rental. Auto-refunds if no SMS was received.

{
  "success": true,
  "status": "refunded",
  "refunded": true,
  "amount": 450.00
}

GET /api/v1/rentals

List your rental history (last 100).

{
  "success": true,
  "data": [
    {
      "rental_id": 101,
      "service": "WhatsApp",
      "country": "Nigeria",
      "provider": "Alpha",
      "phone": "+2348012345678",
      "status": "received",
      "cost": 450.00,
      "created_at": "2026-04-12 14:30:00"
    }
  ]
}

---

Error Responses

{
  "success": false,
  "error": "Insufficient balance. Need ₦450.00"
}

HTTP status codes: 200 success, 400 bad request, 401 unauthorized, 404 not found, 502 provider error.

Rate Limits

No hard rate limit currently, but please keep requests reasonable (max ~2/sec). Excessive usage may be throttled.

Code Examples

Python

import requests

API_KEY = "rn_your_key"
BASE    = "https://v2.rentnumber.net/api/v1"
headers = {"X-API-KEY": API_KEY}

# Get balance
r = requests.get(f"{BASE}/balance", headers=headers)
print(r.json())

# Rent a number
r = requests.post(f"{BASE}/rent", headers=headers, data={"pricing_id": 42})
rental = r.json()
rental_id = rental["rental_id"]

# Poll for SMS
import time
while True:
    r = requests.get(f"{BASE}/rental/{rental_id}", headers=headers)
    data = r.json()
    if data["status"] == "received":
        print(f"Code: {data['code']}")
        break
    time.sleep(5)

PHP

$apiKey = 'rn_your_key';
$base   = 'https://v2.rentnumber.net/api/v1';

$ch = curl_init("$base/balance");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-KEY: $apiKey"],
]);
$result = json_decode(curl_exec($ch), true);
echo $result['balance'];

JavaScript

const API_KEY = 'rn_your_key';
const BASE = 'https://v2.rentnumber.net/api/v1';

const res = await fetch(`${BASE}/balance`, {
    headers: { 'X-API-KEY': API_KEY }
});
const data = await res.json();
console.log(data.balance);