跳转到主要内容
POST
curl
Didit 的地址验证 API 用于确认邮寄地址是否存在,并返回标准化后的地址,包括投递行、地址组成部分和坐标。当您的后端拥有一个地址,并需要确认它是否存在以及以何种标准化形式存在时,请使用 POST /v3/address-validation/。 地址验证仅确认地址本身。它从不将地址与某个人关联:verified 结果表示该地点存在,但不代表有人居住在那里。

发送地址

请在 address 中以单行形式发送地址,或以结构化字段发送:address_line_1,并在有这些信息时提供 address_line_2、city、region 和 postal_code。切勿在同一请求中同时发送两种格式。country 始终为必填项,须为 ISO 3166-1 alpha-2 或 alpha-3 代码。

解读响应

  • address_validation.status 是您应当依据的结果:
    • verified:地址已确认到楼栋(或套房、邮政信箱)。
    • partially_verified:地址仅确认到街道,或确认到邮政参考数据对该地点保存的最精确级别。
    • not_verified:仅匹配到地区或城市,或完全未匹配。
    • unavailable:无法执行验证。请稍后重试。
  • address_validation.verification_level 是匹配到的最精确级别:administrative_area、locality、thoroughfare、premise 或 delivery_point。
  • address_validation.address 和 address_validation.formatted_address 包含标准化后的地址,并按该国的书写习惯呈现。
  • address_validation.latitude 和 address_validation.longitude 标示匹配地址的位置。
  • request_id 用于标识该请求。不会创建会话,结果仅在本次响应中返回,因此请自行保存所需内容。
对于每个已完成的请求,HTTP 状态码均为 200,包括 unavailable 的情况。

工作流中的地址验证

同一验证功能也是身份证件验证和地址证明工作流步骤的附加功能。在该步骤的设置中开启 address_validation_enabled 后,系统会在读取人员上传的文件后,对其提供的地址(印在身份证件上的地址,或地址证明上的地址)进行一次验证。结果即为会话决策中该步骤对应条目(id_verifications[] 或 poa_verifications[])里的 address_validation 对象。状态为 partially_verified 或 not_verified 的地址会触发 ADDRESS_NOT_VERIFIED 警告,其操作由该步骤的 address_not_verified_action 决定(默认为 NO_ACTION,仅记录该警告)。unavailable 的验证从不触发该警告,也从不改变验证结果。

沙盒行为

沙盒密钥会验证请求,并始终返回确定性的 verified 结果,该结果会回显您发送的地址。沙盒调用不消耗额度。

计费

每次地址验证 API 调用,按每个已验证地址收取 $0.10。`unavailable` 结果不收费。在工作流中,该附加功能按步骤验证的每个地址收取 $0.10。

授权

x-api-key
string
header
必填

您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json

一个地址:使用单行文本(address),或者至少包含 address_line_1 的结构化字段,两者不可兼有。

country
string
必填

地址所在国家/地区的 ISO 3166-1 alpha-2 或 alpha-3 代码。

Maximum string length: 3
示例:

"US"

address
string

单行完整地址。

Maximum string length: 500
示例:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

街道与门牌号。

Maximum string length: 255
示例:

"1600 Amphitheatre Pkwy"

address_line_2
string

公寓、套房、楼层或楼栋。

Maximum string length: 255
city
string

城市或地区。

Maximum string length: 128
示例:

"Mountain View"

region
string

州、省或地区。

Maximum string length: 128
示例:

"CA"

postal_code
string
Maximum string length: 32
示例:

"94043"

响应

核验已完成。请读取 address_validation.status;已完成的请求其 HTTP 状态码始终为 200。

request_id
string<uuid>
必填

此请求的标识符;联系支持团队时请引用此标识符。不会创建会话。

address_validation
object
必填

单次地址验证的结果:地址是否存在,以及其规范化形式。它仅确认地址;绝不会将地址与个人关联。

created_at
string<date-time>
必填
最后修改于 2026年11月7日