主要信息
- 单个号码最低价
- $0.0018
- 认证方式
- API 密钥
- 格式
- 基于 HTTPS 的 JSON
- 频率限制
- 每分钟 120 次请求
- 退款
- 与网站相同
REST 和 JSON
6 个请求涵盖余额、服务、价格、获取号码、状态和取消。
在账户中创建密钥
在账户的 API 密钥页面创建密钥,并放在 Authorization 请求头中发送。
与网站价格相同
号码价格和 20 分钟退款规则与网站相同。
可以发送哪些请求?
路径接在基础 URL 之后。每个请求都需要 API 密钥。
| 方法和路径 | 作用 |
|---|---|
GET/ | 您的余额(USD) |
GET/ | 全部服务,附最低价和可选国家数 |
GET/ | 某个服务在各国的单个号码价格 |
POST/ | 按服务和国家获取号码,费用从余额扣除 |
GET/ | 号码状态及目前收到的所有验证码 |
POST/ | 在收到验证码前取消,费用退回余额 |
API 按什么顺序调用?
- 1
获取号码 用 service 和 country 调用 POST /numbers。保存返回的 id 和号码。
- 2
填入号码 把号码填入要发送验证码的服务。
- 3
查询验证码 每 5 秒调用一次 GET /numbers/{id},直到 codes 列表不为空。
- 4
完成 使用验证码。如果在收到验证码前已不再需要这个号码,请取消。
基础 URL 是什么?
所有请求都发送到这个地址,并把密钥放在 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 | 1 分钟内请求超过 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 密钥”中。