NUMELIXA DEVELOPERS · REST API V1

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.

REST · JSONBearer API keyWebhook-ready

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 URL
https://www.numelixa.com/api/v1

Authentication header
Authorization: Bearer YOUR_SECRET_API_KEY

Standard headers
Accept: application/json
Content-Type: application/json for JSON request bodies.

Do not add -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.

1. Register endpoint

Provide an HTTPS URL controlled by you, e.g. https://example.com/webhooks/numelixa.

2. Verify the request

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.

3. Acknowledge quickly

Return HTTP 2xx promptly, process the work asynchronously, and make handlers idempotent.

Delivery is attempted synchronously with a short timeout after the API event. This initial version does not automatically retry failed deliveries; use the status shown in the dashboard and retain polling as a recovery path. The test button sends a signed test event.

06 · Errors, status codes & reliability

200/201Successful request
400Invalid input or missing parameters
401API key missing, invalid or revoked
402Insufficient wallet balance
403Permission or account restriction
404Order or resource not found
409Stock, price or order-state conflict
429 (if returned)No numeric quota or reset window is published; back off safe reads
500Unexpected server error
502/503Temporary 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.
Need help? Contact developer support →
Numelixa Developer Documentation · API v1 · Use the live API contract and account permissions as the source of truth.