←
NUMELIXA DEVELOPER PLATFORM

API Documentation

Production REST API at https://numelixa.com/api/v1 for virtual-number applications. Discover live inventory, exact selling prices, purchase activations from the authenticated user's wallet, retrieve SMS and manage orders.

REST / JSONAPI v1Live stockWallet billingcURLJavaScriptPythonPHPGo
Base URL
https://numelixa.com/api/v1
Authentication
Authorization: Bearer NX_API_KEY

Every account receives an API key automatically. The secret must stay on your backend.

Quick start

Authenticate → check balance → check live stock → compare price → order → poll SMS → complete or cancel.

curl "https://numelixa.com/api/v1/account" -H "Authorization: Bearer NX_API_KEY"
curl "https://numelixa.com/api/v1/stock?country=usa&service=whatsapp&operator=any" -H "Authorization: Bearer NX_API_KEY"
curl -X POST "https://numelixa.com/api/v1/orders" \
  -H "Authorization: Bearer NX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"usa","service":"whatsapp","operator":"any"}'

Authentication

Send the API key with a Bearer token. x-api-key is also accepted.

Authorization: Bearer nx_live_YOUR_SECRET_KEY
x-api-key: nx_live_YOUR_SECRET_KEY

Never expose a production key in browser JavaScript, mobile client source or public repositories. Store it as a server environment variable such as NUMELIXA_API_KEY.

1. Account & wallet

GET /account returns the current authenticated wallet balance.

curl "https://numelixa.com/api/v1/account" -H "Authorization: Bearer NX_API_KEY"
{
  "ok": true,
  "account": {
    "id": "USER_ID",
    "email": "user@example.com",
    "name": "Example User",
    "verified": true,
    "balance": 850,
    "currency": "coins"
  }
}

GET /transactions returns the latest wallet ledger entries.

curl "https://numelixa.com/api/v1/transactions" -H "Authorization: Bearer NX_API_KEY"

2. Services

GET /services returns available Numelixa services.

curl "https://numelixa.com/api/v1/services" -H "Authorization: Bearer NX_API_KEY"

3. Countries & prices

GET /countries?service=whatsapp returns countries, live stock and Numelixa selling price.

curl "https://numelixa.com/api/v1/countries?service=whatsapp" -H "Authorization: Bearer NX_API_KEY"

The price field is the amount charged from the wallet. providerCostUsd is informational only.

4. Live stock

GET /stock checks one exact country/service/operator combination.

curl "https://numelixa.com/api/v1/stock?country=usa&service=whatsapp&operator=any" -H "Authorization: Bearer NX_API_KEY"
{
  "ok": true,
  "stock": {
    "available": true,
    "count": 12,
    "country": "usa",
    "service": "whatsapp",
    "operator": "any",
    "price": 85,
    "providerCostUsd": 0.65,
    "currency": "USD"
  }
}

Always use the live price. Stock and price can change between requests.

5. Purchase a number

POST /orders purchases a real activation using the authenticated user's Numelixa wallet.

Request fields: country is the Numelixa country ID (for example usa), service is the Numelixa service ID (for example whatsapp), and operator is optional. The API validates these values before attempting a purchase.

curl -X POST "https://numelixa.com/api/v1/orders" \
  -H "Authorization: Bearer NX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"usa","service":"whatsapp","operator":"any"}'
  • country — required Numelixa country code.
  • service — required Numelixa service ID.
  • operator — optional; use any to let the number network choose.
{
  "ok": true,
  "order": {
    "id": "ORDER_ID",
    "number": "+15551234567",
    "price": 85,
    "providerCost": 0.65,
    "operator": "any",
    "expiresIn": 600,
    "stockAfter": 11
  }
}

Numelixa checks the live Numelixa quote immediately before charging the wallet. Insufficient balance returns HTTP 402. Provider/stock conflicts are returned without silently creating a fake order.

6. Orders

GET /orders lists the authenticated user's recent orders.

curl "https://numelixa.com/api/v1/orders" -H "Authorization: Bearer NX_API_KEY"

GET /orders/:id returns one order with phone, status, expiry and SMS information.

curl "https://numelixa.com/api/v1/orders/ORDER_ID" -H "Authorization: Bearer NX_API_KEY"

Orders are always scoped to the API key's own account.

7. Retrieve SMS / verification code

POST /orders/code requests the latest SMS/code for an activation.

curl -X POST "https://numelixa.com/api/v1/orders/code" \
  -H "Authorization: Bearer NX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"ORDER_ID"}'

Poll with reasonable intervals and backoff. Do not continuously hammer the API.

8. Cancel & refund

POST /orders/cancel cancels a waiting activation when allowed and refunds its Numelixa wallet cost.

curl -X POST "https://numelixa.com/api/v1/orders/cancel" \
  -H "Authorization: Bearer NX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"ORDER_ID"}'
{
  "ok": true,
  "status": "cancelled",
  "refundedCoins": 85
}

9. JavaScript / Node.js

const API = "https://numelixa.com/api/v1";
const KEY = process.env.NUMELIXA_API_KEY;

async function api(path, options = {}) {
  const res = await fetch(API + path, {
    ...options,
    headers: { Authorization: "Bearer " + KEY, "Content-Type": "application/json", ...(options.headers || {}) }
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error || "Numelixa API error");
  return data;
}

const balance = await api("/account");
const stock = await api("/stock?country=usa&service=whatsapp&operator=any");
if (!stock.stock.available) throw new Error("Out of stock");
if (stock.stock.price > balance.account.balance) throw new Error("Insufficient balance");

const order = await api("/orders", { method: "POST", body: JSON.stringify({ country:"usa", service:"whatsapp", operator:"any" }) });
console.log(order.order.number, order.order.id);

10. Python

import os
import requests

API = "https://numelixa.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["NUMELIXA_API_KEY"], "Content-Type": "application/json"}

def api(method, path, **kwargs):
    r = requests.request(method, API + path, headers=HEADERS, **kwargs)
    data = r.json()
    if not r.ok: raise RuntimeError(data.get("error", "Numelixa API error"))
    return data

balance = api("GET", "/account")
stock = api("GET", "/stock?country=usa&service=whatsapp&operator=any")
if not stock["stock"]["available"]: raise RuntimeError("Out of stock")
if stock["stock"]["price"] > balance["account"]["balance"]: raise RuntimeError("Insufficient balance")
order = api("POST", "/orders", json={"country":"usa","service":"whatsapp","operator":"any"})
print(order["order"]["number"], order["order"]["id"])

11. PHP

<?php
$api = "https://numelixa.com/api/v1";
$key = getenv("NUMELIXA_API_KEY");

function nx($method, $path, $body = null) {
  global $api, $key;
  $ch = curl_init($api . $path);
  curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER=>true, CURLOPT_CUSTOMREQUEST=>$method, CURLOPT_HTTPHEADER=>["Authorization: Bearer ".$key,"Content-Type: application/json"]]);
  if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
  $raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
  $data = json_decode($raw, true);
  if ($status >= 400) throw new Exception($data["error"] ?? "Numelixa API error");
  return $data;
}

$balance = nx("GET", "/account");
$stock = nx("GET", "/stock?country=usa&service=whatsapp&operator=any");
if (!$stock["stock"]["available"]) die("Out of stock");
if ($stock["stock"]["price"] > $balance["account"]["balance"]) die("Insufficient balance");
$order = nx("POST", "/orders", ["country"=>"usa","service"=>"whatsapp","operator"=>"any"]);
print_r($order);

12. Errors & HTTP status

200Success
400Invalid or missing request parameters
401Missing or invalid API key
402Insufficient Numelixa wallet balance
404Order/resource not found
409Out of stock, price changed, provider conflict or invalid order state
502Provider/API failure
503Temporary provider/service unavailable

13. Go

package main
import ("bytes"; "encoding/json"; "fmt"; "net/http"; "os")
func main(){b,_:=json.Marshal(map[string]string{"country":"usa","service":"whatsapp","operator":"any"});r,_:=http.NewRequest("POST","https://numelixa.com/api/v1/orders",bytes.NewReader(b));r.Header.Set("Authorization","Bearer "+os.Getenv("NUMELIXA_API_KEY"));r.Header.Set("Content-Type","application/json");res,_:=http.DefaultClient.Do(r);defer res.Body.Close();fmt.Println(res.Status)}

14. Security & production rules

  • Keep NUMELIXA_API_KEY on your server only.
  • Never commit the key to GitHub or expose it in browser/mobile source.
  • Check live stock and price immediately before ordering.
  • Use the returned order ID to retrieve the correct activation.
  • Use reasonable SMS polling intervals.
  • If compromised, use Revoke & Replace; the old key becomes invalid and a fresh key is automatically issued.
Numelixa API contract.

Every API purchase is charged from the authenticated Numelixa user's wallet. Public API responses and documentation never expose internal upstream provider identity or raw upstream errors.