番号確認API
WhatsApp番号確認の結果(API)
番号確認の結果を、タスクやステータスで絞り込みながらページごとに取得します。WhatsAppを利用している番号のエクスポート、連絡先リストからの無効な番号の削除、CRMへの結果の同期などに利用できます。
https://wbiztool.com/api/v1/verification/results/フィルターを指定しない場合、ワークスペース内のすべての確認結果が新しい順に返されます。API経由で作成したタスクだけでなく、ダッシュボードの番号確認ページで作成したタスクも含まれます。
クイック例#
curl "https://wbiztool.com/api/v1/verification/results/?campaign_id=4521&status=verified&limit=100&offset=0" \
-H "Authorization: Bearer YOUR_API_KEY"import requests
response = requests.get(
"https://wbiztool.com/api/v1/verification/results/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"campaign_id": 4521, "status": "verified", "limit": 100, "offset": 0},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 4xx or 5xx
if result["status"] == "success":
print(f"{result['returned_count']} of {result['total_count']} results")
for item in result["results"]:
print(item["number"], item["status"])
else:
print(f"Failed ({response.status_code}):", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const url = new URL("https://wbiztool.com/api/v1/verification/results/");
url.search = new URLSearchParams({ campaign_id: "4521", status: "verified", limit: "100", offset: "0" });
const response = await fetch(url, {
headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const result = await response.json(); // read the body even when the HTTP code is 4xx or 5xx
if (result.status === "success") {
console.log(`${result.returned_count} of ${result.total_count} results`);
for (const item of result.results) {
console.log(item.number, item.status);
}
} else {
console.error(`Failed (${response.status}):`, result.message);
}<?php
$query = http_build_query([
'campaign_id' => 4521,
'status' => 'verified',
'limit' => 100,
'offset' => 0,
]);
$ch = curl_init('https://wbiztool.com/api/v1/verification/results/?' . $query);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? '') === 'success') {
echo $result['returned_count'] . ' of ' . $result['total_count'] . " results\n";
foreach ($result['results'] as $item) {
echo $item['number'] . ': ' . $item['status'] . "\n";
}
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}リクエストパラメータ#
すべてのパラメータはクエリ文字列で指定します。
認証
Authorizationheader必須Bearer YOUR_API_KEY。設定 → APIキーにあるキーを使用します。代わりにクエリパラメータapi_keyでキーを渡すこともできますが、ヘッダーを使えばサーバーやプロキシのログにキーが残りません。
フィルターとページネーション
campaign_idinteger任意この番号確認タスクの番号のみを返します。APIキーと同じワークスペースの番号確認タスクである必要があります。省略すると、すべてのタスクの結果を取得します。
statusstring任意このステータスの番号のみを返します:
pending、verified、invalid。それ以外の値は無視され、ステータスによる絞り込みは行われません。unknownも同様に無視されるため、status=unknownではすべてのステータスが返ります。値は大文字と小文字が区別されます。Verifiedは無視され、すべてのステータスが返ります。limitinteger任意1ページあたりの結果数です。デフォルトは
100です。1以上の値を指定してください。offsetinteger任意スキップする結果の数です。デフォルトは
0です。0以上である必要があります。
レスポンス#
リクエストが成功すると、HTTP 200が返ります。
{
"status": "success",
"total_count": 2,
"returned_count": 2,
"limit": 100,
"offset": 0,
"has_more": false,
"results": [
{
"id": 88215,
"campaign_id": 4521,
"campaign_name": "Website leads - September",
"number": "14155550123",
"status": "verified",
"checked_at": "2026-09-16T10:16:26.730114+00:00",
"created_at": "2026-09-16T10:15:00.483101+00:00"
},
{
"id": 88213,
"campaign_id": 4521,
"campaign_name": "Website leads - September",
"number": "919876543210",
"status": "verified",
"checked_at": "2026-09-16T10:16:12.204551+00:00",
"created_at": "2026-09-16T10:15:00.482913+00:00"
}
]
}
| フィールド | 型 | 説明 |
|---|---|---|
status | string | "success"。エラーの場合は"error"が返ります。 |
total_count | integer | 全ページを通じた、フィルターに一致する結果の数。 |
returned_count | integer | このレスポンスに含まれる結果の数。 |
limit | integer | 使用されたlimit。 |
offset | integer | 使用されたoffset。 |
has_more | boolean | offset + limitがtotal_countより小さく、次のページがある場合はtrue。 |
results | array | 結果(新しい順)。 |
results[].id | integer | この確認レコードのID。 |
results[].campaign_id | integer or null | 番号が属するタスクのID。 |
results[].campaign_name | string or null | そのタスクの名前。 |
results[].number | string | 整形済みの電話番号。 |
results[].status | string | pending、verified、invalid、または確認がキャンセルされた場合はunknown。 |
results[].checked_at | string or null | 番号が確認された日時。pendingの間はnullです。 |
results[].created_at | string | 番号が追加された日時。 |
タイムスタンプは+00:00オフセット付きのUTCのISO 8601形式です。各ステータスの意味は番号ステータスの値をご覧ください。
エラー#
エラーの場合は、statusが"error"のJSONボディとHTTPエラーコードが返ります。
{ "status": "error", "message": "Campaign not found" }
| HTTP | メッセージ | 対処方法 |
|---|---|---|
405 | Only GET method allowed | GETリクエストを送信してください。 |
401 | API key required | Authorization: Bearer YOUR_API_KEYヘッダーを追加してください。 |
401 | Invalid API key | キーが存在し、削除または無効化されていないことを確認してください。 |
404 | Campaign not found | campaign_idが存在しない、番号確認タスクではない、または別のワークスペースに属しています。 |
500 | Internal server error: … | 通常は、campaign_id、limit、offsetのいずれかが整数でないか、offsetが負の値か、offset + limitが負の値です。 |
すべてのページを読み取る#
has_moreがfalseになるまで、offsetをlimitずつ増やしてください。
import requests
numbers, offset, limit = [], 0, 500
while True:
response = requests.get(
"https://wbiztool.com/api/v1/verification/results/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"campaign_id": 4521, "status": "verified", "limit": limit, "offset": offset},
timeout=60,
)
result = response.json()
if result["status"] != "success":
raise RuntimeError(result["message"])
numbers += [item["number"] for item in result["results"]]
if not result["has_more"]:
break
offset += limit
print(len(numbers), "numbers are on WhatsApp")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const numbers = [];
const limit = 500;
let offset = 0;
while (true) {
const url = new URL("https://wbiztool.com/api/v1/verification/results/");
url.search = new URLSearchParams({ campaign_id: "4521", status: "verified", limit: String(limit), offset: String(offset) });
const response = await fetch(url, { headers: { Authorization: "Bearer YOUR_API_KEY" } });
const result = await response.json();
if (result.status !== "success") throw new Error(result.message);
numbers.push(...result.results.map((item) => item.number));
if (!result.has_more) break;
offset += limit;
}
console.log(numbers.length, "numbers are on WhatsApp");ヒント#
- ページ取得時は
idで重複を除く:結果は作成日時の新しい順に並びます。同じタスクの番号はほぼ同じタイムスタンプを持ち、ページ取得中に新しい確認が追加されることもあるため、同じ行が2つのページに表示されたり、スキップされたりすることがあります。campaign_idで絞り込み、タスクの完了を待つと、これを減らせます。 - 完了を待ってからエクスポートする:
overall_statusがcompletedになるまで番号確認のステータスを確認するか、コードでpendingの結果に対応してください。 - 連絡先リストを整理する:
status=invalidをエクスポートし、次のキャンペーンの前にそれらの番号を削除しましょう。 - ページサイズ:
limitに上限はありませんが、ページが非常に大きいとレスポンスも大きく、遅くなります。
