NumberOTPSign In

API Documentation

Complete guide to integrating NumberOTP into your application.

Quick Navigation

Overview

NumberOTP provides three API layers for different use cases:

  • Public APIs - White-label pricing and availability (no auth required)
  • Internal APIs - User account operations (requires authentication)
  • Webhook APIs - Incoming webhooks from service providers

Base URL: https://api.numberotp.com/api

Authentication

Session-Based (NextAuth)

GET /api/user/profile
Authorization: Bearer <session-token>
Content-Type: application/json

JWT Token (Optional)

POST /api/internal/balance
Authorization: Bearer <jwt-token>
Content-Type: application/json

Public APIs

Get Prices

Fetch service prices for all countries or specific ones.

Endpoint:

GET /api/public/prices?service=telegram&country=US

Query Parameters:

  • • service (optional) - Service name
  • • country (optional) - Country code

Example Response:

{
  "success": true,
  "data": {
    "US": {
      "telegram": {
        "services": {
          "1": {
            "cost": "0.05",
            "count": "1000"
          }
        }
      }
    }
  },
  "source": "api"
}

Get Rent Prices

Fetch rental prices for specific services and durations.

Endpoint:

GET /api/public/rent-prices?service=telegram&country=US

Query Parameters:

  • • service (required) - Service name
  • • country (optional) - Country code
  • • operator (optional) - Operator name

Rate Limiting:

100 requests per 60 seconds per IP

Internal APIs (Authenticated)

Get Balance

Retrieve user account balance and credits.

Endpoint:

GET /api/internal/balance

Example Response:

{
  "success": true,
  "balance": 100.50,
  "credits": 2000,
  "freeCreditsUsed": 0,
  "isApproved": true,
  "source": "cache"
}

Rent Number

Rent a temporary number for OTP verification.

Endpoint:

POST /api/internal/rent

Request Body:

{
  "service": "telegram",
  "country": "US",
  "operator": "verizon"
}

Example Response:

{
  "success": true,
  "data": {
    "id": "12345",
    "number": "+1234567890",
    "service": "telegram",
    "country": "US",
    "expiresAt": "2024-04-29T10:00:00Z"
  },
  "remainingCredits": 1900
}

Status Codes:

  • • 200 - Number rented successfully
  • • 402 - Insufficient credits
  • • 429 - Rate limit exceeded

Get Transactions

Retrieve user transaction history with pagination.

Endpoint:

GET /api/internal/transactions?page=1&limit=20

Query Parameters:

  • • page (optional) - Page number (default: 1)
  • • limit (optional) - Items per page (default: 20, max: 100)

Rate Limiting

All API responses include rate limit information in headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1714316400

The reset timestamp is Unix epoch seconds. Different endpoints have different rate limits.

Code Examples

JavaScript/Node.js

import axios from 'axios'

const api = axios.create({
  baseURL: 'https://api.numberotp.com/api',
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  }
})

// Get prices
const prices = await api.get('/public/prices', {
  params: { service: 'telegram', country: 'US' }
})

// Get balance
const balance = await api.get('/internal/balance')

// Rent number
const rent = await api.post('/internal/rent', {
  service: 'telegram',
  country: 'US'
})

Python

import requests

BASE_URL = "https://api.numberotp.com/api"
HEADERS = {
    'Authorization': f'Bearer {session_token}',
    'Content-Type': 'application/json'
}

# Get prices
response = requests.get(
    f"{BASE_URL}/public/prices",
    params={"service": "telegram", "country": "US"}
)
prices = response.json()

# Get balance
response = requests.get(
    f"{BASE_URL}/internal/balance",
    headers=HEADERS
)
balance = response.json()

cURL

# Get prices
curl -X GET "https://api.numberotp.com/api/public/prices?service=telegram&country=US"

# Get balance (requires authentication)
curl -X GET "https://api.numberotp.com/api/internal/balance" \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json"

# Rent number
curl -X POST "https://api.numberotp.com/api/internal/rent" \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"service": "telegram", "country": "US"}'

Need Help?

If you have questions about the API or need assistance integrating NumberOTP: