Developer API Documentation

Integrate virtual phone numbers for SMS reception directly into your software with our zero-latency API endpoints.

Interactive Playground

Test endpoints instantly in your browser using our built-in Scalar API environment.

Developer Dashboard

Manage your API keys, track monthly usage, and configure Global Webhooks.

1Authentication

All endpoints under https://numberotp.com/v1 require authentication via an API Key generated from your Developer Dashboard.

You must pass the API key in the standard Authorization header using the Bearer scheme.

Authorization: Bearer notp_1234567890abcdef

2Core Public APIs

GET/v1/public/services

Fetch a list of all available services (WhatsApp, Telegram, etc). Optionally pass ?country= query param to filter.

GET/v1/public/countries

Fetch a list of all available countries. Optionally pass ?service= to only show countries supporting a specific service.

GET/v1/public/prices

Fetch real-time pricing and availability for all services and countries. Does not require an API key.

POST/v1/activations

Provision a virtual phone number for SMS reception. Returns the Phone Number and Activation ID. Balance is deducted instantly.

GET/v1/activations/{id}

Poll the status of an activation. Safely requests the latest OTP status. Ideal for developers preferring manual polling loops over Webhooks.

GET/v1/activations/{id}/wait

Long-Polling endpoint. This connection will hang open (up to 55 seconds) and instantly return once the OTP arrives, preventing you from having to hit the server constantly.

3Zero-Latency Webhooks

To provide the absolute fastest delivery of OTP codes, NumberOTP employs a **Global Webhooks** architecture. When our infrastructure catches an SMS intended for your active number, we will instantly POST the payload to your pre-configured Webhook URL.

1. Setup

Navigate to your Developer Dashboard and enter your public server URL (e.g. https://api.yourstartup.com/webhook/numberotp) in the Global Webhook section.

2. Webhook Payload

When an OTP is received, we will POST the following JSON structure to your endpoint:

{
  "id": "act_8f7d98x",
  "phone_number": "14155552671",
  "service": "wa",
  "country": "67",
  "otp": "482910",
  "full_sms": "Your WhatsApp code is 482910.",
  "status": "received"
}

3. Security & Signatures (HMAC SHA-256)

To verify the webhook payload is genuinely from NumberOTP and has not been tampered with, we sign every payload using HMAC SHA-256 mapped to your unique **Webhook Secret** (available in your dashboard).

We include this signature in the request headers:

x-numberotp-signature: sha256=10f4be...

Node.js Verification Example

const crypto = require('crypto');

function verifyWebhook(reqBody, signatureHeader, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(reqBody))
    .digest('hex');
    
  const expectedSignature = `sha256=${hash}`;
  
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader), 
    Buffer.from(expectedSignature)
  );
}