VerifiedCore API Reference

Quickstart

Get your first OTP in 3 steps: install the SDK, search for a number, purchase and subscribe.

1. Install

npm install @verifiedcore/sdk

2. Initialize

import VerifiedCore from '@verifiedcore/sdk'
const vc = new VerifiedCore(process.env.VC_API_KEY)

3. Search + buy + get OTP

const { numbers } = await vc.numbers.search({
  serviceSlug: 'whatsapp',
  countryCode: 'NG',
  minScore: 80,
  limit: 5,
})

Authentication

All requests require a Bearer token in the Authorization header. Get your API key from the dashboard after signing up.

# All requests require this header
Authorization: Bearer vc_live_your_api_key_here

API keys are prefixed with vc_live_ for production and vc_test_ for sandbox. Sandbox keys use mock data and never charge your wallet.

Numbers API

GET /numbers/search

Returns virtual numbers ranked by Health Score™ for a given service and country.

const { numbers } = await vc.numbers.search({
  serviceSlug: 'whatsapp',
  countryCode: 'NG',
  minScore: 80,
  limit: 5,
})

Sessions API

A session is created when you purchase a number. The 90-second SLA clock starts at session creation. If the OTP isn't delivered within 90 seconds, your wallet is automatically refunded.

POST /numbers/purchase

// Request
{ "numberId": "num_abc123" }

// Response
{
  "sessionToken": "sess_xyz789",
  "expiresAt": "2026-05-21T12:00:90Z",
  "price": 0.15,
  "currency": "USD"
}

GET /sessions/{token}

// Response
{
  "sessionToken": "sess_xyz789",
  "status": "DELIVERED",   // PENDING | DELIVERED | EXPIRED | REFUNDED
  "otp": "847291",
  "deliveredAt": "2026-05-21T12:00:04Z",
  "latencyMs": 4200,
  "healthScore": 94
}

WebSocket push

Connect to wss://api.verifiedcore.com/ws and subscribe to your session token. OTPs are pushed in real time — no polling needed.

const session = await vc.numbers.purchase({
  numberId: numbers[0].numberId
})

vc.subscribe(session.sessionToken, ({ otp, latencyMs }) => {
  console.log(`OTP: ${otp} in ${latencyMs}ms`)
})

Webhooks

Register a webhook URL in your dashboard to receive OTP delivery events as HTTP POST requests. Events: otp.delivered, sla.breached, refund.issued.

// otp.delivered payload
{
  "event": "otp.delivered",
  "sessionToken": "sess_xyz789",
  "otp": "847291",
  "latencyMs": 4200,
  "timestamp": "2026-05-21T12:00:04Z"
}

Analytics

GET /analytics/rates returns 30-day rolling delivery rates per service and country.

curl "https://api.verifiedcore.com/v1/analytics/rates?serviceSlug=whatsapp" \
  -H "Authorization: Bearer $VC_API_KEY"

eSIM API

Purchase eSIM data packages for 200+ countries. GET /esim/packages to browse, POST /esim/purchase to buy.

// GET /esim/packages?countryCode=NG
{
  "packages": [
    { "packageId": "esim_ng_1gb", "dataGb": 1, "days": 30, "priceUsd": 2.50 },
    { "packageId": "esim_ng_5gb", "dataGb": 5, "days": 30, "priceUsd": 9.99 }
  ]
}

SDKs

Error reference

Rate limits

Default: 5 requests/second per API key, burst up to 20. Enterprise plans have custom limits. Rate-limited requests return HTTP 429 with a Retry-After header.

Changelog