主な情報
- 1番号あたりの最安料金
- $0.0018
- 認証
- APIキー
- 形式
- HTTPS経由のJSON
- レート制限
- 1分あたり120リクエスト
- 返金
- サイトと同じ
RESTとJSON
残高、サービス、料金、番号の取得、状態、キャンセルの6つのリクエストで完結します。
キーはアカウントで発行
アカウントのAPIキーページでキーを作成し、Authorizationヘッダーで送信します。
サイトと同じ料金
番号の料金と20分の返金ルールはサイトと同じです。
送信できるリクエストは?
パスはベースURLのあとに付けます。すべてのリクエストにAPIキーが必要です。
| メソッドとパス | 内容 |
|---|---|
GET/ | USD建ての残高 |
GET/ | 全サービスと、それぞれの最安料金と対応国数 |
GET/ | あるサービスの、すべての国の番号1つ分の料金 |
POST/ | サービスと国を指定して番号を取得。料金は残高から差し引かれます |
GET/ | 番号の状態と、これまでに届いたすべてのコード |
POST/ | コードが届く前にキャンセル。料金は残高に戻ります |
APIはどの順番で呼び出しますか?
- 1
番号を取得 serviceとcountryを付けてPOST /numbers。idと番号を保存します。
- 2
番号を入力 コードを送るサービスに番号を入力します。
- 3
コードを確認 codesの一覧が空でなくなるまで、5秒ごとにGET /numbers/{id}を呼び出します。
- 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 | 2文字の国コード (例: gb) |
レスポンスのフィールドと状態
| 値 | 意味 |
|---|---|
waiting | 番号は有効で、まだコードは届いていません |
received | コードが1件以上届きました。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"]])SMS認証APIについてのよくある質問
SMS認証APIとは何ですか?
サイトの代わりに、ご自身のプログラムから番号を購入してコードを取得する方法です。
APIの利用に追加料金はかかりますか?
いいえ。番号の料金はサイトと同じで、同じ残高から支払われます。
リクエストはどのくらい送れますか?
1キーにつき1分あたり120リクエストまでです。5秒ごとの確認なら十分に収まります。
APIで取得した番号も返金されますか?
はい。ルールは同じで、20分以内にコードが届かなければ料金は残高に戻ります。
キーはどこで作成しますか?
アカウントの「APIキー」で作成します。