FairValid

开发者参考 · v1

客户 API

提交验证任务、读取结果，并接收已签名的完成事件。

OpenAPI 3.1 JSON管理 API 密钥面向 AI 代理的 MCP管理 Webhook

开始使用

在“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 权限范围。已撤销的密钥将无法发起新请求。测试密钥仅可访问其自身的模拟任务。

正式密钥的总上限包括已扣除的额度，以及为已受理的唯一身份预留的额度。它不会向工作区增加额度。超出上限的新请求将返回 HTTP 402 key_cap_reached，且不会创建任务或预留。降低上限会阻止新工作，已受理的工作将继续进行。

正式任务使用你工作区的验证队列和额度余额。密钥权限范围、密钥上限、工作区访问权限和处理限制仍然适用。验证被受理处理时即会预留工作区额度；结果遵循与控制台相同的扣除和退回规则。

在运营暂停期间，新的实时提交可能会返回 HTTP 503 live_verification_unavailable，且不会预留点数。请稍后使用相同的 Idempotency-Key 重试。

任务与结果

方法路径用途
POST/api/v1/jobs以 JSON 格式提交 1 至 5,000 个地址，大小不超过 2 MiB。
POST/api/v1/verifications提交一个真实地址，或使用原有的单地址模拟器。
GET/api/v1/jobs/{id}读取当前任务状态和摘要。
GET/api/v1/jobs/{id}/results读取最多 50 条结果及已签名的下一页游标。
POST/api/v1/jobs/{id}/cancel请求取消；正在进行的任务可能仍会完成。
GET/api/v1/balance读取工作区当前可用额度和冻结额度。
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 状态。

错误与安全重试

每次提交任务和正式单地址请求时，请发送一个 Idempotency-Key，长度为 8 到 128 个字符，仅可包含字母、数字、点、冒号、下划线或连字符。如果响应结果不确定，请使用相同的 API 密钥、幂等键和规范化请求体进行重试。重放仅限于该 API 密钥范围内；更换该凭据后重新提交可能会创建另一次运行。使用相同幂等键但更改请求体将返回 HTTP 409 idempotency_conflict。仅当您确实需要一次全新的、可能扣除额度的运行时，才使用新的幂等键。

HTTP 401 表示密钥缺失、已被撤销或权限范围不足。HTTP 422 表示地址无效或超出列表限制。测试批量任务在每个工作区每小时新建超过 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。它们分别模拟有效、无效、全收（catch-all）、未知、待处理和不可用的结果。批量测试任务支持状态查询、结果读取、取消和重放，且不会影响正式验证或额度账本。

批量沙盒任务及其重放记录保留 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 十六进制值。请使用恒定时间比较。拒绝与您的时钟相差超过五分钟的时间戳，并在持久化存储中按事件 ID 去重。

请在 10 秒内返回任意 2xx 响应。发送失败或结果不确定时，将使用相同的事件 ID 最多重试八次；您可以查看 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