Build with Numelixa
A practical reference for virtual-number workflows. Each topic has its own section, examples are separated by language, and API-key requests are designed to receive JSON—not browser login pages.
01 · Overview & authentication
All requests target the API base URL. Send your key on every request. Keep it on a private server, never inside a public frontend or distributed APK.
Base URLhttps://www.numelixa.com/api/v1
Authentication headerAuthorization: Bearer YOUR_SECRET_API_KEY
Standard headersAccept: application/jsonContent-Type: application/json for JSON request bodies.
-L / automatic redirect following to API examples. A redirect can hide a wrong URL or an authentication problem; inspect 3xx responses instead.02 · Account & balance
Verify that your key is active before starting an order. Use the balance and transaction endpoints to reconcile wallet changes.
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/account" \ -H "Authorization: Bearer $NUMELIXA_API_KEY" \ -H "Accept: application/json"
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/balance" \ -H "Authorization: Bearer $NUMELIXA_API_KEY" \ -H "Accept: application/json"
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/transactions" \ -H "Authorization: Bearer $NUMELIXA_API_KEY" \ -H "Accept: application/json"
03 · Services, countries & stock
Discover the supported catalog first. Check stock and price immediately before purchasing because availability can change.
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/services" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Accept: application/json"
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/countries?service=whatsapp" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Accept: application/json"
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/stock?country=usa&service=whatsapp" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Accept: application/json"
04 · Orders lifecycle
List orders
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/orders?limit=25" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Accept: application/json"
Purchase a number
curl --fail-with-body -sS -X POST "https://www.numelixa.com/api/v1/orders" \
-H "Authorization: Bearer $NUMELIXA_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
--data '{"country":"usa","service":"whatsapp"}'Retrieve an order
curl --fail-with-body -sS "https://www.numelixa.com/api/v1/orders/ORDER_ID" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Accept: application/json"
Request SMS code
curl --fail-with-body -sS -X POST "https://www.numelixa.com/api/v1/orders/code" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Content-Type: application/json" -H "Accept: application/json" --data '{"orderId":"ORDER_ID"}'Cancel an eligible waiting order (provider caveat)
curl --fail-with-body -sS -X POST "https://www.numelixa.com/api/v1/orders/cancel" -H "Authorization: Bearer $NUMELIXA_API_KEY" -H "Content-Type: application/json" -H "Accept: application/json" --data '{"orderId":"ORDER_ID"}'Save the returned order ID. If a purchase times out, check order history before retrying. Important: the current public cancellation route calls the 5SIM cancellation adapter directly; confirm provider compatibility before relying on it for TigerSMS-routed orders.
05 · Webhooks (event-driven integration)
A webhook lets Numelixa POST signed event notifications to the public HTTPS endpoint saved in your Developer dashboard. The current event types are order.created, order.code_received (when a code is returned by the code endpoint), and order.cancelled. Ordinary read-only GET requests do not generate webhook events.
Provide an HTTPS URL controlled by you, e.g. https://example.com/webhooks/numelixa.
Verify X-Numelixa-Signature using HMAC-SHA256 over timestamp + "." + the exact raw JSON body, with the signing secret shown once when you first save the endpoint. The header format is sha256=HEX; compare in constant time and reject stale timestamps.
Return HTTP 2xx promptly, process the work asynchronously, and make handlers idempotent.
06 · Errors, status codes & reliability
| 200/201 | Successful request |
| 400 | Invalid input or missing parameters |
| 401 | API key missing, invalid or revoked |
| 402 | Insufficient wallet balance |
| 403 | Permission or account restriction |
| 404 | Order or resource not found |
| 409 | Stock, price or order-state conflict |
| 429 (if returned) | No numeric quota or reset window is published; back off safe reads |
| 500 | Unexpected server error |
| 502/503 | Temporary upstream/service unavailability |
Use timeouts and bounded retries for safe reads. No numeric API quota or rate-limit reset window is published. If a 429 is returned by the platform, slow down and retry later. Never retry a purchase blindly after a timeout; reconcile the order first.
{ "ok": false, "error": "Human-readable error message" }07 · Language-specific examples
Choose one language. Each complete example checks the account, reads stock and creates an order. Store the API key in an environment variable.
import os
import requests
BASE = "https://www.numelixa.com/api/v1"
KEY = os.environ["NUMELIXA_API_KEY"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {KEY}",
"Accept": "application/json",
"Content-Type": "application/json",
})
def api(method, path, **kwargs):
# Do not follow redirects: an API request should return JSON directly.
response = session.request(
method, BASE + path, timeout=20, allow_redirects=False, **kwargs
)
if 300 <= response.status_code < 400:
raise RuntimeError("Unexpected redirect from API: " + response.headers.get("Location", ""))
try:
data = response.json()
except ValueError as exc:
raise RuntimeError(f"API returned non-JSON (HTTP {response.status_code})") from exc
if not response.ok or data.get("ok") is False:
raise RuntimeError(f"HTTP {response.status_code}: {data.get('error', 'API request failed')}")
return data
account = api("GET", "/account")
print("Account:", account)
stock = api("GET", "/stock?country=usa&service=whatsapp")
print("Stock:", stock)
order = api("POST", "/orders", json={"country": "usa", "service": "whatsapp"})
print("Order:", order)Security checklist
- Never expose API keys in browser JavaScript, mobile apps, screenshots or public repositories.
- Use HTTPS for your backend and webhook receiver.
- Rotate a key immediately if it may have leaked.
- Validate webhook signatures and reject duplicate event IDs.
- Keep a local order ledger and reconcile status after timeouts.