curl -X POST 'https://verification.didit.me/v3/poa/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'document=@./utility-bill.pdf' \
-F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \
-F 'expected_country=ARG' \
-F 'expected_first_name=Sophia' \
-F 'expected_last_name=Martinez' \
-F 'poa_languages_allowed=en,es' \
-F 'vendor_data=user-123' \
--max-time 45from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.proof_of_address.verify(
document=open("document.pdf", "rb"),
expected_address="Av. Monseñor Tavella 1291, Salta, Argentina",
expected_country="ARG",
expected_first_name="Sophia",
expected_last_name="Martinez",
poa_languages_allowed="en,es",
save_api_request=True,
vendor_data="user-123",
)
print(result)import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.proofOfAddress.verify({
document: await fileFromPath("document.pdf"),
expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
expected_country: "ARG",
expected_first_name: "Sophia",
expected_last_name: "Martinez",
poa_languages_allowed: "en,es",
save_api_request: true,
vendor_data: "user-123",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{
Document: didit.FileFromPath("document.pdf"),
ExpectedAddress: didit.String("Av. Monseñor Tavella 1291, Salta, Argentina"),
ExpectedCountry: didit.String("ARG"),
ExpectedFirstName: didit.String("Sophia"),
ExpectedLastName: didit.String("Martinez"),
POALanguagesAllowed: didit.String("en,es"),
SaveAPIRequest: didit.Bool(true),
VendorData: didit.String("user-123"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.ProofOfAddressVerifyParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()
.document(Path.of("document.pdf"))
.expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina")
.expectedCountry("ARG")
.expectedFirstName("Sophia")
.expectedLastName("Martinez")
.poaLanguagesAllowed("en,es")
.saveApiRequest(true)
.vendorData("user-123")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
use Didit\File;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->proofOfAddress->verify([
'document' => File::fromPath('document.pdf'),
'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',
'expected_country' => 'ARG',
'expected_first_name' => 'Sophia',
'expected_last_name' => 'Martinez',
'poa_languages_allowed' => 'en,es',
'save_api_request' => true,
'vendor_data' => 'user-123',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.proof_of_address.verify(
document: Pathname("document.pdf"),
expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
expected_country: "ARG",
expected_first_name: "Sophia",
expected_last_name: "Martinez",
poa_languages_allowed: "en,es",
save_api_request: true,
vendor_data: "user-123"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams
{
Document = FileUpload.FromPath("document.pdf"),
ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina",
ExpectedCountry = "ARG",
ExpectedFirstName = "Sophia",
ExpectedLastName = "Martinez",
PoaLanguagesAllowed = "en,es",
SaveApiRequest = true,
VendorData = "user-123",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88",
"poa": {
"issuing_state": "ARG",
"document_type": "UTILITY_BILL",
"document_subtype": "WATER_BILL",
"document_language": "es",
"issuer": "Aguas del Norte",
"issue_date": "2026-04-10",
"expiration_date": null,
"poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA",
"poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina",
"poa_parsed_address": {
"street_1": "Avenida Monseñor Tavella 1291",
"street_2": "b",
"city": "Salta",
"region": "Salta",
"country": "AR",
"postal_code": "A4400",
"document_location": {
"latitude": -24.8208682,
"longitude": -65.4130954
}
},
"expected_details_address": null,
"expected_details_formatted_address": null,
"expected_details_parsed_address": null,
"name_on_document": "OESTE EMBOTELLADORA S.A.",
"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": [
"LA EMBOTELLADORA DEL NORTE SA"
]
},
"detected_codes": [
{
"type": "QR_CODE",
"page_number": 1,
"position": [
[
820,
1120
],
[
1002,
1120
],
[
1002,
1302
],
[
820,
1302
]
],
"x": 820,
"y": 1120,
"width": 182,
"height": 182,
"page_width": 1190,
"page_height": 1684,
"raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==",
"parsed_payload": "https://aguasdelnorte.com/factura/998811"
},
{
"type": "CODE_128",
"page_number": 1,
"position": [
[
112,
1480
],
[
560,
1480
],
[
560,
1540
],
[
112,
1540
]
],
"x": 112,
"y": 1480,
"width": 448,
"height": 60,
"page_width": 1190,
"page_height": 1684,
"raw_payload": "MDA5OTg4MTEwMDA0Mg==",
"parsed_payload": "0099881100042"
}
],
"status": "Approved",
"warnings": []
},
"vendor_data": "user-123",
"metadata": null,
"created_at": "2026-06-12T02:29:02.439655+00:00"
}地址证明 API:POA 验证与 OCR | Didit
通过 POST /v3/poa/ 验证水电费账单、银行对账单和租约。Didit 提供 OCR 地址提取、真伪检测,按次计费,无需签约。
curl -X POST 'https://verification.didit.me/v3/poa/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'document=@./utility-bill.pdf' \
-F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \
-F 'expected_country=ARG' \
-F 'expected_first_name=Sophia' \
-F 'expected_last_name=Martinez' \
-F 'poa_languages_allowed=en,es' \
-F 'vendor_data=user-123' \
--max-time 45from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.proof_of_address.verify(
document=open("document.pdf", "rb"),
expected_address="Av. Monseñor Tavella 1291, Salta, Argentina",
expected_country="ARG",
expected_first_name="Sophia",
expected_last_name="Martinez",
poa_languages_allowed="en,es",
save_api_request=True,
vendor_data="user-123",
)
print(result)import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.proofOfAddress.verify({
document: await fileFromPath("document.pdf"),
expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
expected_country: "ARG",
expected_first_name: "Sophia",
expected_last_name: "Martinez",
poa_languages_allowed: "en,es",
save_api_request: true,
vendor_data: "user-123",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{
Document: didit.FileFromPath("document.pdf"),
ExpectedAddress: didit.String("Av. Monseñor Tavella 1291, Salta, Argentina"),
ExpectedCountry: didit.String("ARG"),
ExpectedFirstName: didit.String("Sophia"),
ExpectedLastName: didit.String("Martinez"),
POALanguagesAllowed: didit.String("en,es"),
SaveAPIRequest: didit.Bool(true),
VendorData: didit.String("user-123"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.ProofOfAddressVerifyParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()
.document(Path.of("document.pdf"))
.expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina")
.expectedCountry("ARG")
.expectedFirstName("Sophia")
.expectedLastName("Martinez")
.poaLanguagesAllowed("en,es")
.saveApiRequest(true)
.vendorData("user-123")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
use Didit\File;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->proofOfAddress->verify([
'document' => File::fromPath('document.pdf'),
'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',
'expected_country' => 'ARG',
'expected_first_name' => 'Sophia',
'expected_last_name' => 'Martinez',
'poa_languages_allowed' => 'en,es',
'save_api_request' => true,
'vendor_data' => 'user-123',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.proof_of_address.verify(
document: Pathname("document.pdf"),
expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina",
expected_country: "ARG",
expected_first_name: "Sophia",
expected_last_name: "Martinez",
poa_languages_allowed: "en,es",
save_api_request: true,
vendor_data: "user-123"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams
{
Document = FileUpload.FromPath("document.pdf"),
ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina",
ExpectedCountry = "ARG",
ExpectedFirstName = "Sophia",
ExpectedLastName = "Martinez",
PoaLanguagesAllowed = "en,es",
SaveApiRequest = true,
VendorData = "user-123",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88",
"poa": {
"issuing_state": "ARG",
"document_type": "UTILITY_BILL",
"document_subtype": "WATER_BILL",
"document_language": "es",
"issuer": "Aguas del Norte",
"issue_date": "2026-04-10",
"expiration_date": null,
"poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA",
"poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina",
"poa_parsed_address": {
"street_1": "Avenida Monseñor Tavella 1291",
"street_2": "b",
"city": "Salta",
"region": "Salta",
"country": "AR",
"postal_code": "A4400",
"document_location": {
"latitude": -24.8208682,
"longitude": -65.4130954
}
},
"expected_details_address": null,
"expected_details_formatted_address": null,
"expected_details_parsed_address": null,
"name_on_document": "OESTE EMBOTELLADORA S.A.",
"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": [
"LA EMBOTELLADORA DEL NORTE SA"
]
},
"detected_codes": [
{
"type": "QR_CODE",
"page_number": 1,
"position": [
[
820,
1120
],
[
1002,
1120
],
[
1002,
1302
],
[
820,
1302
]
],
"x": 820,
"y": 1120,
"width": 182,
"height": 182,
"page_width": 1190,
"page_height": 1684,
"raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==",
"parsed_payload": "https://aguasdelnorte.com/factura/998811"
},
{
"type": "CODE_128",
"page_number": 1,
"position": [
[
112,
1480
],
[
560,
1480
],
[
560,
1540
],
[
112,
1540
]
],
"x": 112,
"y": 1480,
"width": 448,
"height": 60,
"page_width": 1190,
"page_height": 1684,
"raw_payload": "MDA5OTg4MTEwMDA0Mg==",
"parsed_payload": "0099881100042"
}
],
"status": "Approved",
"warnings": []
},
"vendor_data": "user-123",
"metadata": null,
"created_at": "2026-06-12T02:29:02.439655+00:00"
}授权
您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。
请求体
地址证明文件。允许的扩展名:tiff、jpg、jpeg、png、pdf、webp。最大上传大小:15 MB(超出将返回 400 拒绝)。支持多页 PDF(延迟可能更高);加密的 PDF 需要提供 document_password。图片在处理前会自动压缩。
当 document 为加密 PDF 时用于解密的密码。发送未附带(或附带错误)密码的加密 PDF 将返回 400。
用于与证件核对的地址。系统会对该地址进行地理编码并与提取出的地址进行比对;不匹配(或预期地址无法进行地理编码/验证)将添加 ADDRESS_MISMATCH_WITH_PROVIDED,受 poa_address_mismatch_action 控制。地理编码后的形式将在 expected_details_formatted_address / expected_details_parsed_address 中回显。
"Av. Monseñor Tavella 1291, Salta, Argentina"
用于与证件核验的国家/地区(ISO 3166-1 代码,例如 ARG 或 AR)。与证件国家/地区不匹配会添加 POA_COUNTRY_MISMATCH_WITH_PROVIDED,受 poa_address_mismatch_action 控制。
"ARG"
用于与 name_on_document 进行核验的名(支持音译的模糊匹配)。低于匹配阈值的分数会添加 NAME_MISMATCH_WITH_PROVIDED,受 poa_address_mismatch_action 管控。
"Sophia"
用于与 name_on_document 比对的姓氏,与 expected_first_name 结合以计算匹配分数。
"Martinez"
以逗号分隔的所接受证件语言的 ISO 639-1 代码列表(例如 en,es,fr)。省略或为空时,接受所有 51 种受支持的语言。使用列表之外语言的证件会添加 UNSUPPORTED_DOCUMENT_LANGUAGE(由 poa_unsupported_language_action 控制);列表中包含未知代码将返回 400 以及完整的受支持代码集。
"en,es"
以逗号分隔的 key:value 对,用于按证件类型设置最大证件月龄 — 键:utility_bill、bank_statement、government_issued_document、other_poa_document;值:1–120,或 -1 表示无限制(不进行时效检查)。缺省时的默认值:utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12。超出期限的证件将以 POA_DOCUMENT_EXPIRED 拒绝。注意:提供此字段时,请列出您接受的所有类型 — 未列出的类型将被视为不接受(提示信息 POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION),并跳过其时效检查。
"utility_bill:3,bank_statement:6"
已接受但目前未应用:姓名不匹配警告(NAME_MISMATCH_WITH_PROVIDED)将转而遵循 poa_address_mismatch_action。请设置 poa_address_mismatch_action 以同时控制姓名和地址的不匹配行为。
DECLINE, NO_ACTION 遇到文件完整性问题时的处理操作:实际上该 endpoint 仅生成 DOCUMENT_METADATA_MISMATCH。
DECLINE, NO_ACTION 当怀疑证件被篡改(SUSPECTED_DOCUMENT_MANIPULATION)时的处理操作,例如 PDF 在数字签名后被修改、经由已知 PDF 编辑器处理、存在覆盖文本篡改或 EXIF 日期不一致。同时控制 POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT(文件无法证明其是否发生过更改的重新录入文本字段):DECLINE 同样予以拒绝,NO_ACTION 将其保留为警告。
DECLINE, NO_ACTION 当证件语言不在 poa_languages_allowed 范围内(UNSUPPORTED_DOCUMENT_LANGUAGE)时采取的操作。
DECLINE, NO_ACTION 当提取的详细信息与 expected_* 字段不一致时采取的操作:ADDRESS_MISMATCH_WITH_PROVIDED、NAME_MISMATCH_WITH_PROVIDED 和 POA_COUNTRY_MISMATCH_WITH_PROVIDED 均遵循此操作。
DECLINE, NO_ACTION 当无法在证件上识别出签发公司/组织时的处理操作(ISSUER_NOT_IDENTIFIED)。
DECLINE, NO_ACTION 为 true(默认)时,将此次调用持久化为 API 类型的会话:在 Business Console 中可见,可使用返回的 request_id 通过 GET /v3/session/{sessionId}/decision/ 检索,通过 status.updated Webhook 发出通知,并存储上传的证件。为 false 时,不存储任何内容,且 request_id 仅为用于关联响应的临时 UUID。
true
可选的不透明字符串(您的内部用户 ID、邮箱、UUID 等),存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联,并在稍后筛选会话。
"user-123"
与会话一同存储(当 save_api_request=true 时)并在响应中原样返回的可选 JSON 对象。在 multipart 请求中,请将其作为 JSON 编码的字符串字段发送(例如 metadata={"flow":"onboarding"}),它将被解析为对象。
{ "flow": "onboarding" }
响应
证件已处理。poa.status 为 Approved 或 Declined;检测到的每个问题都在 poa.warnings 中逐项列出。过期、不匹配或可疑的证件仍会返回 200 并附带 status: "Declined" — 请检查响应体,而不仅仅是 HTTP 状态码。当 save_api_request=true 时,request_id 为持久化的会话 ID。
当 save_api_request=true 时持久化的会话 ID(可用于 GET /v3/session/{sessionId}/decision/);否则为一个临时的关联 UUID。
Show child attributes
Show child attributes
您发送的 vendor_data 回显,或 null。
您发送的 metadata 对象回显,或 null。
响应生成时的 ISO 8601 时间戳(UTC)。