NexNum Logo
NexNum
Dashboard
Developer Portal & Reference

Build With The
NexNum API v1

Complete RESTful interface providing direct access to real-SIM carrier numbers, instant SMS OTP activations, 180+ country catalogs, and provider pricing matrices.

< 120ms
Avg API Latency
180+
Supported Nations
500+
Active Services
Quickstart Example
// Purchase WhatsApp Number (India)
curl -X GET "https://nexnum.in/api/v1?action=getNumber&service=wa&country=in" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Output:
"ACCESS_NUMBER:98472910:+919876543210"
Direct Carrier Route20-Min Expiration

Quickstart & Base Endpoint

Wire protocol and global API parameters

The NexNum Public API v1 implements a high-throughput, provider-compatible wire protocol. All requests originate from the primary base URL:

https://nexnum.in/api/v1
Plain Text Output (`text/plain`)

Used for single line responses like `ACCESS_NUMBER` and `ACCESS_BALANCE` for direct legacy compatibility.

JSON Output (`application/json`)

Used for structured catalog lookups (`getPrices`, `getServicesList`, `getCountriesList`).

Authentication & API Keys

Securing your requests with Bearer Tokens

Authenticate your requests using an API Key generated from your NexNum User Dashboard. You can provide your key in two ways:

Method 1: Authorization Header (Recommended)Authorization: Bearer nx_live_98a72b10f...
Method 2: Query ParameterGET https://nexnum.in/api/v1?action=getBalance&api_key=nx_live_98a72b10f...

API Action References

Detailed documentation for all 9 v1 provider actions

GET

Get Wallet Balance

Retrieves current available wallet credit balance for the authenticated user API key in formatted currency units.

action=getBalancescope: read

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getBalance&api_key=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (text/plain)

ACCESS_BALANCE:25.50
GET

Purchase Virtual Number

Allocates a new virtual line from real SIM carrier inventory for a specific service and country.

action=getNumberscope: numbers

Request Parameters

ParameterTypeRequiredDescription
servicestring | numberYesTarget service code (e.g. wa, tg, go) or numeric service ID.
countrystring | numberYesTarget country code (e.g. in, us, uk) or numeric country ID.
operatorstring | numberOptionalOptional carrier operator filter code.
maxPricenumberOptionalMaximum acceptable price in points. Rejects offer if cost exceeds this cap.

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getNumber&api_key=YOUR_API_KEY&service=wa&country=in" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (text/plain)

ACCESS_NUMBER:98472910:+919876543210
GET

Set Activation Status

Updates activation line lifecycle state (mark ready, retry code, complete line, or cancel & refund).

action=setStatusscope: numbers

Request Parameters

ParameterTypeRequiredDescription
idstringYesActive activation ID returned during getNumber.
statusnumberYesStatus code: 1 (Ready), 3 (Retry Code), 6/8 (Complete), -1 (Cancel & Refund).

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=setStatus&api_key=YOUR_API_KEY&id=98472910&status=6" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (text/plain)

ACCESS_ACTIVATION
GET

Poll Received SMS & Code

Polls real-time SMS inbox for an active line to inspect verification codes and delivery state.

action=getStatusscope: sms

Request Parameters

ParameterTypeRequiredDescription
idstringYesTarget activation ID.

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getStatus&api_key=YOUR_API_KEY&id=98472910" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (application/json)

{
  "status": true,
  "message": "STATUS_OK:847291"
}
GET

List Supported Services

Returns list of all 500+ supported services with numeric IDs, names, codes, and icon paths.

action=getServicesListscope: read

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getServicesList&api_key=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (application/json)

{
  "services": [
    { "id": 1, "name": "WhatsApp", "code": "wa", "serviceIcon": "/assets/icons/services/wa.svg" },
    { "id": 2, "name": "Telegram", "code": "tg", "serviceIcon": "/assets/icons/services/tg.svg" }
  ]
}
GET

List Supported Countries

Returns list of all 180+ supported countries with numeric IDs, ISO codes, and flag icons.

action=getCountriesListscope: read

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getCountriesList&api_key=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (application/json)

{
  "countries": [
    { "id": 1, "name": "India", "code": "in", "flagIcon": "/assets/icons/flags/in.svg" },
    { "id": 2, "name": "United States", "code": "us", "flagIcon": "/assets/icons/flags/us.svg" }
  ]
}
GET

Get Real-Time Price Matrix

Returns live carrier prices, available line counts, and provider breakdown grouped by country and service.

action=getPricesscope: read

Request Parameters

ParameterTypeRequiredDescription
countrystring | numberOptionalFilter matrix by specific country code or ID.
servicestring | numberOptionalFilter matrix by specific service code or ID.

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getPrices&api_key=YOUR_API_KEY&country=in&service=wa" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (application/json)

{
  "1": {
    "1": {
      "price": 5.00,
      "count": 1420,
      "providers": {
        "1000": { "count": 1420, "price": 5.00, "provider_id": "1000", "provider_name": "GrizzlySMS" }
      }
    }
  }
}
GET

Get Active User Lines

Returns real-time status and message histories for all active numbers owned by the API key user.

action=getNumbersStatusscope: numbers

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getNumbersStatus&api_key=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (application/json)

{
  "98472910": {
    "phone": "+919876543210",
    "countryId": 1,
    "countryName": "India",
    "serviceName": "WhatsApp",
    "status": "received",
    "sms": [
      { "sender": "WhatsApp", "code": "847291", "content": "Your code is 847291", "receivedAt": "2026-07-30T15:30:00Z" }
    ]
  }
}
GET

List Active Carrier Networks

Returns registry of active carrier networks and provider codes currently supplying SMS routes.

action=getProvidersscope: read

Code Examples

curl -X GET "https://nexnum.in/api/v1?action=getProviders&api_key=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Sample (application/json)

{
  "providers": [
    { "id": "1000", "name": "GrizzlySMS" },
    { "id": "1001", "name": "5sim" }
  ]
}

Interactive API Playground

Test parameters and generate custom requests

https://nexnum.in/api/v1?action=getNumber&api_key=nx_live_98a72b10f...&service=wa&country=in

Error Codes Reference

Standard API error messages & resolution steps

Error CodeHTTPDescription & Resolution
NO_KEY200 / 401API key was not supplied in header or query string.
BAD_KEY200 / 403API key is invalid, disabled, or lacks required permission scope.
BAD_SERVICE200Invalid service or country code supplied during getNumber.
NO_NUMBERS200No available carrier lines matching filter or price exceeds maxPrice cap.
NO_BALANCE200Insufficient wallet credit balance to complete purchase.
NO_ACTIVATION200Activation ID not found or not owned by user API key.