跳到正文
tomnumber

短信验证 API

在自己的软件中购买号码、读取验证码。API 使用同一个余额,价格和 20 分钟退款规则都与网站相同。

API 密钥在账户中创建。通过 API 购买的号码与网站使用同一余额、同样价格。

创建账户API 密钥

每个号码 $0.0018 起

主要信息

单个号码最低价
$0.0018
认证方式
API 密钥
格式
基于 HTTPS 的 JSON
频率限制
每分钟 120 次请求
退款
与网站相同

REST 和 JSON

6 个请求涵盖余额、服务、价格、获取号码、状态和取消。

在账户中创建密钥

在账户的 API 密钥页面创建密钥,并放在 Authorization 请求头中发送。

与网站价格相同

号码价格和 20 分钟退款规则与网站相同。

可以发送哪些请求?

路径接在基础 URL 之后。每个请求都需要 API 密钥。

可以发送哪些请求?
方法和路径作用
GET/balance您的余额(USD)
GET/services全部服务,附最低价和可选国家数
GET/prices?service=telegram某个服务在各国的单个号码价格
POST/numbers按服务和国家获取号码,费用从余额扣除
GET/numbers/{id}号码状态及目前收到的所有验证码
POST/numbers/{id}/cancel在收到验证码前取消,费用退回余额

API 按什么顺序调用?

  1. 1

    获取号码 用 service 和 country 调用 POST /numbers。保存返回的 id 和号码。

  2. 2

    填入号码 把号码填入要发送验证码的服务。

  3. 3

    查询验证码 每 5 秒调用一次 GET /numbers/{id},直到 codes 列表不为空。

  4. 4

    完成 使用验证码。如果在收到验证码前已不再需要这个号码,请取消。

如何获取 API 密钥?

登录后在账户中打开“API 密钥”。创建密钥后请立即复制,密钥只显示一次。生成新密钥后,旧密钥会失效。

API 密钥

基础 URL 是什么?

所有请求都发送到这个地址,并把密钥放在 Authorization 请求头(Bearer)或 X-Api-Key 请求头中:

https://tomnumber.com/api/v1
Authorization: Bearer <API_KEY>

请求字段

请求字段
字段用于值
servicePOST /numbers, GET /prices/services 返回的服务名称,例如 telegram
countryPOST /numbers两位字母的国家代码,例如 gb

响应字段和状态

响应字段和状态
值含义
waiting号码已开通,尚未收到验证码
received已收到至少一条验证码,在 expires_at 之前还可能收到更多
refunded20 分钟内未收到验证码,费用已退回余额
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_limited1 分钟内请求超过 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"

短信验证 API 常见问题

什么是短信验证 API?

一种不通过网站、而是在自己的程序中购买号码和读取验证码的方式。

API 要额外收费吗?

不收。号码价格与网站相同,并从同一个余额扣款。

可以发送多少请求?

每个密钥每分钟最多 120 次请求。每 5 秒查询一次,远低于这个限制。

通过 API 获取的号码也能退款吗?

能,规则相同:20 分钟内未收到验证码,费用退回余额。

在哪里创建密钥?

在账户的“API 密钥”中。

其他服务的虚拟号码