API

仮想番号サービスの事実上の標準プロトコルに準拠したREST APIです。既存クライアントのベースURLとキーを差し替えるだけで動きます。

いまお使いのクライアントをそのまま向けてください

ベースURLとトークンの2行を変えるだけで、クライアントの既存の呼び出しはそのまま動きます。パス、クエリパラメータ、JSONのフィールド名、エラー文字列まで同じです。

ベースURL

https://otphub-api.43.203.247.133.nip.io/v1

認証

すべてのリクエストで、キーをBearerトークンとして送信してください。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" -H "Accept: application/json" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

クイックスタート

アカウントページでキーを作成し、環境変数に設定してから番号を購入します。

クイックスタート

export OTPHUB_KEY="your-api-key"

# 1. what is in stock
curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

# 2. buy a number
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook"

# 3. poll it until the code lands
curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

エンドポイント

未認証

GET/v1/guest/countriesトークン不要

取り扱うすべての国と、国番号、対応する通信事業者。

リクエスト

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/countries"

レスポンス

{
  "england": {
    "iso": { "gb": 1 },
    "prefix": { "+44": 1 },
    "text_en": "England",
    "text_ru": "England",
    "vodafone": { "activation": 1 }
  }
}

GET/v1/guest/products/{country}/{operator}トークン不要

指定した国と通信事業者で利用できるサービス、在庫数、料金。どちらのセグメントにもanyを指定できます。

リクエスト

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/products/england/any"

レスポンス

{
  "1day":     { "Category": "hosting",    "Qty": 14,  "Price": 80 },
  "facebook": { "Category": "activation", "Qty": 133, "Price": 21 }
}

GET/v1/guest/prices?country=&product=トークン不要

国 → サービス → 通信事業者の順にネストした全料金表。countryやproductで絞り込めます。

リクエスト

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/prices?country=england&product=facebook"

レスポンス

{
  "england": {
    "facebook": {
      "vodafone": { "cost": 21, "count": 1260, "rate": 99.99 }
    }
  }
}

GET/v1/guest/flash/{lang}トークン不要

指定した言語での、現在のサイトのお知らせ。

リクエスト

curl "https://otphub-api.43.203.247.133.nip.io/v1/guest/flash/en"

アカウント

GET/v1/user/profileBearerトークン

残高、仮押さえ額、レーティング、既定値。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/profile"

レスポンス

{
  "id": 1,
  "email": "you@example.com",
  "vendor": "otphub",
  "default_forwarding_number": "",
  "balance": 100,
  "rating": 96,
  "default_country": { "name": "england", "iso": "gb", "prefix": "+44" },
  "default_operator": { "name": "" },
  "frozen_balance": 0
}

GET/v1/user/orders?category=&limit=&offset=&order=&reverse=Bearerトークン

注文履歴（新しい順）。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/orders?category=activation&limit=25"

レスポンス

{ "Data": [ /* orders */ ], "ProductNames": [], "Statuses": [], "Total": 3 }

GET/v1/user/payments?limit=&offset=&order=&reverse=Bearerトークン

チャージや調整の台帳エントリ。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/payments?limit=25"

レスポンス

{
  "Data": [
    {
      "ID": 30011934,
      "TypeName": "charge",
      "ProviderName": "admin",
      "Amount": 100,
      "Balance": 100,
      "CreatedAt": "2026-08-17T15:37:08.149895Z"
    }
  ],
  "PaymentTypes": [{ "Name": "charge" }],
  "PaymentProviders": [{ "Name": "admin" }],
  "Total": 1
}

GET/v1/user/max-pricesBearerトークン

サービスごとに設定した上限金額。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices"

レスポンス

[{ "id": 14, "product": "facebook", "price": 11, "CreatedAt": "2026-08-17T15:37:08Z" }]

POST/v1/user/max-pricesBearerトークン

1つのサービスに上限を設定します。上限を超える購入は拒否されます。

リクエスト

curl -X POST "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook","price":30}'

DELETE/v1/user/max-pricesBearerトークン

上限を削除します。

リクエスト

curl -X DELETE "https://otphub-api.43.203.247.133.nip.io/v1/user/max-prices" \
  -H "Authorization: Bearer $OTPHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_name":"facebook"}'

購入

GET/v1/user/buy/activation/{country}/{operator}/{product}Bearerトークン

使い切りの認証番号を購入します。電話番号を含む注文を返します。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" \
  "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/activation/england/any/facebook?maxPrice=30"

レスポンス

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/buy/hosting/{country}/{operator}/{product}Bearerトークン

3hours、1day、10days、1monthのいずれかの期間で番号をレンタルします。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/buy/hosting/england/any/1day"

GET/v1/user/reuse/{product}/{number}Bearerトークン

通信事業者が許可している場合、同じサービスで同じ番号をもう一度購入します。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/reuse/facebook/447350690992"

注文管理

GET/v1/user/check/{id}Bearerトークン

新しいメッセージがないか注文をポーリングします。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/check/11631253"

レスポンス

{
  "id": 11631253,
  "phone": "+447350690992",
  "operator": "vodafone",
  "product": "facebook",
  "price": 21,
  "status": "PENDING",
  "expires": "2026-08-17T08:28:38.809469028Z",
  "sms": null,
  "created_at": "2026-08-17T08:13:38.809469028Z",
  "forwarding": false,
  "forwarding_number": "",
  "country": "england"
}

GET/v1/user/finish/{id}Bearerトークン

使い終えた注文を閉じます。仮押さえ分が課金されます。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/finish/11631253"

GET/v1/user/cancel/{id}Bearerトークン

SMSが届く前にキャンセルします。仮押さえは解除されます。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/cancel/11631253"

GET/v1/user/ban/{id}Bearerトークン

使用済みの番号として報告します。仮押さえが解除され、番号は在庫から外れます。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/ban/11631253"

GET/v1/user/sms/inbox/{id}Bearerトークン

レンタルした番号に届いたすべてのメッセージ。

リクエスト

curl -H "Authorization: Bearer $OTPHUB_KEY" "https://otphub-api.43.203.247.133.nip.io/v1/user/sms/inbox/11631253"

レスポンス

{
  "Data": [
    {
      "ID": 1,
      "created_at": "2026-08-17T17:23:25.106597Z",
      "date": "2026-08-17T17:23:15Z",
      "sender": "Facebook",
      "text": "Use 415127 as your login code",
      "code": "415127",
      "is_wave": false,
      "wave_uuid": ""
    }
  ],
  "Total": 1
}

注文ステータス

すべての購入はこれらの状態を通ります。以下の文字列は、APIが実際に返す値そのものです。

ステータス	説明
`PENDING`待機中	番号は有効で、SMSの受信を待っています。
`RECEIVED`コード受信	コードが1件以上届きました。
`CANCELED`キャンセル済み	キャンセルされ、仮押さえは解除されました。
`TIMEOUT`時間切れ	時間内にSMSが届かなかったため返金しました。
`FINISHED`完了	完了しました。購入分が課金されています。
`BANNED`報告済み	使用済みとして報告され、返金しました。

エラー

失敗時は標準プロトコルと同じく、理由だけを記したプレーンテキストを返します。

エラー本文	返却される条件
`no free phones`	その国・通信事業者・サービスの組み合わせに在庫がありません。
`not enough user balance`	残高が料金に足りません。
`not enough rating`	レーティングが0です。24時間後に注文できるようになります。
`select country`	国のセグメントが空でした。
`select operator`	通信事業者のセグメントが空でした。
`bad country`	その国のスラッグはカタログにありません。
`bad operator`	その通信事業者のスラッグはカタログにありません。
`no product`	そのサービスのスラッグはカタログにありません。
`server offline`	仕入先に接続できません。
`order not found`	そのIDの注文はこのアカウントにありません。
`order expired`	注文が有効期限を過ぎています。
`order has sms`	すでにメッセージが届いているため、注文をキャンセルできません。
`hosting order`	レンタル注文では使えない呼び出しです。
`reuse not possible`	通信事業者がこの番号の再利用を許可していません。
`reuse false`	元の注文が再利用オプションなしで購入されています。
`reuse expired`	この番号の再利用可能な期間が終了しています。

レート制限

APIキーごとに毎秒100リクエストです。過度な連続アクセスは一時的に制限されます。

IPごとに毎秒100リクエスト、超えると503。
APIキーごとに毎秒100リクエスト、超えると429。
アカウント全体で毎秒100件までの購入。
10分以内に5回上限に達すると、そのキーは10分間ブロックされます。

そのまま使える互換性

パス、JSONの構造、エラー文字列まで標準プロトコルと完全に一致します。先頭が大文字のキーやプレーンテキストのエラー本文もそのままです。既存のクライアントライブラリは変更不要です。