> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # 从其他服务商导入数据 > Didit 导入路径指南：为历史验证会话、用户、人脸、黑名单、企业、交易及工作流状态规则选择合适的导入方式。 本指南可帮助您在将数据从其他服务商迁移至 Didit 时选择合适的导入路径。客户通常用“导入”一词指代两种不同的操作：- **导入历史验证记录**：重建已完成的 KYC、KYB、交易监控或工作流规则记录，使 Didit 能够展示旧服务商的历史。请使用 `POST /v3/session/imports/`。 - **导入运营数据**：创建用户、企业、资料人脸、黑名单条目或白名单条目，使 Didit 能够在后续检查中使用这些数据。请使用实体、人脸和名单 API。验证导入会为 KYC 和 KYB 创建历史记录，并设置 `session_type: "MIGRATED"`。这些导入不会向终端用户发送邮件，不会将用户重定向至托管流程，也不会重新执行原始验证。导入的记录会出现在会话列表、实体档案和交易视图中，并在适用时出现在 `GET /v3/session/{session_id}/decision/` 中。## 应选择哪种导入方式| 目标 | 使用的导入路径 | 创建内容 | 适用场景 | | - | - | - | - | | 重建历史 KYC 会话 | `POST /v3/session/imports/`，搭配 `import_type=user_verification` | `Session`、身份证件验证数据、可选的证件或自拍照图像、证件和活体视频、标签、元数据 | 从 Sumsub、MetaMap、Veriff、Onfido、Persona、Jumio、Incode、iDenfy、Trulioo 或其他 KYC 服务商迁移已完成的申请人 | | 重建历史 KYB 会话 | `POST /v3/session/imports/`，搭配 `import_type=business_verification` | `BusinessSession`、公司登记数据、高管、实际受益人、标签、元数据 | 从 KYB 服务商、公司登记服务商或内部 KYB 工具迁移已完成的企业核验 | | 重建历史交易监控记录 | `POST /v3/session/imports/`，搭配 `import_type=transactions` | `Transaction`、主体与交易对手、服务商结果、Travel Rule 数据、网络快照、元数据 | 迁移规则引擎、KYT、钱包筛查或法币交易监控的历史记录 | | 导入自定义工作流状态规则 | `POST /v3/session/imports/`，搭配 `import_type=status_rules` | `VerificationSettings.feature_status_rules` | 将其他服务商或电子表格中的策略逻辑迁移至 Didit 的工作流引擎 | | 在无历史会话的情况下创建用户 | `POST /v3/users/create/` 或控制台 CSV 导入 | `VendorUser` 用户档案记录 | 在开始新的 Didit 检查前导入用户名单 | | 为用户关联可信资料人脸 | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` | 已建立索引的资料人脸证据，用于重复检测和人脸搜索 | 从其他 KYC 服务商迁移资料人脸图像，无需重建完整会话 | | 将人脸加入黑名单或白名单 | `POST /v3/lists/{list_uuid}/entries/face-upload/`，或搭配 `reference_session_id` 使用 `POST /v3/lists/{list_uuid}/entries/` | 人脸名单条目和生物特征嵌入向量 | 迁移已知欺诈人脸、可信白名单人脸，或将现有 Didit 会话中的人脸加入黑名单 | | 在无历史 KYB 会话的情况下创建企业 | `POST /v3/businesses/create/` 或控制台 CSV 导入 | `VendorBusiness` 企业档案记录 | 在运行 KYB 前导入企业客户名单 |> [!NOTE] > > 如果您只需要用户或企业档案用于后续检查，请不要导入历史验证会话，而应使用用户或企业实体 API。如果您希望旧服务商的决策结果、证件字段、警告或证据在 Didit 中以合规历史的形式呈现，请使用 `POST /v3/session/imports/`。## 各服务商可以迁移哪些内容只要您导出并转换数据，Didit 就接受标准 CSV 或 NDJSON 文件，因此可以从任何服务商迁移。导入格式始终为 Didit 的标准架构。| 服务商类别 | 常见来源 | 通常可迁移 | 说明 | | - | - | - | - | | KYC 服务商 | Sumsub、MetaMap、Veriff、Onfido、Persona、Jumio、Incode、iDenfy、Trulioo、HyperVerge、AU10TIX、Mitek、Ondato | 申请人 ID、服务商用户 ID、决策状态、证件字段、证件图像、自拍/活体图像、拒绝标签、标签、服务商原始元数据 | 使用 `import_type=user_verification`。如果服务商无法导出图像，请仅导入结构化字段，并将图像 URL 留空。 | | KYB 服务商 | 公司登记服务商、Sumsub KYB、Trulioo KYB、Creditsafe 类登记导出数据、内部 KYB 工具 | 公司名称、注册号、国家/地区、登记状态、高管人员、实际受益人、风险等级、原始登记 payload | 使用 `import_type=business_verification`。高管人员和 UBO 以 JSON 数组形式传入。 | | 交易监控 / KYT 服务商 | Sumsub Transaction Monitoring、Chainalysis 类 KYT 导出数据、Crystal、Merkle Science、Sardine、Unit21、Alloy、内部规则引擎 | 交易 ID、金额、币种、方向、主体/交易对手、规则命中、服务商结果、Travel Rule 状态、网络图谱快照 | 使用 `import_type=transactions`。导入的交易属于历史记录，默认不会重新筛查。 | | 工作流与策略电子表格 | 合规策略导出文件、服务商规则表、内部风险电子表格 | 按功能设置的状态规则，例如“如果签发国家/地区为 X，则将身份证件验证设为审核中” | 使用 `import_type=status_rules`。规则在保存前会根据 Didit 的工作流字段目录进行校验。 | | 用户/档案数据存储 | CRM、客户数据库、服务商用户导出数据、数据仓库 | `vendor_data`、显示名称、元数据、标签、可信人脸图像 | 使用用户 API 和档案人脸上传。这与已完成的验证会话不同。 | | 黑名单/白名单数据 | 服务商欺诈名单、内部欺诈运营表格、退单名单、与制裁相关的内部名单 | 电子邮箱、电话、证件、钱包、地址、设备指纹、人脸、国家/地区、用户、企业 | 使用 Lists API。对于人脸图像，请使用专用的人脸上传 endpoint，以便 Didit 提取人脸特征向量。 |## 迁移流程1) 确定您要导入的是历史记录、档案、人脸、名单、交易还是规则。 2) 自行从旧服务商导出数据。请勿将旧服务商的 API 密钥发送给 Didit。 3) 将服务商导出的数据转换为对应的 Didit 标准 CSV 或 NDJSON 模板。 4) 对于大规模迁移，建议使用 NDJSON，并拆分为可独立重试的文件。 5) 创建导入任务并轮询进度。 6) 获取行错误，仅修复失败的行并重试。所有导入任务都以其自然外部 ID 实现幂等性。## 创建导入任务使用单个 multipart 请求创建导入任务：```bash theme={null} curl -X POST https://verification.didit.me/v3/session/imports/ \ -H "x-api-key: YOUR_API_KEY" \ -F "import_type=user_verification" \ -F "workflow_id=YOUR_KYC_WORKFLOW_ID" \ -F "file=@didit-import.ndjson" ```对于较小的、由电子表格驱动的迁移，请使用 CSV；对于大规模迁移，请使用 NDJSON。对于 100k+ 行的数据，NDJSON 更便于流式传输、拆分、校验和重试。每个应用最多可同时运行 4 个导入任务，因此请将大规模迁移拆分为多个文件，并为每个文件启动一个任务。每个任务会并行下载每行记录的媒体文件。因部署或工作进程重启而中断的任务，会从最后导入的行自动继续，无需您重新启动。导入交易时，请省略 `workflow_id`：```bash theme={null} curl -X POST https://verification.didit.me/v3/session/imports/ \ -H "x-api-key: YOUR_API_KEY" \ -F "import_type=transactions" \ -F "file=@didit-transactions.ndjson" ```### 请求字段| 字段 | 是否必填 | 说明 | | - | - | - | | `import_type` | 否，默认为 `user_verification` | 取值之一：`user_verification`、`business_verification`、`status_rules`、`transactions`。 | | `workflow_id` | 是，`transactions` 除外 | 导入记录所关联的工作流 UUID。`user_verification` 和 `status_rules` 需要用户验证工作流；`business_verification` 需要企业验证（KYB）工作流。 | | `file` | `file` 或 `source_file_url` 二选一 | 标准 CSV 或 NDJSON 文件，以内联方式上传。 | | `source_file_url` | `file` 或 `source_file_url` 二选一 | Didit 下载文件所用的 HTTPS URL。系统会拒绝内网 URL。 | | `source_format` | 否 | `csv` 或 `ndjson`。省略时根据文件扩展名推断。 |### 记录的跟踪与去重请求字段中没有数据来源参数：所有导入均使用 Didit 的标准架构。每条导入的记录都会存储 `metadata.imported_from = "generic"`，以便追溯。`user_verification` 和 `business_verification` 导入会在应用内按 `external_id` 对行去重，因此重试同一文件不会产生重复记录。`transactions` 导入则改为按 `transaction_id` 去重。服务商迁移（`source=provider`）会将每条记录存储为 `:`，例如 `sumsub:5f8c0e2a9b1d4c3e2f1a0b9c`。如果用户验证文件导入时发送的是服务商的纯 ID（`5f8c0e2a9b1d4c3e2f1a0b9c`），系统会将其识别为同一条记录，两个方向均适用。因此，您可以先通过文件开始迁移，再用服务商迁移完成，反之亦然，不会导入重复记录。## 导入证件照片、视频和自拍证据对于 `import_type=user_verification`，您可以从之前的服务商导入原始证件照片、证件/活体采集视频以及自拍照。请使用以下标准列：| 证据 | 首选列 | 小批量导入备用列 | 在 Didit 中的存储位置 | | - | - | - | - | | 证件正面图像 | `document_front_url` | `document_front_base64` | 身份证件验证 OCR 正面图像 | | 证件背面图像 | `document_back_url` | `document_back_base64` | 身份证件验证 OCR 背面图像 | | 自拍照 / 活体图像 | `selfie_url` | `selfie_base64` | 人脸/活体检测参考图像 | | 证件正面视频 | `document_front_video_url` | 仅支持 URL | 身份证件验证 OCR 正面视频 | | 证件背面视频 | `document_back_video_url` | 仅支持 URL | 身份证件验证 OCR 背面视频 | | 活体视频 | `liveness_video_url` | 仅支持 URL | 人脸/活体检测采集视频 |对于大批量迁移，请使用 **HTTPS URL**。Didit 会下载每个文件，验证 URL 是否安全，存储一份 Didit 自有副本，并将其关联到导入的会话。图片会被压缩；视频按原样存储。小批量导入时可以为图片内联 base64，但**视频必须始终以 URL 形式提供**，因为 base64 会使每个视频体积增加约 33%，很快就会超过单文件导入限制。以下是使用服务商托管媒体 URL 的 NDJSON 行示例：```json theme={null} { "external_id": "applicant-123", "vendor_data": "user-42", "created_at": "2025-01-12T10:30:00Z", "status": "Approved", "email": "user@example.com", "phone": "+34687020083", "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "document_type": "P", "issuing_state": "USA", "document_number": "123456789", "expiration_date": "2030-01-15", "document_front_url": "https://provider-export.example.com/files/applicant-123-front.jpg", "document_back_url": "https://provider-export.example.com/files/applicant-123-back.jpg", "selfie_url": "https://provider-export.example.com/files/applicant-123-selfie.jpg", "document_front_video_url": "https://provider-export.example.com/files/applicant-123-front.webm", "document_back_video_url": "https://provider-export.example.com/files/applicant-123-back.webm", "liveness_video_url": "https://provider-export.example.com/files/applicant-123-liveness.mp4", "reject_reasons_json": "[]", "provider_metadata_json": "{\"source\":\"sumsub-export\"}" } ```重要的媒体规则：- URL 必须使用 `https`。 - URL 不得解析为私有 IP、localhost、链路本地地址范围或内部元数据主机。 - 图片可以使用 URL 列，也可以使用对应的 `*_base64` 备用列；两者都设置时，以 base64 为准。视频仅支持 URL，不存在 `*_video_base64` 列。 - 视频必须为 `mp4`、`webm` 或 `mov` 格式，且每个视频最大 **10 MB**。超过大小限制或非视频文件将作为行错误被拒绝。 - Didit 强制执行连接/读取超时和最大文件大小限制，并且不会无限重试。 - 媒体下载失败会记录为行错误，不影响导入的其余部分继续进行。 - 如果服务商没有提供媒体，请将这些列留空。Didit 仍会导入结构化的决策和证件字段。 - 导入的图片和视频作为历史审核的证据。Didit 默认不会对导入的历史媒体重新运行 OCR、活体检测或证件欺诈分析。 用户验证导入提示 将提示词复制到剪贴板 \

\`You are helping migrate historical User Verification (KYC) sessions into Didit.

Goal:
Transform the customer's Sumsub, MetaMap, or provider export into Didit's canonical verification import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=user_verification
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for a User Verification workflow
\- Provider export file or API output

Canonical columns:
external_id, vendor_data, created_at, status, email, phone, first_name, last_name, date_of_birth, gender, nationality, document_type, issuing_state, document_number, personal_number, expiration_date, document_front_url, document_back_url, selfie_url, document_front_base64, document_back_base64, selfie_base64, document_front_video_url, document_back_video_url, liveness_video_url, is_blocklisted, reject_reasons_json, tags, provider_metadata_json

Rules:
\- phone is optional and accepts international format (for example +34687020083); it is stored on the imported session.
\- external_id must be the provider's unique verification/applicant id.
\- vendor_data must be the customer's stable user id. If absent, use the provider identity/user id.
\- status must be Approved, Declined, In Review, or Expired.
\- date_of_birth and expiration_date must use YYYY-MM-DD.
\- created_at must be ISO 8601.
\- nationality and issuing_state must be ISO-3166 alpha-3, for example USA, ESP, BRA.
\- document_type must use Didit codes: P, ID, DL, RP, SSC, HIC, WP, TC, VISA, PSC, BC, OTHER.
\- reject_reasons_json must be a JSON array. provider_metadata_json must be a JSON object.
\- Use document_front_url, document_back_url, and selfie_url when the provider can export evidence images. Use HTTPS media URLs for large imports. Avoid inline base64 unless the import is small.
\- Use document_front_video_url, document_back_video_url, and liveness_video_url to import capture videos. Videos must be mp4, webm, or mov and at most 10 MB each; otherwise the row is rejected.
\- If only one document side exists, fill document_front_url and leave document_back_url empty.
\- Never call the import API with provider credentials. The customer downloads provider data themselves.
\- The import is idempotent by external_id inside one Didit application, so retries are safe.

Steps:
1\. Inspect the provider export schema.
2\. Map each provider row to the canonical fields.
3\. Write NDJSON for large files; one JSON object per line.
4\. Validate the first 10 rows locally before uploading.
5\. Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=user_verification" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-import.ndjson"
6\. Poll until status is COMPLETED or FAILED.
7\. If failed_count is greater than 0, fetch /errors/ and produce a corrected file containing only failed rows.

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A short summary of created, skipped, and failed rows.`

\
粘贴到 企业验证导入提示 将提示词复制到剪贴板 \

\`You are helping migrate historical Business Verification (KYB) sessions into Didit.

Goal:
Transform the customer's KYB provider export into Didit's canonical business verification import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=business_verification
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for a Business Verification workflow
\- Provider export file or API output

Canonical business columns:
external_id, vendor_data, created_at, status, company_name, registration_number, country_code, registry_status, verification_status, company_type, tax_number, risk_level, incorporation_date, registered_address, is_from_registry, officers_json, beneficial_owners_json, provider_metadata_json, tags

Rules:
\- external_id must be the provider's unique business verification id.
\- vendor_data must be the customer's stable business id.
\- status must be Approved, Declined, In Review, or Expired.
\- country_code must be ISO-3166 alpha-3.
\- officers_json and beneficial_owners_json must be JSON arrays of objects.
\- provider_metadata_json must be a JSON object.
\- The import is idempotent by external_id inside one Didit application.

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=business_verification" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-business-import.ndjson"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A short summary of created, skipped, and failed rows.`

\
粘贴到 自定义状态规则导入提示 将提示词复制到剪贴板 \

\`You are helping import custom status rules into a Didit workflow.

Goal:
Transform the customer's policy spreadsheet into Didit's feature_status_rules format, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=status_rules
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for the workflow to update
\- A policy spreadsheet or JSON policy definition

Canonical status-rule columns:
feature, rules_json, mode

Rules:
\- feature must be a Didit feature key such as OCR, LIVENESS, FACE_MATCH, AML, KYB_REGISTRY, KYB_DOCUMENTS, or KYB_KEY_PEOPLE.
\- rules_json must be a JSON array of rule objects.
\- Each rule needs field, operator, status, and usually value.
\- mode is replace or append. Default is replace.
\- Do not reference status fields such as kyc.status; status rules compute status and must use other report fields.

Example rules_json:
\[{"field":"kyc.issuing_state","operator":"in","value":["VEN","IRN"],"status":"In Review"}]

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=status_rules" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-status-rules.csv"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A summary of updated and failed rule rows.`

\
粘贴到 交易导入提示 将提示词复制到剪贴板 \

\`You are helping migrate historical transaction monitoring records into Didit.

Goal:
Transform the customer's legacy transaction monitoring export into Didit's canonical transaction import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=transactions
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- A transaction export file or API output

Canonical transaction columns:
transaction_id, transaction_at, transaction_category, direction, amount, currency, currency_kind, amount_in_default_currency, default_currency, payment_details, payment_reference_id, action_type, status, score, severity, subject_json, counterparty_json, custom_properties_json, provider_results_json, travel_rule_json, network_snapshot_json, metadata_json

Rules:
\- transaction_id is required and is idempotent per Didit application.
\- transaction_category must be one of Didit's transaction categories, for example finance, kyc, travelRule, userPlatformEvent, gamblingBet, gamblingLimitChange, gamblingBonusChange, or auditTrailEvent.
\- direction must be INBOUND or OUTBOUND.
\- status must be APPROVED, IN_REVIEW, DECLINED, or AWAITING_USER.
\- subject_json must include vendor_data and full_name.
\- counterparty_json is optional but should be included when the legacy provider has it.
\- provider_results_json must be a JSON array.
\- travel_rule_json, network_snapshot_json, custom_properties_json, and metadata_json must be JSON objects when present.

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=transactions" \
-F "file=@didit-transactions.ndjson"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A summary of created, skipped, and failed transaction rows.`

\
粘贴到 ## 轮询进度```bash theme={null} curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \ -H "x-api-key: YOUR_API_KEY" ```响应包含 `status`、`import_type`、`total_rows`、`processed_rows`、`created_count`、`updated_count`、`skipped_count`、`failed_count` 和 `checkpoint_row`。## 下载行错误```bash theme={null} curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \ -H "x-api-key: YOUR_API_KEY" ```每个错误包含 `row_number`、`external_id`、`error` 和 `raw_row`，以便您只修复失败的行并重试。## 滥用防护通过 `POST /v3/session/imports/` 发起的历史导入任务默认处于禁用状态。Didit 会在审核后按组织启用此功能，因为这些任务可能处理数百万行数据并下载媒体。本指南中的常规运营数据导入（创建用户、创建企业、上传用户档案人脸、上传人脸黑名单，或添加名单条目）除正常的 API 密钥权限、产品可用性和这些端点的速率限制外，无需特别的迁移启用。历史导入任务还运行在隔离的工作节点上，并设有文件大小限制、行数预算、仅限 HTTPS 的媒体 URL、私有网络 URL 拦截，以及每个应用最多 4 个活跃导入任务的限制，并会记录每行的错误。## 标准状态| 服务商结果 | Didit 状态 | | - | - | | Approved / Green / Verified | `Approved` | | Declined / Red / Rejected | `Declined` | | Manual review / Pending / Review needed | `In Review` | | Incomplete / Init / Unknown historical row | `Expired` |## 幂等性Didit 将 `external_id` 用作用户验证和企业验证导入的幂等键，按应用范围限定。交易导入使用 `transaction_id`，同样按应用范围限定。重复导入同一文件时，会跳过已导入的行，并创建尚未处理的行。## 导入用户、个人资料人脸和黑名单如果您不需要重建已完成的验证会话，请使用以下路径：### 导入用户资料使用 [`POST /v3/users/create/`](https://docs.didit.me/zh/management-api/users/create) 创建用户，或通过 [导入和导出用户](https://docs.didit.me/zh/entities/users/import-export.md) 中的 Business Console CSV 导入功能创建用户。此操作只会创建或更新 `VendorUser` 资料，不会创建验证会话、KYC 决策、证件报告、警告或 Webhook 历史记录。当您希望 Didit 在后续检查前就知道某位客户的存在，或需要补充 `display_name`、标签或元数据等类似 CRM 的字段时，请使用此方式。### 上传可信的个人资料人脸用户存在后，使用 [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/zh/management-api/users/upload-face) 上传可信的资料人脸。此操作会将生物特征证据关联到用户资料，并为其建立索引，以用于重复检测和人脸搜索。此操作**不会**将该人脸加入黑名单。如果您有来自此前 KYC 服务商的可信的个人资料图像，并希望 Didit 在未来的检查中与之比对，可以使用此方式。### 导入人脸黑名单和白名单如需直接拦截或放行某张人脸，请使用 [`POST /v3/lists/{list_uuid}/entries/face-upload/`](https://docs.didit.me/zh/management-api/lists/upload-face)，并使用人脸类型名单。Didit 会提取生物特征向量并保存为名单条目。此方式适用于已知欺诈者图像、可信白名单人脸，或服务商欺诈名单的迁移。如果人脸来自已有的 Didit 会话，请优先使用 [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/zh/management-api/lists/create-entry) 并传入 `reference_session_id`。Didit 会从该会话中提取正确的人脸，并将条目与来源关联。### 导入用户、企业、证件、钱包、邮箱、电话、IP 或设备名单对于非人脸类名单的值，请使用 [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/zh/management-api/lists/create-entry)。此路径适用于服务商黑名单、白名单、拒付名单、钱包地址、已知风险 IP、设备指纹、证件号码、邮箱、电话、用户或企业。## 后续步骤> [card] [导入用户](https://docs.didit.me/zh/entities/users/import-export.md) > > 加载用户资料并关联可信的个人资料人脸。> [card] [导入企业](https://docs.didit.me/zh/entities/businesses/import-export.md) > > 在执行 KYB 之前加载企业资料。> [card] [上传资料人脸](https://docs.didit.me/zh/management-api/users/upload-face.md) > > 为已导入的用户关联可信人脸图像。> [card] [向名单上传人脸](https://docs.didit.me/zh/management-api/lists/upload-face.md) > > 将人脸添加到黑名单或白名单。> [card] [创建名单条目](https://docs.didit.me/zh/management-api/lists/create-entry.md) > > 将电话、邮箱、钱包、证件、IP、设备、用户或企业导入名单。> [card] [速率限制](https://docs.didit.me/zh/integration/rate-limiting.md) > > 设计安全的迁移循环与重试机制。 ## OpenAPI ````yaml zh/openapi-25.json POST /v3/session/imports/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/session/imports/: post: tags: - Sessions summary: 创建验证导入任务 description: >- 为历史用户验证会话、企业验证会话、交易监控记录或工作流自定义状态规则创建异步导入任务。设置 `source=provider` 以从其他提供商迁移：Didit 使用您的只读密钥读取 Sumsub、Onfido、Persona 和 ComplyCube；通过您在 `file` 中上传的 ID 读取 Veriff、iDenfy 和 MetaMap 记录；对于其他提供商，则导入 Didit 格式的导出文件。记录 ID 按提供商进行命名空间隔离（`sumsub:`），因此重新运行会跳过 Didit 中已存在的所有内容；通过包含提供商裸 ID 的文件导入的记录也能双向被识别，因此在文件导入与提供商迁移之间切换绝不会重复导入记录。一个应用最多可同时运行 4 个导入任务；因部署或工作进程重启而中断的任务会自动从上次导入的行继续。导入功能默认处于禁用状态，必须由 Didit 按组织单独启用。 operationId: post_v3_session_imports_create requestBody: required: true content: multipart/form-data: schema: type: object properties: import_type: type: string enum: - user_verification - business_verification - status_rules - transactions default: user_verification description: 要导入的内容：历史用户验证会话、历史企业验证会话、工作流自定义状态规则或历史交易监控记录。 workflow_id: type: string format: uuid description: >- 导入的会话或状态规则应关联的工作流 UUID。对于 user_verification、business_verification 和 status_rules 为必填项。对于 transactions 请省略。 source_format: type: string enum: - csv - ndjson description: 可选。如果省略，将根据上传文件的扩展名推断。 file: type: string format: binary description: >- 规范的 CSV 或 NDJSON 文件。大批量导入请使用 NDJSON。最大上传大小 25 MB（更大的文件请使用 `source_file_url`）。与 `source_file_url` 互斥。 source_file_url: type: string format: uri description: 文件上传的替代方案。必须是解析为公共地址的 HTTPS URL（私有/回环网络将被拒绝）。与 `file` 互斥。 source: type: string enum: - file - provider description: '`provider` 表示这是从另一家身份证件验证服务商进行的迁移。文件导入时请省略。' provider: type: string enum: - sumsub - jumio - veriff - onfido - persona - metamap - socure - idnow - shufti - idenfy - ondato - trulioo - au10tix - complycube - other description: >- 迁移来源，来自 `GET /v3/session/imports/providers/`。当 `source` 为 `provider` 时必填。 credentials: type: object additionalProperties: type: string description: >- 服务商的只读密钥，其字段名称由 `credential_fields` 列出。静态加密存储，从不返回，并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。 options: type: object properties: region: type: string description: 服务商区域，为其 `regions` 之一（Onfido：`eu`、`us`、`ca`）。 status_mapping: type: object additionalProperties: type: string enum: - Approved - Declined - In Review - Expired - Not Finished - Abandoned description: >- 对提供商默认状态映射的修改：将源状态映射到 Didit 状态。`Not Finished` 和 `Abandoned` 会被跳过并计数，绝不会被导入。 dry_run: type: boolean default: false description: >- 统计迁移将导入的内容（按状态、已在 Didit 中、同一人、未完成划分）且不写入任何内容。任务结束状态为 `READY`；使用 `POST /v3/session/imports/{importId}/start/` 启动它。 face_templates: type: boolean default: false description: >- 根据导入的自拍照构建人脸模板，并对照应用的人脸库和黑名单进行搜索。匹配项仅会被标记以供审核。需要 `lawful_basis_confirmed`。 lawful_basis_confirmed: type: boolean default: false description: 确认您拥有合法依据将这些自拍照共享给作为处理者的 Didit。 application/json: schema: type: object required: - source_file_url properties: import_type: type: string enum: - user_verification - business_verification - status_rules - transactions default: user_verification description: 要导入的内容：历史用户验证会话、历史企业验证会话、工作流自定义状态规则或历史交易监控记录。 workflow_id: type: string format: uuid description: >- 导入的会话或状态规则应关联的工作流 UUID。对于 user_verification、business_verification 和 status_rules 为必填项。对于 transactions 请省略。 source_format: type: string enum: - csv - ndjson description: 可选。如果省略，将根据 URL 的文件扩展名推断。 source_file_url: type: string format: uri description: 文件上传的替代方案。必须是解析为公共地址的 HTTPS URL（私有/回环网络将被拒绝）。与 `file` 互斥。 source: type: string enum: - file - provider description: '`provider` 表示这是从另一家身份证件验证服务商进行的迁移。文件导入时请省略。' provider: type: string enum: - sumsub - jumio - veriff - onfido - persona - metamap - socure - idnow - shufti - idenfy - ondato - trulioo - au10tix - complycube - other description: >- 迁移来源，来自 `GET /v3/session/imports/providers/`。当 `source` 为 `provider` 时必填。 credentials: type: object additionalProperties: type: string description: >- 服务商的只读密钥，其字段名称由 `credential_fields` 列出。静态加密存储，从不返回，并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。 options: type: object properties: region: type: string description: 服务商区域，为其 `regions` 之一（Onfido：`eu`、`us`、`ca`）。 status_mapping: type: object additionalProperties: type: string enum: - Approved - Declined - In Review - Expired - Not Finished - Abandoned description: >- 对提供商默认状态映射的修改：将源状态映射到 Didit 状态。`Not Finished` 和 `Abandoned` 会被跳过并计数，绝不会被导入。 dry_run: type: boolean default: false description: >- 统计迁移将导入的内容（按状态、已在 Didit 中、同一人、未完成划分）且不写入任何内容。任务结束状态为 `READY`；使用 `POST /v3/session/imports/{importId}/start/` 启动它。 face_templates: type: boolean default: false description: >- 根据导入的自拍照构建人脸模板，并对照应用的人脸库和黑名单进行搜索。匹配项仅会被标记以供审核。需要 `lawful_basis_confirmed`。 lawful_basis_confirmed: type: boolean default: false description: 确认您拥有合法依据将这些自拍照共享给作为处理者的 Didit。 examples: URL-based import: value: import_type: user_verification workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab source_file_url: https://files.example.com/exports/sessions.ndjson responses: '201': description: 导入任务已受理。轮询返回的 `uuid`，直至 `status` 变为 `COMPLETED` 或 `FAILED`。 content: application/json: schema: $ref: '#/components/schemas/SessionImportJob' examples: Job accepted: value: uuid: 3f9c1a2b-4d5e-4f60-8a7b-9c0d1e2f3a4b status: PENDING import_type: user_verification source_format: ndjson source_filename: sessions.ndjson total_rows: 0 processed_rows: 0 checkpoint_row: 0 created_count: 0 updated_count: 0 skipped_count: 0 failed_count: 0 total_media_bytes: 0 last_error: null created_at: '2026-05-17T08:42:11Z' updated_at: '2026-05-17T08:42:11Z' started_at: null completed_at: null '400': description: >- 无效的工作流、文件类型、文件大小、来源 URL 或选择器组合。对于提供商拒绝其密钥的迁移，将返回 `code`（`invalid_credentials`、`missing_permission`、`wrong_region`、`provider_unavailable`、`rate_limited`、`ids_required`、`record_not_found`）、`missing_permissions` 和 `suggested_region`。 content: application/json: examples: Invalid workflow: value: workflow_id: - Invalid workflow_id. Workflow required: value: workflow_id: - This field is required for this import type. Wrong file type: value: file: - Only CSV and NDJSON files are supported. File too large: value: file: - Import file exceeds the maximum allowed size. No source: value: file: - Upload a file or provide source_file_url. Both sources: value: file: - Use either file or source_file_url, not both. '403': description: >- 未启用导入、沙盒应用或缺少 API 密钥（错误、已撤销或已过期的密钥会返回 `401`）。验证导入默认处于禁用状态，必须由 Didit 按组织单独启用。 content: application/json: examples: Imports not enabled: value: detail: >- Verification imports are not enabled for this organization. Sandbox: value: detail: >- Verification imports are not enabled for sandbox applications. Bad API key: value: detail: You do not have permission to perform this action. '429': description: >- 该应用已有 4 个处于活动状态的导入任务（PENDING/PROCESSING/PAUSED），已达同时运行的最大数量。请等待其中一个完成后再启动另一个。 content: application/json: examples: Active job: value: detail: >- This application already has 4 active import jobs, the most it can run at once. Wait for one to finish before starting another. security: - ApiKeyAuth: [] x-codeSamples: - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.imports.create( import_type="user_verification", workflow_id="9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url="https://files.example.com/exports/sessions.ndjson", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.sessions.imports.create({ import_type: "user_verification", workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url: "https://files.example.com/exports/sessions.ndjson", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Create(ctx, didit.SessionsImportsCreateParams{\n\tImportType: didit.Some(didit.SessionsImportsCreateParamsImportType(\"user_verification\")),\n\tWorkflowID: didit.String(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\"),\n\tSourceFileURL: didit.String(\"https://files.example.com/exports/sessions.ndjson\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.SessionsImportsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().imports().create(SessionsImportsCreateParams.builder() .importType(SessionsImportsCreateParams.ImportType.of("user_verification")) .workflowId("9f9b1234-aaaa-bbbb-cccc-1234567890ab") .sourceFileUrl("https://files.example.com/exports/sessions.ndjson") .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->imports->create([ 'import_type' => 'user_verification', 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab', 'source_file_url' => 'https://files.example.com/exports/sessions.ndjson', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.imports.create( import_type: "user_verification", workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url: "https://files.example.com/exports/sessions.ndjson" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Sessions.Imports.CreateAsync(new SessionsImportsCreateParams { ImportType = new SessionsImportsCreateParamsImportType("user_verification"), WorkflowId = "9f9b1234-aaaa-bbbb-cccc-1234567890ab", SourceFileUrl = "https://files.example.com/exports/sessions.ndjson", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionImportJob: type: object required: - uuid - status - import_type - source_format - source_filename - total_rows - processed_rows - created_count - updated_count - skipped_count - failed_count properties: uuid: type: string format: uuid description: 导入任务 ID。使用此值轮询进度并获取行级错误。 status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - PAUSED - CANCELLED - READY import_type: type: string enum: - user_verification - business_verification - status_rules - transactions source_format: type: string enum: - csv - ndjson source_filename: type: string total_rows: type: integer format: int64 processed_rows: type: integer format: int64 checkpoint_row: type: integer format: int64 created_count: type: integer format: int64 updated_count: type: integer format: int64 skipped_count: type: integer format: int64 failed_count: type: integer format: int64 total_media_bytes: type: integer format: int64 last_error: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true state: type: string enum: - ready - queued - running - paused - completed - errors - failed - cancelled description: 控制台显示的任务状态；`errors` 表示任务已完成但存在被拒绝的行。 source: type: string enum: - file - api - provider provider: type: string description: 迁移来源；对于文件或 API 导入则为空。 provider_options: type: object credential_hint: type: string description: 迁移所保存密钥的前几个字符。密钥本身永远不会返回。 credentials_expires_at: type: string format: date-time nullable: true resumes_at: type: string format: date-time nullable: true description: 因提供商速率限制而暂停的任务自行恢复的时间。 status_mapping: type: object additionalProperties: type: string is_dry_run: type: boolean dry_run_summary: type: object description: >- 试运行发现的内容：`total`、`by_status`、`already_in_didit`、`same_person`、`not_finished`、`failed`、`unmapped_statuses`。 face_templates_enabled: type: boolean lawful_basis_confirmed_at: type: string format: date-time nullable: true not_finished_count: type: integer format: int64 same_person_count: type: integer format: int64 face_templates_count: type: integer format: int64 face_duplicates_count: type: integer format: int64 face_blocklist_hits_count: type: integer format: int64 created_by_name: type: string nullable: true created_by_email: type: string nullable: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.