Phone Number API

curl https://phoneborn.com/v1/balance \
  -H "X-API-Key: pb_live_xxxxxxxxxxxxxxxx"

# 200 OK
{ "balance": "25.00" }

curl https://phoneborn.com/v1/countries -H "X-API-Key: $PHONEBORN_API_KEY"

[
  {
    "iso": "GB", "name": "United Kingdom", "slug": "united-kingdom", "flag": "🇬🇧",
    "dial_code": "+44", "region": "Europe", "available": 34,
    "otp_from": "0.30",
    "from_per_month": "1.80", "from_plan": "12 months", "from_plan_code": "yearly",
    "plans": [
      { "code": "monthly", "months": 1, "days": 30, "label": "1 month", "price": "…", "per_month": "…", "saving_pct": "…" },
      { "code": "quarterly", "months": 3, "days": 90, "label": "3 months", "price": "…", "per_month": "…", "saving_pct": "…" },
      { "code": "semiannual", "months": 6, "days": 180, "label": "6 months", "price": "…", "per_month": "…", "saving_pct": "…" },
      { "code": "yearly", "months": 12, "days": 365, "label": "12 months", "price": "…", "per_month": "…", "saving_pct": "…" }
    ]
  }
]

curl -X POST https://phoneborn.com/v1/numbers \
  -H "X-API-Key: $PHONEBORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "GB", "plan": "monthly"}'

{
  "id": 912,
  "number": { "e164": "+44XX123456XX", "display": "+44 XX 1234 56XX" },
  "country": { "iso": "GB", "name": "United Kingdom", "flag": "🇬🇧" },
  "plan": "monthly",
  "price": "…",
  "started_at": "2026-09-24T10:12:03Z",
  "expires_at": "2026-10-24T10:12:03Z",
  "auto_renew": true,
  "status": "active",
  "days_left": 30,
  "label": null,
  "sms_count": 0,
  "renew_price": { "monthly": "…", "quarterly": "…", "semiannual": "…", "yearly": "…" }
}

curl "https://phoneborn.com/v1/numbers/912/sms?after_id=0" -H "X-API-Key: $PHONEBORN_API_KEY"

[
  {
    "id": 55012,
    "sender": "Telegram",
    "body": "Telegram code: 70582. Do not give this code to anyone.",
    "code": "70582",
    "received_at": "2026-09-24T10:14:41Z"
  }
]

curl -X POST https://phoneborn.com/v1/numbers/912/replace \
  -H "X-API-Key: $PHONEBORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "app_rejected"}'

{
  "event": "sms.received",
  "number": "+44XX123456XX",
  "sender": "WhatsApp",
  "body": "Your WhatsApp code is 482-913. Do not share it.",
  "code": "482913",
  "order_id": 1842
}

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.PHONEBORN_WEBHOOK_SECRET;

// Use the RAW body — re-serialised JSON will not match the signature.
app.post("/webhooks/phoneborn", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-PhoneBorn-Signature") || "";
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event === "sms.received") {
    console.log(`Code ${event.code} from ${event.sender} on ${event.number}`);
  }
  res.sendStatus(200); // respond quickly; do heavy work async
});

app.listen(3000);

import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["PHONEBORN_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/phoneborn")
def phoneborn_webhook():
    raw = request.get_data()  # raw bytes, exactly as sent
    expected = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-PhoneBorn-Signature", "")
    if not hmac.compare_digest(received, expected):
        abort(401)

    event = request.get_json()
    if event["event"] == "sms.received":
        print(f"Code {event['code']} from {event['sender']} on {event['number']}")
    return "", 200

const API = "https://phoneborn.com/v1";
const headers = { "X-API-Key": process.env.PHONEBORN_API_KEY, "Content-Type": "application/json" };

// 1. Buy a UK number on a monthly plan
const rental = await fetch(`${API}/numbers`, {
  method: "POST", headers, body: JSON.stringify({ country: "GB", plan: "monthly" }),
}).then((r) => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); });

console.log("Your number:", rental.number.e164);

// 2. Poll for new messages (or use webhooks — recommended)
let lastId = 0;
setInterval(async () => {
  const sms = await fetch(`${API}/numbers/${rental.id}/sms?after_id=${lastId}`, { headers }).then((r) => r.json());
  for (const m of sms) {
    lastId = Math.max(lastId, m.id);
    console.log(`[${m.sender}] ${m.body}`, m.code ? `→ code ${m.code}` : "");
  }
}, 5000);

import os, time, requests

API = "https://phoneborn.com/v1"
H = {"X-API-Key": os.environ["PHONEBORN_API_KEY"]}

rental = requests.post(f"{API}/numbers", json={"country": "GB", "plan": "yearly"}, headers=H)
rental.raise_for_status()
rental = rental.json()
print("Your number:", rental["number"]["e164"], "expires", rental["expires_at"])

last_id = 0
while True:
    for m in requests.get(f"{API}/numbers/{rental['id']}/sms", params={"after_id": last_id}, headers=H).json():
        last_id = max(last_id, m["id"])
        print(m["sender"], m["body"], m.get("code"))
    time.sleep(5)