> ## 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.
# Importar verificaciones y datos desde otro proveedor
> Elige en Didit la vía de importación adecuada para sesiones históricas, usuarios, rostros, listas de bloqueo, empresas, transacciones y reglas.
Usa esta guía para elegir la vía de importación adecuada cuando traslades datos de otro proveedor a Didit. Los clientes suelen llamar "importación" a dos tareas distintas:- **Importar el historial de verificaciones**: recrea registros completados de KYC, KYB, monitorización de transacciones o reglas de flujo para que Didit muestre el historial del proveedor anterior. Usa `POST /v3/session/imports/`.
- **Importar datos operativos**: crea usuarios, empresas, rostros de perfil, entradas de lista de bloqueo o entradas de lista de permitidos para que Didit pueda usarlos en verificaciones futuras. Usa las API de entidades, rostros y listas.Las importaciones de verificaciones crean registros históricos con `session_type: "MIGRATED"` para KYC y KYB. No envían correos electrónicos al usuario final, no redirigen a los usuarios al flujo alojado y no vuelven a ejecutar la verificación original. Los registros importados aparecen en las listas de sesiones, los perfiles de entidades, las vistas de transacciones y en `GET /v3/session/{session_id}/decision/` cuando corresponde.## Qué importación debes usar| Objetivo | Ruta de importación | Qué crea | Ideal para |
| - | - | - | - |
| Recrear sesiones KYC históricas | `POST /v3/session/imports/` con `import_type=user_verification` | `Session`, datos de Verificación de identidad, imágenes opcionales del documento y del selfie, videos del documento y de la prueba de vida, etiquetas, metadatos | Trasladar solicitantes que han completado el proceso desde Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo u otro proveedor de KYC |
| Recrear sesiones KYB históricas | `POST /v3/session/imports/` con `import_type=business_verification` | `BusinessSession`, datos registrales de la empresa, administradores, beneficiarios finales, etiquetas, metadatos | Trasladar verificaciones de empresas completadas desde proveedores de KYB, proveedores de registros de empresas o herramientas internas de KYB |
| Recrear registros históricos de monitorización de transacciones | `POST /v3/session/imports/` con `import_type=transactions` | `Transaction`, partes del sujeto y de la contraparte, resultados del proveedor, datos de Travel Rule, instantánea de la red, metadatos | Trasladar el historial de motores de reglas, KYT, análisis de wallets o monitorización de transacciones fiat |
| Importar reglas de estado personalizadas del flujo | `POST /v3/session/imports/` con `import_type=status_rules` | `VerificationSettings.feature_status_rules` | Trasladar la lógica de políticas desde otro proveedor o una hoja de cálculo al motor de flujos de Didit |
| Crear Users sin sesiones históricas | `POST /v3/users/create/` o importación CSV desde la Console | Filas de perfil `VendorUser` | Cargar tu lista de usuarios antes de iniciar nuevas verificaciones en Didit |
| Asociar rostros de perfil de confianza a los usuarios | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` | Evidencia de rostro de perfil indexada para la detección de duplicados y la búsqueda facial | Migrar imágenes de rostros de perfil desde otro proveedor de KYC sin recrear sesiones completas |
| Añadir rostros a la lista de bloqueo o a la lista de permitidos | `POST /v3/lists/{list_uuid}/entries/face-upload/` o `POST /v3/lists/{list_uuid}/entries/` con `reference_session_id` | Entrada de lista de rostros y embedding biométrico | Migrar rostros de fraude conocidos o rostros de confianza de la lista de permitidos, o añadir a la lista de bloqueo un rostro de una sesión de Didit existente |
| Crear Businesses sin sesiones KYB históricas | `POST /v3/businesses/create/` o importación CSV desde la Console | Filas de perfil `VendorBusiness` | Cargar una lista de clientes empresariales antes de ejecutar KYB |> [!NOTE]
>
> Si solo necesitas un perfil de usuario o de empresa para verificaciones futuras, no importes una sesión de verificación histórica. Usa las API de las entidades User o Business. Si necesitas que la decisión, los campos del documento, las advertencias o la evidencia del proveedor anterior aparezcan como historial de cumplimiento en Didit, usa `POST /v3/session/imports/`.## Qué se puede migrar desde cada proveedorDidit acepta un archivo CSV o NDJSON canónico, así que puedes migrar desde cualquier proveedor una vez que exportes y transformes los datos. El contrato de importación es siempre el esquema canónico de Didit.| Tipo de proveedor | Fuentes habituales | Normalmente migrable | Notas |
| - | - | - | - |
| Proveedores de KYC | Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, HyperVerge, AU10TIX, Mitek, Ondato | ID del solicitante, ID de usuario del proveedor, estado de la decisión, campos del documento, imágenes del documento, imagen de selfie/prueba de vida, etiquetas de rechazo, etiquetas, metadatos sin procesar del proveedor | Usa `import_type=user_verification`. Si el proveedor no puede exportar imágenes, importa los campos estructurados y deja vacías las URL de las imágenes. |
| Proveedores de KYB | Proveedores de registros de empresas, Sumsub KYB, Trulioo KYB, exportaciones de registros al estilo de Creditsafe, herramientas internas de KYB | Nombre de la empresa, número de registro, país, estado en el registro, administradores, beneficiarios finales, nivel de riesgo, payload sin procesar del registro | Usa `import_type=business_verification`. Los administradores y los UBO se envían como arrays JSON. |
| Proveedores de monitorización de transacciones / KYT | Sumsub Transaction Monitoring, exportaciones de KYT al estilo de Chainalysis, Crystal, Merkle Science, Sardine, Unit21, Alloy, motores de reglas internos | ID de la transacción, importe, moneda, dirección del flujo, sujeto/contraparte, coincidencias de reglas, resultados del proveedor, estado de Travel Rule, instantánea del grafo de red | Usa `import_type=transactions`. Las transacciones importadas son registros históricos; por defecto no se vuelven a analizar. |
| Hojas de cálculo de flujos de trabajo y políticas | Exportaciones de políticas de cumplimiento, tablas de reglas del proveedor, hojas de cálculo internas de riesgo | Reglas de estado por función, como "si el país emisor es X, establecer Verificación de identidad en En revisión" | Usa `import_type=status_rules`. Las reglas se validan contra el catálogo de campos del flujo de trabajo de Didit antes de guardarse. |
| Almacenes de usuarios/perfiles | CRM, base de datos de clientes, exportación de usuarios del proveedor, data warehouse | `vendor_data`, nombre visible, metadatos, etiquetas, imágenes faciales de confianza | Usa las APIs de usuarios y la carga de imágenes faciales de perfil. Esto no es lo mismo que una sesión de verificación completada. |
| Datos de listas de bloqueo / listas de permitidos | Listas de fraude del proveedor, hojas internas de operaciones antifraude, listas de contracargos, listas internas relacionadas con sanciones | Correos electrónicos, teléfonos, documentos, wallets, direcciones IP, huellas digitales de dispositivos, rostros, países, usuarios, empresas | Usa las APIs de listas. Para imágenes faciales, usa el endpoint específico de carga de imágenes faciales para que Didit pueda extraer el embedding biométrico. |## Flujo de migración1) Decide si vas a importar historial, perfiles, rostros, listas, transacciones o reglas.
2) Exporta tú mismo los datos del proveedor anterior. No envíes a Didit las claves de API del proveedor anterior.
3) Transforma la exportación del proveedor en la plantilla canónica CSV o NDJSON de Didit correspondiente.
4) Para migraciones grandes, da preferencia a NDJSON y divide los datos en archivos que puedas reintentar de forma independiente.
5) Crea el trabajo de importación y consulta su progreso.
6) Obtén los errores por fila, corrige solo las filas fallidas y vuelve a intentarlas. Todos los trabajos de importación son idempotentes respecto a su ID externo natural.## Crear un trabajo de importaciónCrea un trabajo de importación con una única solicitud 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"
```Usa CSV para migraciones más pequeñas basadas en hojas de cálculo y NDJSON para migraciones grandes. Para 100k+ filas, NDJSON es más fácil de procesar en streaming, dividir, validar y reintentar.Para importaciones de transacciones, omite `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"
```### Campos de la solicitud| Campo | Obligatorio | Descripción |
| - | - | - |
| `import_type` | No, por defecto es `user_verification` | Uno de `user_verification`, `business_verification`, `status_rules`, `transactions`. |
| `workflow_id` | Sí, excepto para `transactions` | UUID del flujo al que se asocian los registros importados. `user_verification` y `status_rules` requieren un flujo de Verificación de usuarios; `business_verification` requiere un flujo de Verificación de empresas. |
| `file` | `file` o `source_file_url` | El archivo CSV o NDJSON canónico, subido directamente en la solicitud. |
| `source_file_url` | `file` o `source_file_url` | URL HTTPS desde la que Didit descarga el archivo. Se rechazan las URL de redes privadas. |
| `source_format` | No | `csv` o `ndjson`. Si se omite, se deduce de la extensión del archivo. |### Cómo se rastrean y deduplican los registrosNo existe ningún campo de la solicitud para la fuente de datos: todas las importaciones usan el esquema canónico de Didit. Cada registro importado almacena `metadata.imported_from = "generic"` para su trazabilidad.Las importaciones `user_verification` y `business_verification` deduplican las filas por `external_id` dentro de la aplicación, por lo que reintentar el mismo archivo no creará duplicados. Las importaciones `transactions` deduplican por `transaction_id` en su lugar.## Importar fotos de documentos, videos y evidencia de selfieCon `import_type=user_verification`, puedes importar las fotos originales del documento, los videos de captura del documento y de la prueba de vida, y la imagen de la selfie del proveedor anterior.Usa estas columnas canónicas:| Evidencia | Columna preferida | Alternativa para importaciones pequeñas | Se almacena en Didit como |
| - | - | - | - |
| Imagen frontal del documento | `document_front_url` | `document_front_base64` | Imagen frontal de OCR de Verificación de identidad |
| Imagen trasera del documento | `document_back_url` | `document_back_base64` | Imagen trasera de OCR de Verificación de identidad |
| Imagen de selfie / prueba de vida | `selfie_url` | `selfie_base64` | Imagen de referencia de rostro/prueba de vida |
| Video frontal del documento | `document_front_video_url` | Solo URL | Video frontal de OCR de Verificación de identidad |
| Video trasero del documento | `document_back_video_url` | Solo URL | Video trasero de OCR de Verificación de identidad |
| Video de prueba de vida | `liveness_video_url` | Solo URL | Video de captura de rostro/prueba de vida |En migraciones grandes, usa **URL HTTPS**. Didit descarga cada archivo, comprueba que la URL sea segura, almacena una copia propiedad de Didit y la vincula a la sesión importada. Las imágenes se comprimen; los videos se almacenan tal cual. En importaciones pequeñas se acepta base64 en línea para las imágenes, pero **los videos siempre deben proporcionarse como URL**: base64 aumentaría el tamaño de cada video en un \~33% y superaría rápidamente el límite de importación por archivo.Ejemplo de fila NDJSON con URLs de archivos multimedia alojados por el proveedor:```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\"}"
}
```Reglas importantes sobre los archivos multimedia:- Las URL deben usar `https`.
- Las URL no deben resolverse a direcciones IP privadas, localhost, rangos link-local ni hosts internos de metadatos.
- Las imágenes aceptan una columna de URL o su alternativa `*_base64`; si se definen ambas, base64 tiene prioridad. Los videos solo admiten URL: no existe ninguna columna `*_video_base64`.
- Los videos deben estar en formato `mp4`, `webm` o `mov`, y cada video puede ocupar como máximo **10 MB**. Los archivos más grandes o que no sean de video se rechazan como errores de fila.
- Didit aplica tiempos de espera de conexión y lectura y un tamaño máximo de archivo, y no realiza reintentos infinitos.
- Los fallos de descarga de archivos multimedia se almacenan como errores de fila para que el resto de la importación pueda continuar.
- Si no tienes archivos multimedia del proveedor, deja estas columnas vacías. Didit sigue importando la decisión estructurada y los campos del documento.
- Las imágenes y los videos importados son evidencia para la revisión histórica. De forma predeterminada, Didit no vuelve a ejecutar el OCR, la prueba de vida ni el análisis de fraude documental sobre los medios históricos importados.
Prompt de importación de verificaciones de usuarios
Copiar el prompt al portapapeles
\
\`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.`
\
Pegar en
Prompt de importación de verificaciones de empresas
Copiar el prompt al portapapeles
\
\`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.`
\
Pegar en
Prompt de importación de reglas de estado personalizadas
Copiar el prompt al portapapeles
\
\`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.`
\
Pegar en
Prompt de importación de transacciones
Copiar el prompt al portapapeles
\
\`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.`
\
Pegar en
## Consultar el progreso```bash theme={null}
curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \
-H "x-api-key: YOUR_API_KEY"
```La respuesta incluye `status`, `import_type`, `total_rows`, `processed_rows`, `created_count`, `updated_count`, `skipped_count`, `failed_count` y `checkpoint_row`.## Descargar errores de filas```bash theme={null}
curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \
-H "x-api-key: YOUR_API_KEY"
```Cada error incluye `row_number`, `external_id`, `error` y `raw_row`, para que puedas corregir solo las filas fallidas y reintentar.## Protección contra abusosLos trabajos de importación histórica mediante `POST /v3/session/imports/` están desactivados de forma predeterminada. Didit habilita esta capacidad por organización tras una revisión, porque estos trabajos pueden procesar millones de filas y descargar archivos multimedia. Las importaciones normales de datos operativos de esta guía (crear usuarios, crear empresas, subir rostros de perfil, subir listas de bloqueo de rostros o añadir entradas a listas) no requieren ninguna habilitación especial de migración, más allá de los permisos normales de la clave de API, la disponibilidad del producto y los límites de solicitudes de esos endpoints.Además, los trabajos de importación histórica se ejecutan en workers aislados con límites de tamaño de archivo, límites de filas, URL de archivos multimedia que solo usan HTTPS, bloqueo de URL de redes privadas, límites de trabajos activos por aplicación y registro de errores por fila.## Estados canónicos| Resultado del proveedor | Estado en Didit |
| - | - |
| Aprobado / Verde / Verificado | `Approved` |
| Rechazado / Rojo / Denegado | `Declined` |
| Revisión manual / Pendiente / Requiere revisión | `In Review` |
| Incompleto / Inicial / Fila histórica desconocida | `Expired` |## IdempotenciaDidit usa `external_id` como clave de idempotencia de importación para las importaciones de verificación de usuarios y verificación de empresas, con alcance por aplicación. Las importaciones de transacciones usan `transaction_id` por aplicación. Al reintentar el mismo archivo, se omiten las filas que ya se importaron y se crean las que aún no se habían procesado.## Importar usuarios, rostros de perfil y listas de bloqueoUsa estas vías cuando no estés recreando una sesión de verificación completada:### Importar perfiles de usuarioCrea usuarios con [`POST /v3/users/create/`](https://docs.didit.me/es/management-api/users/create) o con la importación CSV de Business Console descrita en [Importar y exportar usuarios](https://docs.didit.me/es/entities/users/import-export.md). Esto solo crea o actualiza el perfil `VendorUser`. No crea una sesión de verificación, una decisión de KYC, un informe de documento, advertencias ni historial de webhooks.Úsalo cuando quieras que Didit sepa que el cliente existe antes de futuras comprobaciones, o cuando necesites completar con datos históricos campos de tipo CRM como `display_name`, etiquetas o metadatos.### Subir rostros de perfil de confianzaUna vez que exista el usuario, sube un rostro de perfil de confianza con [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/es/management-api/users/upload-face). Esto asocia evidencia biométrica al perfil del usuario y la indexa para la detección de duplicados y la búsqueda facial.Esto **no** añade el rostro a una lista de bloqueo. Resulta útil cuando tienes una imagen de perfil de confianza de un proveedor de KYC anterior y quieres que las futuras comprobaciones de Didit la usen como referencia.### Importar listas de bloqueo y listas de permitidos de rostrosPara bloquear o permitir un rostro directamente, usa [`POST /v3/lists/{list_uuid}/entries/face-upload/`](https://docs.didit.me/es/management-api/lists/upload-face) con una lista de tipo rostro. Didit extrae el embedding biométrico y almacena una entrada en la lista.Úsalo para imágenes de estafadores conocidos, rostros de confianza de listas de permitidos o migraciones de listas de fraude de un proveedor. Si el rostro procede de una sesión de Didit existente, es preferible usar [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/es/management-api/lists/create-entry) con `reference_session_id`; Didit extrae el rostro correcto de la sesión y vincula la entrada con su origen.### Importar listas de usuarios, empresas, documentos, wallets, correos electrónicos, teléfonos, IP o dispositivosUsa [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/es/management-api/lists/create-entry) para valores de listas que no sean rostros. Es la vía adecuada para listas de bloqueo de proveedores, listas de permitidos, listas de contracargos, direcciones de wallets, direcciones IP de riesgo conocidas, huellas digitales de dispositivos, números de documento, correos electrónicos, teléfonos, usuarios o empresas.## Próximos pasos> [card] [Importar usuarios](https://docs.didit.me/es/entities/users/import-export.md)
>
> Carga perfiles de usuario y asocia rostros de perfil de confianza a ellos.> [card] [Importar empresas](https://docs.didit.me/es/entities/businesses/import-export.md)
>
> Carga perfiles de empresa antes de ejecutar el KYB.> [card] [Subir rostro de perfil](https://docs.didit.me/es/management-api/users/upload-face.md)
>
> Asocia imágenes faciales de confianza a los usuarios importados.> [card] [Subir rostro a una lista](https://docs.didit.me/es/management-api/lists/upload-face.md)
>
> Añade rostros a listas de bloqueo o listas de permitidos.> [card] [Crear entrada de lista](https://docs.didit.me/es/management-api/lists/create-entry.md)
>
> Importa teléfonos, correos electrónicos, wallets, documentos, direcciones IP, dispositivos, usuarios o empresas a listas.> [card] [Límites de solicitudes](https://docs.didit.me/es/integration/rate-limiting.md)
>
> Diseña bucles de migración y reintentos seguros.
## OpenAPI
````yaml es/openapi-25.json POST /v3/session/imports/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificación de identidad. Autentícate con el encabezado x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/imports/:
post:
tags:
- Sessions
summary: Crear un trabajo de importación de verificaciones
description: >-
Crea un trabajo de importación asíncrono para sesiones históricas de
Verificación de usuarios, sesiones de Verificación de empresas,
registros de monitorización de transacciones o reglas de estado
personalizado de flujos. Establece `source=provider` para migrar desde
otro proveedor. Didit lee Sumsub, Onfido, Persona y ComplyCube con tu
clave de solo lectura. Lee los registros de Veriff, iDenfy y MetaMap a
partir de los ID que subes en `file`. Para los demás proveedores,
importa un archivo de exportación en el formato de Didit. Los ID de los
registros llevan el proveedor como espacio de nombres (`sumsub:`),
así que una nueva ejecución omite todo lo que ya está en Didit. Las
importaciones están desactivadas por defecto y Didit debe activarlas
para cada organización.
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: >-
Qué importar: sesiones históricas de Verificación de
usuarios, sesiones históricas de Verificación de empresas,
reglas de estado personalizadas del flujo o registros
históricos de monitorización de transacciones.
workflow_id:
type: string
format: uuid
description: >-
UUID del flujo al que deben asociarse las sesiones
importadas o las reglas de estado. Obligatorio para
user_verification, business_verification y status_rules.
Omítelo para transactions.
source_format:
type: string
enum:
- csv
- ndjson
description: >-
Opcional. Si se omite, se deduce de la extensión del archivo
subido.
file:
type: string
format: binary
description: >-
Archivo CSV o NDJSON canónico. Usa NDJSON para importaciones
grandes. Tamaño máximo de subida: 25 MB (usa
`source_file_url` para archivos más grandes). Mutuamente
excluyente con `source_file_url`.
source_file_url:
type: string
format: uri
description: >-
Alternativa a la subida de un archivo. Debe ser una URL
HTTPS que resuelva a una dirección pública (se rechazan las
redes privadas y de loopback). Es mutuamente excluyente con
`file`.
source:
type: string
enum:
- file
- provider
description: >-
`provider` convierte esto en una migración desde otro
proveedor de verificación de identidad. Omítelo para
importar un archivo.
provider:
type: string
enum:
- sumsub
- jumio
- veriff
- onfido
- persona
- metamap
- socure
- idnow
- shufti
- idenfy
- ondato
- trulioo
- au10tix
- complycube
- other
description: >-
Origen de la migración, obtenido de `GET
/v3/session/imports/providers/`. Obligatorio cuando `source`
es `provider`.
credentials:
type: object
additionalProperties:
type: string
description: >-
La clave de solo lectura del proveedor, con los nombres de
campo que indica `credential_fields`. Se cifra en reposo,
nunca se devuelve y se borra cuando termina la importación.
Envíala como cadena JSON en multipart.
options:
type: object
properties:
region:
type: string
description: >-
La región del proveedor, una de sus `regions` (Onfido:
`eu`, `us`, `ca`).
status_mapping:
type: object
additionalProperties:
type: string
enum:
- Approved
- Declined
- In Review
- Expired
- Not Finished
- Abandoned
description: >-
Cambios en la correspondencia de estados predeterminada del
proveedor: del estado de origen al estado de Didit. `Not
Finished` y `Abandoned` se omiten y se contabilizan, pero
nunca se importan.
dry_run:
type: boolean
default: false
description: >-
Cuenta lo que importaría la migración (por estado, ya en
Didit, misma persona, sin finalizar) sin escribir nada. El
trabajo termina en `READY`. Inícialo con `POST
/v3/session/imports/{importId}/start/`.
face_templates:
type: boolean
default: false
description: >-
Genera plantillas faciales a partir de las selfies
importadas y búscalas entre los rostros y la lista de
bloqueo de la aplicación. Las coincidencias solo se marcan
para revisión. Requiere `lawful_basis_confirmed`.
lawful_basis_confirmed:
type: boolean
default: false
description: >-
Confirma que tienes una base legal para compartir estas
selfies con Didit como encargado del tratamiento.
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: >-
Qué importar: sesiones históricas de Verificación de
usuarios, sesiones históricas de Verificación de empresas,
reglas de estado personalizadas del flujo o registros
históricos de monitorización de transacciones.
workflow_id:
type: string
format: uuid
description: >-
UUID del flujo al que deben asociarse las sesiones
importadas o las reglas de estado. Obligatorio para
user_verification, business_verification y status_rules.
Omítelo para transactions.
source_format:
type: string
enum:
- csv
- ndjson
description: >-
Opcional. Si se omite, se deduce de la extensión del archivo
de la URL.
source_file_url:
type: string
format: uri
description: >-
Alternativa a la subida de un archivo. Debe ser una URL
HTTPS que resuelva a una dirección pública (se rechazan las
redes privadas y de loopback). Es mutuamente excluyente con
`file`.
source:
type: string
enum:
- file
- provider
description: >-
`provider` convierte esto en una migración desde otro
proveedor de verificación de identidad. Omítelo para
importar un archivo.
provider:
type: string
enum:
- sumsub
- jumio
- veriff
- onfido
- persona
- metamap
- socure
- idnow
- shufti
- idenfy
- ondato
- trulioo
- au10tix
- complycube
- other
description: >-
Origen de la migración, obtenido de `GET
/v3/session/imports/providers/`. Obligatorio cuando `source`
es `provider`.
credentials:
type: object
additionalProperties:
type: string
description: >-
La clave de solo lectura del proveedor, con los nombres de
campo que indica `credential_fields`. Se cifra en reposo,
nunca se devuelve y se borra cuando termina la importación.
Envíala como cadena JSON en multipart.
options:
type: object
properties:
region:
type: string
description: >-
La región del proveedor, una de sus `regions` (Onfido:
`eu`, `us`, `ca`).
status_mapping:
type: object
additionalProperties:
type: string
enum:
- Approved
- Declined
- In Review
- Expired
- Not Finished
- Abandoned
description: >-
Cambios en la correspondencia de estados predeterminada del
proveedor: del estado de origen al estado de Didit. `Not
Finished` y `Abandoned` se omiten y se contabilizan, pero
nunca se importan.
dry_run:
type: boolean
default: false
description: >-
Cuenta lo que importaría la migración (por estado, ya en
Didit, misma persona, sin finalizar) sin escribir nada. El
trabajo termina en `READY`. Inícialo con `POST
/v3/session/imports/{importId}/start/`.
face_templates:
type: boolean
default: false
description: >-
Genera plantillas faciales a partir de las selfies
importadas y búscalas entre los rostros y la lista de
bloqueo de la aplicación. Las coincidencias solo se marcan
para revisión. Requiere `lawful_basis_confirmed`.
lawful_basis_confirmed:
type: boolean
default: false
description: >-
Confirma que tienes una base legal para compartir estas
selfies con Didit como encargado del tratamiento.
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: >-
Trabajo de importación aceptado. Consulta el `uuid` devuelto hasta
que `status` sea `COMPLETED` o `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: >-
Flujo, tipo de archivo, tamaño de archivo, URL de origen o
combinación de selectores no válidos. Una migración cuya clave
rechaza el proveedor responde con `code` (`invalid_credentials`,
`missing_permission`, `wrong_region`, `provider_unavailable`,
`rate_limited`, `ids_required`, `record_not_found`),
`missing_permissions` y `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: >-
Importaciones no habilitadas, aplicación de sandbox o falta la clave
de API (una clave incorrecta, revocada o expirada devuelve `401`).
Las importaciones de verificaciones están deshabilitadas de forma
predeterminada y Didit debe habilitarlas para cada organización.
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: >-
La aplicación ya tiene un trabajo de importación activo
(PENDING/PROCESSING/PAUSED). Espera a que termine antes de iniciar
otro.
content:
application/json:
examples:
Active job:
value:
detail: >-
This application already has an active import job. Wait
for it 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 del trabajo de importación. Usa este valor para consultar el
progreso y obtener los errores de las filas.
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: >-
El estado del trabajo tal como lo muestra la consola; `errors` es un
trabajo completado con filas rechazadas.
source:
type: string
enum:
- file
- api
- provider
provider:
type: string
description: >-
Origen de la migración; vacío en una importación desde archivo o
API.
provider_options:
type: object
credential_hint:
type: string
description: >-
Los primeros caracteres de la clave que contiene la migración. La
clave en sí nunca se devuelve.
credentials_expires_at:
type: string
format: date-time
nullable: true
resumes_at:
type: string
format: date-time
nullable: true
description: >-
Cuándo se reanuda por sí solo un trabajo pausado por el límite de
solicitudes del proveedor.
status_mapping:
type: object
additionalProperties:
type: string
is_dry_run:
type: boolean
dry_run_summary:
type: object
description: >-
Qué encontró una ejecución de prueba: `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: >-
La clave de API de tu aplicación, que encontrarás en Developers -> API
keys en la Business Console. La clave principal tiene acceso completo.
Una clave con nombre puede tener un alcance limitado: ninguno, lectura o
escritura por recurso, limitada a algunos flujos o a sesiones aprobadas,
a una lista de direcciones IP y a una fecha de caducidad. 401 significa
que la clave es incorrecta, se revocó o expiró; 403 significa que no se
envió ninguna clave, que la clave no tiene acceso a este recurso o
acción, o que la solicitud provino de una dirección fuera de su lista de
IP; 404 en una ruta de sesión significa que la sesión está fuera de los
flujos o estados de la clave. Una clave sin acceso a contenido
multimedia recibe las URL de imágenes, videos y PDF como null, y una
clave sin permiso de escritura en sesiones recibe los enlaces y tokens
de sesión como null. Consulta https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.