didit-proof-of-address

Didit Proof of Address API

概要

住所書類（画像または PDF）を 1 回の呼び出しで検証します。書類を分類（種類とサブタイプ）し、発行元、日付、所有者の氏名と住所を抽出します。住所を解析してジオコーディングし、PDF／EXIF のフォレンジックで改ざんを確認し、オプションの expected_* 値と照合します。結果は Approved または Declined で、見つかった問題をすべて説明する warnings リストが含まれます。

料金： 1 回の呼び出しにつき $0.20（200 レスポンスはすべて課金対象で、Approved と Declined のどちらも含みます。単独の呼び出しに無料枠はありません）。これらは 2026 年 11 月 1 日までの標準価格です。同日、Didit の料金体系が変更され、月 500 件の無料チェックは月 $10 分の無料クレジットになります。最新の料金は didit.me/pricing をご確認ください。

主な制約：

• 形式：JPG、JPEG、PNG、TIFF、PDF、WEBP。複数ページの PDF に対応しています。暗号化された PDF には document_password が必要です。
• 最大アップロードサイズ：PDF は 50 MB、画像は 6 MB（これを超えるファイルは 400 を返します）
• 応答時間：通常 5～15 秒、複数ページの PDF は最大 約 30 秒。クライアントのタイムアウトは少なくとも 45 秒に設定し、呼び出しが完了する前に再試行しないでください。
• 書類の最大経過期間（デフォルト）：公共料金の請求書と銀行取引明細書は 3 か月、政府発行書類およびその他の書類は 12 か月です。1 か月は 30 日として計算されます。リクエストごとに poa_document_age_months（1～120、年齢チェックを無効にする場合は -1）で変更できます。印字された有効期限が過ぎている場合も、書類は期限切れとみなされます。
• 撮影のガイダンス：フルカラーで、すべての角とページが見えるようにし、デジタル編集はしないでください。

機能： 書類の分類、LLM ベースの抽出、住所の解析とジオコーディング（緯度／経度）、言語検出、発行日と経過期間のチェック、氏名／住所／国の照合、PDF および EXIF の改ざんフォレンジック、銀行情報の抽出、QR コードとバーコードの検出。

受け付ける書類の種類（document_type）：

種類	例（document_subtype）
UTILITY_BILL	電気、水道、ガス、インターネット、電話、複合公共料金の請求書
BANK_STATEMENT	口座取引明細書、クレジットカード利用明細書、住宅ローンまたはローンの明細書
GOVERNMENT_ISSUED_DOCUMENT	納税通知書、居住証明書、選挙人登録カード
OTHER_POA_DOCUMENT	賃貸契約書、保険証券、雇用主からのレター

分類できない書類は document_type: "UNKNOWN" となり、INVALID_DOCUMENT_TYPE とともに却下されます。

API リファレンス： https://docs.didit.me/standalone-apis/proof-of-address 機能ガイド： https://docs.didit.me/core-technology/proof-of-address/overview 警告： https://docs.didit.me/core-technology/proof-of-address/warnings-proof-of-address

---

認証

すべてのリクエストに x-api-key ヘッダーが必要です。Didit Business Console の Developers > API keys からアプリケーションの API キーを使用するか、アカウントとキーをプログラムで作成してください（「はじめに」を参照）。カスタムアクセス権を持つ名前付きキーで単独チェックを実行するには、Sessions の書き込み権限が必要です。一部のワークフローに制限されたキーや、承認済みセッションに制限されたキーでは、単独チェックを実行できません。

はじめに（まだアカウントをお持ちでない場合）

Didit API キーをお持ちでない場合は、2 回の API 呼び出しで作成できます。

1. 登録： POST https://apx.didit.me/auth/v2/programmatic/register/ に {"email": "[email protected]", "password": "MyStr0ng!Pass"} を送信します
2. メールを確認： 6 文字の確認コードを確認します
3. 確認： POST https://apx.didit.me/auth/v2/programmatic/verify-email/ に {"email": "[email protected]", "code": "A3K9F2"} を送信します。キーはレスポンスの application.api_key にあります。

クレジットを追加するには： GET /v3/billing/balance/ で残高を確認し、POST /v3/billing/top-up/ に {"amount_in_dollars": 50} を送信して Stripe のチェックアウトリンクを取得します。

プラットフォーム管理（ワークフロー、セッション、ユーザー、請求）の全容については、didit-verification-management スキルをご覧ください。

---

エンドポイント

POST https://verification.didit.me/v3/poa/

ヘッダー

ヘッダー	値	必須
x-api-key	お使いの API キー	はい
Content-Type	multipart/form-data	はい

リクエストパラメーター（multipart/form-data）

パラメーター	型	必須	デフォルト	説明
document	file	はい	-	PoA 文書：tiff、jpg、jpeg、png、pdf、webp。PDF は最大 50 MB、画像は最大 6 MB
document_password	string	いいえ	-	暗号化された PDF のパスワード。パスワードが未指定または誤っている場合は 400 を返します
expected_address	string	いいえ	-	照合する住所です。ジオコーディングして文書内の住所と比較します。不一致の場合、または指定した住所を検証できない場合は、ADDRESS_MISMATCH_WITH_PROVIDED が追加されます
expected_country	string	いいえ	-	ISO 3166-1 alpha-2 または alpha-3 コード（ES または ESP）。文書の国が異なる場合は POA_COUNTRY_MISMATCH_WITH_PROVIDED が追加されます
expected_first_name	string	いいえ	-	name_on_document と照合する名です（あいまい一致、翻字を考慮）。expected_last_name と併せて送信してください。両方が設定されている場合のみ氏名照合が実行されます
expected_last_name	string	いいえ	-	同じ照合に使用する姓です。スコアが 86（0～100）未満の場合は NAME_MISMATCH_WITH_PROVIDED が追加されます
poa_languages_allowed	string	いいえ	サポート対象の全 51 言語	ISO 639-1 コードをカンマ区切りで指定します（例：en,es）。別の言語の場合は UNSUPPORTED_DOCUMENT_LANGUAGE が追加されます。不明なコードの場合は、サポート対象の一覧とともに 400 を返します
poa_document_age_months	string	いいえ	utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12	key:value ペアで指定する、種類ごとの最大経過月数です。値は 1～120、または年齢チェックを行わない場合は -1 を指定します。このパラメーターを送信する場合は、受け入れる種類をすべて指定してください：省略した種類は受け入れ対象外と見なされ（情報通知 POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION）、年齢チェックも行われません
poa_address_mismatch_action	DECLINE / NO_ACTION	いいえ	DECLINE	ADDRESS_MISMATCH_WITH_PROVIDED、NAME_MISMATCH_WITH_PROVIDED、POA_COUNTRY_MISMATCH_WITH_PROVIDED に適用されます
poa_document_issues_action	DECLINE / NO_ACTION	いいえ	DECLINE	DOCUMENT_METADATA_MISMATCH に適用されます
poa_document_authenticity_action	DECLINE / NO_ACTION	いいえ	DECLINE	SUSPECTED_DOCUMENT_MANIPULATION に適用されます
poa_unsupported_language_action	DECLINE / NO_ACTION	いいえ	DECLINE	UNSUPPORTED_DOCUMENT_LANGUAGE に適用されます
poa_issuer_not_identified_action	DECLINE / NO_ACTION	いいえ	DECLINE	ISSUER_NOT_IDENTIFIED に適用されます
poa_name_mismatch_action	DECLINE / NO_ACTION	いいえ	DECLINE	受け付けられますが、適用されません。氏名の不一致には poa_address_mismatch_action が適用されます
save_api_request	boolean	いいえ	true	true：セッションとして保存されます（Business Console、返された request_id を使用する GET /v3/session/{sessionId}/decision/、status.updated ウェブフック）。false：何も保存されず、request_id を使った検索もできません
vendor_data	string	いいえ	-	ユーザーを識別するための値です。レスポンスに含まれ、セッションに保存されます
metadata	JSON string	いいえ	-	文字列フィールドとして送信する JSON オブジェクトです（例：{"flow":"onboarding"}）。レスポンスに含まれ、保存されます

サンドボックス： サンドボックス API キーでは、処理と課金がスキップされます。リクエストの検証後（入力が不正な場合は引き続き 400 を返します）、固定の Approved モックレスポンスが返され、何も保存されません。

例

import requests

with open("bill.pdf", "rb") as f:
    response = requests.post(
        "https://verification.didit.me/v3/poa/",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"document": ("bill.pdf", f, "application/pdf")},
        data={
            "expected_first_name": "Jane",
            "expected_last_name": "Doe",
            "expected_country": "ESP",
            "poa_languages_allowed": "en,es",
            "vendor_data": "user-123",
        },
        timeout=60,  # extraction takes 5-15 s, up to ~30 s for multi-page PDFs
    )
response.raise_for_status()
poa = response.json()["poa"]
print(poa["status"], poa["poa_formatted_address"], [w["risk"] for w in poa["warnings"]])

const formData = new FormData();
formData.append("document", documentFile); // File or Blob
formData.append("expected_first_name", "Jane");
formData.append("expected_last_name", "Doe");
formData.append("expected_country", "ESP");
formData.append("vendor_data", "user-123");

const response = await fetch("https://verification.didit.me/v3/poa/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
  signal: AbortSignal.timeout(60_000),
});
if (!response.ok) throw new Error(`PoA failed: ${response.status} ${await response.text()}`);
const { poa } = await response.json();
console.log(poa.status, poa.warnings.map((w: { risk: string }) => w.risk));

レスポンス（200 OK）

{
  "request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88",
  "poa": {
    "issuing_state": "ESP",
    "document_type": "UTILITY_BILL",
    "document_subtype": "ELECTRICITY_BILL",
    "document_language": "es",
    "issuer": "Acme Energy",
    "issue_date": "2026-09-15",
    "expiration_date": null,
    "poa_address": "C/ Mayor 10, 2B, 28013 Madrid",
    "poa_formatted_address": "Calle Mayor 10, 2B, 28013 Madrid, Spain",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "street_2": "2B",
      "city": "Madrid",
      "region": "Comunidad de Madrid",
      "country": "ES",
      "postal_code": "28013",
      "document_location": {"latitude": 40.4155, "longitude": -3.7074}
    },
    "expected_details_address": null,
    "expected_details_formatted_address": null,
    "expected_details_parsed_address": null,
    "name_on_document": "JANE DOE",
    "extra_fields": {
      "bank_account_number": null,
      "bank_iban": null,
      "bank_sort_code": null,
      "bank_routing_number": null,
      "bank_swift_bic": null,
      "bank_branch_name": null,
      "bank_branch_address": null,
      "document_phone_number": null,
      "additional_names": []
    },
    "detected_codes": [],
    "status": "Approved",
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-10-12T09:30:00.000000+00:00"
}

文書が却下された場合でも 200 を返します。許容される経過期間を超えた請求書に対する警告の例：

{
  "risk": "POA_DOCUMENT_EXPIRED",
  "feature": "PROOF_OF_ADDRESS",
  "additional_data": {
    "expiration_reason": "age_window",
    "max_age_months": 3,
    "document_subtype": "ELECTRICITY_BILL",
    "document_type": "UTILITY_BILL",
    "issue_date": "2026-02-10"
  },
  "log_type": "error",
  "short_description": "Document expired",
  "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity."
}

レスポンスには文書ファイルやフォレンジックメタデータは含まれません。save_api_request=true の場合、GET /v3/session/{request_id}/decision/ はそれらを poa_verifications[] で返します（document_file は約 4 時間後に期限切れとなる一時 URL です）。

ステータス値と処理

ステータス	意味	対応
"Approved"	却下につながる警告はありません	解析された住所を使用します。information 警告が含まれる場合があります
"Declined"	少なくとも1つの警告に log_type: "error" があります	warnings[].risk を確認し、別の書類を求めるか、expected_* 入力を修正します

このエンドポイントが In Review または Not Finished を返すことはありません。HTTP コードだけでなく、必ず poa.status と poa.warnings を確認してください。

エラーレスポンス

コード	意味	対応
400	リクエストが無効です	レスポンス本文のフィールドエラーを確認します
401	API キーの有効期限が切れています	キーをローテーションするか、Developers > API keys で新しいキーを作成します
403	API キーがない、誤っている、または取り消されている、このエンドポイントへのアクセス権がないスコープ付きキー、キーの IP 許可リスト外からのリクエスト、またはクレジット不足です	detail または error のメッセージを確認し、x-api-key ヘッダーまたはキーのアクセス権を修正するか、クレジットを追加します
429	レート制限：キーごとに1分あたり POST/PATCH/DELETE リクエスト300件、GET リクエスト600件	Retry-After の秒数だけ待ってから再試行します

このエンドポイントで 400 となる原因：document がない、許可リスト外の拡張子、50 MB を超える PDF または6 MB を超える画像、暗号化された PDF に document_password がない（または誤っている）、poa_languages_allowed に不明なコードがある、poa_document_age_months の組み合わせが不正、または抽出処理で処理できない書類（{"error": ["Error extracting POA information"]}）。クレジットの確認は処理の前に行われます。クレジット不足の場合の 403 の本文は {"error": "You don't have enough credits to perform this request. ..."} です。

---

応答フィールドのリファレンス

フィールド	型	説明
request_id	uuid	save_api_request=true の場合はセッション ID、それ以外の場合は一時的な相関 ID
poa.status	string	"Approved" または "Declined"
poa.issuing_state	string/null	書類の発行国。通常は ISO 3166-1 alpha-3（ESP）
poa.document_type	string	UTILITY_BILL、BANK_STATEMENT、GOVERNMENT_ISSUED_DOCUMENT、OTHER_POA_DOCUMENT または UNKNOWN
poa.document_subtype	string	例：ELECTRICITY_BILL、WATER_BILL、ACCOUNT_STATEMENT、CREDIT_CARD_STATEMENT、TAX_ASSESSMENT。判定できない場合は UNKNOWN
poa.document_language	string/null	ISO 639-1 コード
poa.issuer	string/null	発行会社または組織。null の場合は ISSUER_NOT_IDENTIFIED が追加されます
poa.issue_date	date/null	YYYY-MM-DD。null の場合は UNABLE_TO_EXTRACT_ISSUE_DATE で却下されます
poa.expiration_date	date/null	書類に印字されている有効期限（該当する場合）
poa.poa_address	string/null	印字されている住所。null の場合は MISSING_ADDRESS_INFORMATION で却下されます
poa.poa_formatted_address	string/null	ジオコーディングで正規化された住所
poa.poa_parsed_address	object/null	{street_1, street_2, city, region, country, postal_code, document_location}。country は ISO alpha-2
poa.poa_parsed_address.document_location	object/null	書類上の住所の {latitude, longitude}
poa.expected_details_address	string/null	expected_address のエコー
poa.expected_details_formatted_address	string/null	ジオコーディングされた expected_address
poa.expected_details_parsed_address	object/null	expected_address のジオコーディング結果。is_verified フラグを含みます
poa.name_on_document	string/null	主たる名義人の名前。null の場合は POA_NAME_NOT_DETECTED で却下されます
poa.extra_fields	object	bank_account_number、bank_iban、bank_sort_code、bank_routing_number、bank_swift_bic、bank_branch_name、bank_branch_address、document_phone_number（存在しない場合は null）、additional_names（配列）
poa.detected_codes	array	QR コードとバーコード：type、page_number、position、x、y、width、height、page_width、page_height、raw_payload（base64）、parsed_payload（デコードできない場合は null）
poa.warnings	array	{risk, feature, additional_data, log_type, short_description, long_description}。feature は常に PROOF_OF_ADDRESS です
vendor_data	string/null	vendor_data のエコー
metadata	object/null	metadata のエコー
created_at	string	ISO 8601 UTC タイムスタンプ

---

警告タグ

log_type は error（Declined に設定）または information（影響なし）です。このエンドポイントでは warning は生成されません。

常に却下

タグ	原因
MISSING_ADDRESS_INFORMATION	住所を抽出できませんでした
POA_DOCUMENT_EXPIRED	該当する種類の許容期間を超えているか、印字された有効期限を過ぎています。additional_data：expiration_reason（age_window または printed_expiration）、document_type、document_subtype、issue_date、および max_age_months または expiration_date
INVALID_DOCUMENT_TYPE	PoA 書類として分類できません（document_type: "UNKNOWN"）
UNABLE_TO_VALIDATE_DOCUMENT_AGE	書類の有効期間のチェック自体に失敗しました
UNABLE_TO_EXTRACT_ISSUE_DATE	発行日が見つかりませんでした（このエンドポイントでは設定できません）
POA_NAME_NOT_DETECTED	名義人の名前が見つかりませんでした（このエンドポイントでは設定できません）

設定可能（デフォルトは DECLINE、NO_ACTION にすると information）

タグ	原因	オプション
NAME_MISMATCH_WITH_PROVIDED	name_on_document が expected_first_name + expected_last_name と一致しません	poa_address_mismatch_action
ADDRESS_MISMATCH_WITH_PROVIDED	書類の住所が expected_address と異なるか、いずれかの住所を確認できませんでした	poa_address_mismatch_action
POA_COUNTRY_MISMATCH_WITH_PROVIDED	書類の国が expected_country と異なります。additional_data：expected_country、extracted_country	poa_address_mismatch_action
DOCUMENT_METADATA_MISMATCH	ファイルが空、ファイルのメタデータを読み取れない、または EXIF の日付形式が不正です	poa_document_issues_action
SUSPECTED_DOCUMENT_MANIPULATION	フォレンジック検査で編集の痕跡が見つかりました。デジタル署名後の変更、テキストオーバーレイによる改ざん、既知の PDF エディターの使用、EXIF 日付の不整合、不審な再エクスポートが含まれます。additional_data：reason、detection_method	poa_document_authenticity_action
UNSUPPORTED_DOCUMENT_LANGUAGE	言語が poa_languages_allowed に含まれていません	poa_unsupported_language_action
ISSUER_NOT_IDENTIFIED	発行機関が見つかりませんでした	poa_issuer_not_identified_action

このエンドポイントでは情報提供のみ（却下されません）

タグ	原因
POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION	検出されたタイプが poa_document_age_months から除外されています
UNPARSABLE_OR_INVALID_ADDRESS	住所を読み取れましたが、有効な居住用住所として解析およびジオコーディングできませんでした

FUTURE_ISSUE_DATE、POOR_DOCUMENT_QUALITY、NAME_MISMATCH_ID_VERIFICATION、POA_NAME_MISMATCH_BETWEEN_DOCUMENTS、POA_MAX_ATTEMPTS_EXCEEDED は、このエンドポイントでは生成されません（ワークフローセッションで使用されます）。発行日が未来の日付の書類が、このエンドポイントで自動的に却下されることはありません。

---

一般的なワークフロー

基本的な住所確認

1. POST /v3/poa/ with the document (client timeout >= 45 s)
2. "Approved" -> store poa_formatted_address / poa_parsed_address
   "Declined" -> branch on warnings[].risk:
     POA_DOCUMENT_EXPIRED            -> ask for a more recent document
     MISSING_ADDRESS_INFORMATION     -> ask for a clearer, complete document
     INVALID_DOCUMENT_TYPE           -> ask for a utility bill, bank statement or official letter
     UNABLE_TO_EXTRACT_ISSUE_DATE    -> ask for a document with a visible issue date
     SUSPECTED_DOCUMENT_MANIPULATION -> do not accept; ask for the original file

住所と本人確認情報の照合

単独での呼び出しは ID チェックと関連付けられないため、すでに信頼しているデータを渡してください。

1. POST /v3/id-verification/ -> read id_verification.first_name, last_name, issuing_state
   (see the didit-id-document-verification skill)
2. POST /v3/poa/ with expected_first_name, expected_last_name, expected_country
   (and expected_address if the user typed one)
3. NAME_MISMATCH_WITH_PROVIDED / ADDRESS_MISMATCH_WITH_PROVIDED / POA_COUNTRY_MISMATCH_WITH_PROVIDED
   -> Declined by default; send poa_address_mismatch_action=NO_ACTION to only flag them

保存済みの結果の取得または修正

1. Call with save_api_request=true (default); keep request_id
2. GET /v3/session/{request_id}/decision/ -> poa_verifications[] with document_file and forensics
3. To fix extracted fields after a manual review, PATCH /v3/session/{sessionId}/update-poa-data/
   (documented in the didit-verification-management skill)

---

ユーティリティスクリプト

verify_address.py：コマンドラインから住所証明書類を確認します。JSON レスポンスを出力した後、ステータス、住所、警告リスクを表示します。

# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/verify_address.py utility_bill.pdf
python scripts/verify_address.py bank_statement.jpg --vendor-data user-123
python scripts/verify_address.py bill.pdf --first-name Jane --last-name Doe --country ESP
python scripts/verify_address.py bill.pdf --expected-address "Calle Mayor 10, 28013 Madrid" --languages en,es
python scripts/verify_address.py bill.pdf --document-age utility_bill:6,bank_statement:6,government_issued_document:12,other_poa_document:12
python scripts/verify_address.py locked.pdf --password "pdf-password" --no-save