OxgelAPI Public API Documentation

AI integration prompt

Integrate the OxgelAPI virtual-number REST API. Public docs are at https://oxgelapi.com/docs.html, markdown at https://oxgelapi.com/api-docs.md, and OpenAPI at https://oxgelapi.com/openapi.json. Auth header: X-API-Key: OXGL-... Store the key server-side as OXGEL_API_KEY and never expose it client-side. Build a backend proxy for GET /balance, GET /services, GET /countries, GET /prices, POST /numbers/buy, GET /numbers/status, POST /numbers/cancel and POST /numbers/finish. On the frontend, show a service and country picker, buy a number, then poll /numbers/status every 4 seconds until sms_code is returned.

Authentication

Every request must include your API key in the HTTP header X-API-Key. Do not put API keys in frontend code. In Lovable, store it as a backend/edge-function secret named OXGEL_API_KEY.

curl -H "X-API-Key: OXGL-YOUR-KEY-HERE" \
  https://oxgelapi.com/api/v1/balance

Core endpoints

Method	Path	Purpose
GET	`/balance`	Return wallet balance, escrow and currency.
GET	`/services`	List supported services such as WhatsApp, Telegram, Google, Facebook, Instagram, TikTok and OpenAI.
GET	`/countries`	List supported country codes, ISO2 values and country names.
GET	`/prices?service=wa&country=187`	Return current price and stock for a service/country.
POST	`/numbers/buy`	Rent a virtual phone number. Body: `{"service":"wa","country":"187","operator":"any"}`.
GET	`/numbers/status?id=ORDER_ID`	Poll for SMS / OTP code. Returns status and `sms_code` when received.
POST	`/numbers/cancel?id=ORDER_ID`	Cancel a waiting order and refund escrow. Allowed after 2 minutes.
POST	`/numbers/finish?id=ORDER_ID`	Mark order complete after using the code.
POST	`/numbers/another?id=ORDER_ID`	Request another SMS to the same number.

Response examples

Balance

{ "balance": 12.45, "escrow": 0.85, "currency": "USD" }

Buy number

{
  "id": "5e8b...uuid",
  "order_code": "ORD-LX9F2A",
  "phone": "+15551234567",
  "expires_at": "2026-06-03T14:23:00.000Z",
  "cost": 0.18
}

Status received

{ "status": "received", "sms_code": "482913", "phone": "+15551234567" }

Node.js quick start

const API = "https://oxgelapi.com/api/v1";
const KEY = process.env.OXGEL_API_KEY;

async function oxgel(path, options = {}) {
  const res = await fetch(`${API}${path}`, {
    ...options,
    headers: {
      "X-API-Key": KEY,
      "Content-Type": "application/json",
      ...(options.headers || {})
    }
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

const order = await oxgel("/numbers/buy", {
  method: "POST",
  body: JSON.stringify({ service: "wa", country: "187" })
});

let code = null;
for (let i = 0; i < 60 && !code; i++) {
  await new Promise(resolve => setTimeout(resolve, 4000));
  const status = await oxgel(`/numbers/status?id=${order.id}`);
  if (status.status === "received") code = status.sms_code;
}

await oxgel(`/numbers/finish?id=${order.id}`, { method: "POST" });

Support

Email support@oxgelapi.com or Telegram https://t.me/oxgelapi.