重點資訊
- 每個號碼最低價
- $0.0018
- 驗證方式
- API 金鑰
- 格式
- 透過 HTTPS 傳送 JSON
- 請求限制
- 每分鐘 120 次請求
- 退款
- 與網站相同
REST 與 JSON
6 種請求涵蓋餘額、服務、價格、取得號碼、狀態和取消。
從帳號產生金鑰
在帳號的「API 金鑰」頁面建立金鑰,放在 Authorization 標頭傳送。
價格與網站相同
號碼價格和 20 分鐘退款規則都和網站相同。
可以傳送哪些請求?
路徑接在基礎網址後面。每個請求都需要您的 API 金鑰。
| 方法與路徑 | 功能 |
|---|---|
GET/ | 您的 USD 餘額 |
GET/ | 所有服務,附最低價和可用國家數 |
GET/ | 某項服務在各國的單一號碼價格 |
POST/ | 取得指定服務和國家的號碼,費用從餘額扣除 |
GET/ | 號碼狀態和目前收到的所有驗證碼 |
POST/ | 在收到驗證碼前取消,費用退回餘額 |
API 要依什麼順序呼叫?
- 1
取得號碼 用 service 和 country 呼叫 POST /numbers,並保存 id 和號碼。
- 2
輸入號碼 把號碼輸入要傳送驗證碼的服務。
- 3
檢查驗證碼 每 5 秒呼叫一次 GET /numbers/{id},直到 codes 清單不是空的。
- 4
完成 使用驗證碼。如果在收到驗證碼前就不需要這個號碼,請取消。
基礎網址是什麼?
所有請求都傳送到這個網址,並把金鑰放在 Authorization 標頭(Bearer)或 X-Api-Key 標頭:
https://tomnumber.com/api/v1Authorization: Bearer <API_KEY>請求欄位
| 欄位 | 使用於 | 值 |
|---|---|---|
service | POST /numbers, GET /prices | /services 裡的服務名稱,例如 telegram |
country | POST /numbers | 兩個字母的國家代碼,例如 gb |
回應欄位與狀態
| 值 | 意義 |
|---|---|
waiting | 號碼已開啟,尚未收到驗證碼 |
received | 至少收到一個驗證碼;在 expires_at 之前還可能收到更多 |
refunded | 20 分鐘內沒收到驗證碼,費用已退回餘額 |
canceled | 您在收到驗證碼前取消,費用已退回餘額 |
回應範例
{ "ok": true, "id": "R8KQ2M7XWD4P", "service": "telegram", "country": "gb", "number": "+44 7700 900412", "price": "0.167", "status": "received", "expires_at": "2026-11-11T09:20:00.000Z", "codes": [ { "code": "483920", "text": "Telegram code: 483920", "received_at": "2026-11-11T09:01:12.000Z" } ]}錯誤代碼
unauthorized | 缺少 API 金鑰或金鑰錯誤 |
rate_limited | 一分鐘內超過 120 次請求 |
bad_service | 未知的服務名稱 |
bad_country | 該服務不提供這個國家 |
low_balance | 餘額低於價格 |
unavailable | 目前沒有可用號碼,未扣任何費用 |
not_found | 您的帳號裡沒有這個 id 的號碼 |
cannot_cancel | 已收到驗證碼,或號碼已關閉 |
程式碼範例
# get a numbercurl -X POST https://tomnumber.com/api/v1/numbers \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"service":"telegram","country":"gb"}' # check for codescurl https://tomnumber.com/api/v1/numbers/R8KQ2M7XWD4P \ -H "Authorization: Bearer $API_KEY"const api = (path, init = {}) => fetch("https://tomnumber.com/api/v1" + path, { ...init, headers: { Authorization: "Bearer " + process.env.API_KEY, "Content-Type": "application/json" }, }).then((r) => r.json()); const n = await api("/numbers", { method: "POST", body: JSON.stringify({ service: "telegram", country: "gb" }) });console.log(n.number); // enter this number in the app let codes = [];while (!codes.length) { await new Promise((r) => setTimeout(r, 5000)); const s = await api("/numbers/" + n.id); if (s.status === "refunded" || s.status === "canceled") break; codes = s.codes;}console.log(codes.map((c) => c.code));import os, time, requests API = "https://tomnumber.com/api/v1"H = {"Authorization": "Bearer " + os.environ["API_KEY"]} n = requests.post(API + "/numbers", json={"service": "telegram", "country": "gb"}, headers=H).json()print(n["number"]) # enter this number in the app while True: time.sleep(5) s = requests.get(API + "/numbers/" + n["id"], headers=H).json() if s["codes"] or s["status"] in ("refunded", "canceled"): breakprint([c["code"] for c in s["codes"]])簡訊驗證 API 常見問題
什麼是簡訊驗證 API?
讓您不用透過網站,而是用自己的程式購買號碼、讀取驗證碼的方式。
API 要另外收費嗎?
不用。號碼價格和網站相同,從同一個餘額扣款。
可以傳送多少次請求?
每個金鑰每分鐘最多 120 次。每 5 秒查詢一次遠低於這個上限。
API 購買的號碼也會退款嗎?
會,規則相同:20 分鐘內沒收到驗證碼,費用就退回餘額。
要在哪裡建立金鑰?
在帳號裡的「API 金鑰」。