---
title: "POST /v1/me/identity/verification"
method: POST
path: "/v1/me/identity/verification"
tags: ["IdentityService"]
---

# POST /v1/me/identity/verification

`POST /v1/me/identity/verification`

SubmitVerification 校验实名信息与授权，并按选定的支付宝 OpenAPI v3 方式初始化核身单据。

## Request body

- IdentityV1SubmitVerificationRequest — SubmitVerificationRequest 用户自助实名认证提交参数。
  - `agreementAccepted` boolean — 是否已单独同意实名认证服务协议与个人信息处理授权。
  - `agreementVersion` string — 协议版本，留空时服务端使用当前默认版本。
  - `documentNo` string — 证件号码；新客户端应使用此字段，idCardNo 仅保留旧客户端兼容。
  - `documentType` string — 证件类型；当前支持 IDENTITY_CARD / RESIDENCE_HK_MC / RESIDENCE_TAIWAN。
  - `idCardNo` string — 旧客户端身份证号字段；仅在 documentType=IDENTITY_CARD 时兼容读取。
  - `realName` string — 与所选证件一致的真实姓名，2-30 个字符。
  - `returnUrl` string — 认证完成后的前端回跳地址；服务端只允许配置基准 URL 的同源地址。
  - `verifyMethod` string — 支付宝核身方式：alipay_certify_qr / alipay_id_two_meta；留空使用默认方式。

## Response `200`

OK

- IdentityV1SubmitVerificationReply — SubmitVerificationReply 实名提交结果。
  - `verification` IdentityV1IdentityVerification — IdentityVerification 是用户侧可见的实名状态，敏感字段仅返回脱敏值。
    - `certifyId` string — 支付宝核身/核验审计标识；人脸 processing 或二要素 verified 时可能返回。
    - `certifyUrl` string — 支付宝人脸核身 URL；仅异步 processing 时返回，二要素不返回。
    - `documentNoMasked` string
    - `documentType` string
    - `expiresAt` string, date-time — 当前核身单据过期时间。
    - `failReason` string — 最近一次失败原因。
    - `idCardMasked` string — 历史身份证脱敏字段；新客户端使用 documentNoMasked。
    - `realNameMasked` string — 脱敏姓名。
    - `remainingAttemptsToday` integer — 当前认证方式剩余提交次数；窗口由服务端策略决定。
    - `status` string — 状态：unverified / processing / verified。
    - `verifiedAt` string, date-time — 认证通过时间。
    - `verifyMethod` string — 本次认证方式。

---

[API](https://skmtc.dev/apiqik/apis/apiqik-api.md) · [All operations](https://skmtc.dev/apiqik/apis/apiqik-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/apiqik/apiqik-api/revisions/e06b96127408/schema)