顧客向け API

今すぐ始める

API キーでテストキーを作成してサーバー上に保管し、FAIRVALID_API_KEY と FAIRVALID_BASE_URL を設定してください。テストキーは予約済みの @example.com アドレスで動作します。プロバイダーへの呼び出しは行われず、クレジットも消費しません。

curl -X POST "$FAIRVALID_BASE_URL/api/v1/jobs" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY" \
  -H "Idempotency-Key: my-import-2026-10-05" \
  -H "Content-Type: application/json" \
  -d '{"emails":["deliverable@example.com","pending@example.com"]}'

本番環境では、submit スコープを持つ Live キーを作成し、/api/v1/jobs または /api/v1/verifications を使用してください。ジョブの状態と結果を読み取るには read スコープを追加してください。

新しいジョブではHTTP 202とUUID job_idが返されます。一致する再試行ではHTTP 200と同じジョブが返されます。レスポンスにはversion: v1、brand: FairValid、およびno-storeヘッダーが含まれます。

キーと利用上限

サーバーから Authorization: Bearer fv_live_… または Bearer fv_test_… を渡してください。完全なシークレットは一度しか表示されません。本番キーには submit、read、balance のスコープを設定できます。無効化されたキーでは新しいリクエストができなくなります。テストキーでは、そのキー自身のシミュレーションジョブにアクセスできます。

本番キーの累計上限には、すでに消費されたクレジットと、受け付けた一意のIDのために確保されたクレジットが含まれます。上限によってワークスペースにクレジットが追加されることはありません。上限を超える新しいリクエストには、ジョブやクレジットの確保を作成せずにHTTP 402 key_cap_reachedが返されます。上限を下げると新しい作業はブロックされますが、受け付け済みの作業は継続されます。

ライブジョブでは、ワークスペースの検証キューとクレジット残高を使用します。キーのスコープ、キーの上限、ワークスペースへのアクセス権、処理の制限は引き続き適用されます。ワークスペースのクレジットは、チェックが処理対象として受け付けられた時点で確保されます。結果には、ダッシュボードと同じ消費および返却のルールが適用されます。

運用上の一時停止中は、新しいライブ送信に対してクレジットを確保せずにHTTP 503 live_verification_unavailableが返される場合があります。後ほど同じIdempotency-Keyで再試行してください。

ジョブと結果

curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"
curl "$FAIRVALID_BASE_URL/api/v1/jobs/$JOB_ID/results" \
  -H "Authorization: Bearer $FAIRVALID_API_KEY"

next_cursor を cursor クエリパラメーターとして渡してください。元のフィルターと検索条件が引き継がれます。フィルターは all、valid、invalid、catch_all、unknown、still_checking、not_checked です。本番の結果とクレジットの状態は、ダッシュボードのスナップショットと一致します。ジョブのステータスは queued、running、paused、canceling、canceled、completed のいずれかです。テストジョブは、決定論的な completed、pending、failed、cancelled のいずれかの状態を返します。

エラーと安全な再試行

すべてのジョブ送信と単一アドレスのライブ送信で、使用可能な英字、数字、ドット、コロン、アンダースコア、ハイフンからなる 8～128 文字の Idempotency-Key を送信してください。応答が不確かな場合は、同じ API キー、同じ冪等キー、同じ正規化済みボディで再試行してください。リプレイの範囲は API キー単位です。この認証情報を置き換えて再送信すると、別の実行が作成される場合があります。同じ冪等キーを変更したボディで再利用すると、HTTP 409 idempotency_conflict が返されます。新しいキーは、クレジットが消費される可能性のある新しい実行を意図する場合にのみ使用してください。

HTTP 401 は、キーが指定されていない、失効している、またはスコープが不足していることを意味します。HTTP 422 は無効なアドレスやリストの上限超過を示します。テスト用の一括ジョブは、ワークスペースごとに1時間あたり20件、または30日あたり100件の新規ジョブを超えると HTTP 429 を返します。同一内容の再試行では元のジョブが返されます。HTTP 503 はリクエストが一時的に利用できないことを意味します。送信結果が不確かな状態で 503 が返っても、ジョブが存在しないとは限らないため、同じ冪等キーで再試行してください。エラーにはコード、メッセージ、リクエスト ID が含まれます。

無料のサンドボックス

テストキーで使用できるアドレスは、deliverable@example.com、undeliverable@example.com、risky@example.com、unknown@example.com、pending@example.com、error@example.com のみです。これらは有効、無効、キャッチオール、不明、保留中、利用不可の各結果をシミュレートします。一括テストジョブでは、本番の検証やクレジット台帳に影響を与えることなく、ステータス、結果、キャンセル、リプレイを利用できます。

一括サンドボックスジョブとそのリプレイ記録は30日間保持されます。この期間を過ぎたら、新しいテストには新しいべき等キーを使用してください。

従来の/api/v1/verificationsテストキーシミュレーターは、以前の2026-10-01レスポンスバージョンとcamelCaseのフィールドを使用します。バージョン管理された一括シミュレーターには/api/v1/jobsをご利用ください。

署名付き Webhook

オーナーとマネージャーのロールでは、job.completed と job.canceled 用の HTTPS エンドポイントを設定できます。テスト ping には test.ping が使用されます。ジョブのペイロードには、固定のイベント ID、ジョブ ID、状態、アドレスを含まない概要、消費/返還された件数、結果の URL が含まれます。メールアドレスやプロバイダーのデータが含まれることはありません。

FairValid-Webhook-Id、FairValid-Webhook-Timestamp、FairValid-Webhook-Signature を読み取ってください。署名は fv1= の後に、fv1\n{event ID}\n{Unix timestamp}\nの生のバイト列とその直後に続く生の JSON ボディに対する小文字の HMAC-SHA256 16 進値が続く形式です。比較には定数時間比較を使用してください。自身の時計から 5 分を超えてずれたタイムスタンプは拒否し、永続ストレージ上でイベント ID による重複排除を行ってください。

10 秒以内に任意の 2xx を返してください。失敗した配信や結果が不明な配信は、同じイベント ID で最大 8 回再試行されます。30 日間の履歴を確認するか、手動で再配信できます。リダイレクトやプライベートな宛先は拒否されます。シークレットのローテーション後、新しい試行では新しいシークレットが使用されます。処理中の試行の署名を検証できるよう、以前のシークレットは 24 時間保持してください。

実行可能なサンプル

リポジトリにはpackages/contracts/examples/job.mjsとpackages/contracts/examples/webhook-receiver.mjsが含まれています。ジョブのサンプルは、Node 22とテストキーで実行してください。レシーバーは、正確な生のボディバイトと、ローテーション中の現在および以前のシークレットの両方を検証します。本番環境で使用する前に、HTTPSを前段に配置し、メモリ内のイベントIDセットを永続的でアトミックなストアに置き換えてください。

FAIRVALID_API_KEY=... FAIRVALID_BASE_URL=https://YOUR_FAIRVALID_HOST \
  node packages/contracts/examples/job.mjs