API Documentation | Telenumerus

Authentication

Authenticated endpoints require an API key. Pass it via any of these methods:

Authentication Methods
// Option 1: Authorization header
Authorization: Bearer your_api_key

// Option 2: X-API-Key header
X-API-Key: your_api_key

// Option 3: Request body
{ "api_key": "your_api_key" }

Get an API key by calling POST /api/v1/register — no signup UI needed.

Quick Start

Get a verified SMS code in 2 API calls:

Step 1 — RegisterPOST
curl -X POST /api/v1/register

// Response:
{
  "api_key": "vn_a1b2c3d4e5f6...",
  "balance": 0.00,
  "deposit_addresses": {
    "btc": "bc1q...",
    "ltc": "ltc1q..."
  }
}

Step 2 — One-Call VerifyPOST
curl -X POST /api/v1/verify \
  -H "Authorization: Bearer your_key" \
  -d '{"platform": "instagram"}'

// Waits for SMS, returns code automatically:
{
  "order_id": "abc-123",
  "phone": "+12025551234",
  "code": "847291",
  "status": "completed",
  "price": 0.25
}

Endpoints

GET/api/v1/services

List all available platforms and their live prices. No authentication required.

Response
{
  "service": "Telenumerus",
  "total_platforms": 33,
  "services": [
    { "platform": "instagram", "price": 0.12 },
    { "platform": "whatsapp", "price": 0.25 },
    ...
  ]
}

GET/api/v1/availability

Platform success rates, stock levels, and estimated delivery times. No auth required.

POST/api/v1/register

Create a new API account. Returns an API key and crypto deposit addresses. No auth needed.

Response
{
  "api_key": "vn_...",
  "balance": 0.00,
  "tier": "Standard",
  "deposit_addresses": { ... }
}

POST/api/v1/orderauth required

Request a phone number for a specific platform. Poll /order/:id to get the SMS code.

Parameters

platformstringrequiredPlatform name (e.g. "instagram", "whatsapp")

countrystringoptionalCountry code (default: any)

idempotency_keystringoptionalPrevents duplicate orders

Response
{
  "order_id": "abc-123-def",
  "phone": "+12025551234",
  "price": 0.25,
  "status": "active",
  "expires_at": "2026-04-07T23:30:00Z"
}

POST/api/v1/verifyauth required

All-in-one: orders a number, waits for the SMS, and returns the code. Long-poll endpoint (up to 300s).

Parameters

platformstringrequiredPlatform name

timeout_secondsnumberoptional30–300, default 120

Response
{
  "order_id": "abc-123",
  "phone": "+12025551234",
  "code": "847291",
  "status": "completed",
  "price": 0.25
}

GET/api/v1/order/:orderIdauth required

Check order status and retrieve the SMS code once received.

Response
{
  "order_id": "abc-123",
  "status": "completed",
  "phone": "+12025551234",
  "code": "847291",
  "platform": "instagram",
  "price": 0.25
}

POST/api/v1/order/:orderId/cancelauth required

Cancel an active order and receive an automatic refund to your balance.

POST/api/v1/batchauth required

Order up to 20 numbers in a single API call.

Request
{
  "api_key": "your_key",
  "orders": [
    { "platform": "instagram" },
    { "platform": "whatsapp", "country": "us" },
    { "platform": "twitter" }
  ]
}

POST/api/v1/agentauth required

Natural language ordering for AI agents. Describe what you need in plain English.

Request
{
  "api_key": "your_key",
  "query": "I need a US verification number"
}

GET/api/v1/accountauth required

Account info: balance, loyalty tier, stats, deposit addresses, and recent orders.

GET/api/v1/usageauth required

Usage analytics: per-platform breakdown and daily aggregates.

PUT/api/v1/webhookauth required

Set a webhook URL for push notifications instead of polling.

Request
{
  "api_key": "your_key",
  "url": "https://yourserver.com/webhook"
}

GET/api/v1/health

Service health check. Returns status and uptime. No auth required.

Guides

Webhooks

Configure a webhook to receive push notifications. Events are signed with HMAC-SHA256.

Event Types

sms.receivedSMS code received for an active order

order.failedOrder failed or timed out

balance.lowAccount balance below threshold

Error Codes

400Bad request — missing or invalid parameters

401Unauthorized — invalid or missing API key

402Insufficient balance

404Order or resource not found

429Rate limited — too many requests

503Service temporarily unavailable

Loyalty Tiers

Discounts are automatically applied based on your completed order count.

Standard

0–19 orders

0% off

Silver

20+ orders

5% off

Gold

50+ orders

10% off

VIP

100+ orders

15% off