> ## 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 dados de outro provedor
> A Didit importa sessões de verificação históricas, usuários, rostos, listas de bloqueio, empresas, transações e regras de status.
Use este guia para escolher o caminho de importação certo ao migrar dados de outro provedor para a Didit. Existem dois tipos diferentes de tarefas que os clientes costumam chamar de "importação":- **Importar o histórico de verificações**: recria registros concluídos de KYC, KYB, monitoramento de transações ou regras de fluxo para que a Didit exiba o histórico do provedor anterior. Use `POST /v3/session/imports/`.
- **Importar dados operacionais**: cria Usuários, Empresas, rostos de perfil, entradas de lista de bloqueio ou entradas de lista de permissão para que a Didit possa usá-los em verificações futuras. Use as APIs de entidades, rostos e listas.As importações de verificações criam registros históricos com `session_type: "MIGRATED"` para KYC e KYB. Elas não enviam e-mails ao usuário final, não redirecionam os usuários para o fluxo hospedado e não executam novamente a verificação original. Os registros importados aparecem nas listas de sessões, nos perfis de entidades, nas visualizações de transações e em `GET /v3/session/{session_id}/decision/`, quando aplicável.## Qual importação usar| Objetivo | Caminho de importação | O que é criado | Ideal para |
| - | - | - | - |
| Recriar sessões históricas de KYC | `POST /v3/session/imports/` com `import_type=user_verification` | `Session`, dados de Verificação de identidade, imagens opcionais de documento/selfie, vídeos de documento e de prova de vida, tags, metadados | Migrar candidatos com verificações concluídas da Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo ou de outro provedor de KYC |
| Recriar sessões históricas de KYB | `POST /v3/session/imports/` com `import_type=business_verification` | `BusinessSession`, dados da empresa no registro, administradores, beneficiários finais, tags, metadados | Migrar verificações de empresas concluídas de fornecedores de KYB, provedores de registro de empresas ou ferramentas internas de KYB |
| Recriar registros históricos de monitoramento de transações | `POST /v3/session/imports/` com `import_type=transactions` | `Transaction`, partes titular/contraparte, resultados do provedor, dados da Travel Rule, snapshot da rede, metadados | Migrar o histórico de motor de regras, KYT, triagem de carteiras ou monitoramento de transações em moeda fiduciária |
| Importar regras de status personalizadas do fluxo | `POST /v3/session/imports/` com `import_type=status_rules` | `VerificationSettings.feature_status_rules` | Migrar a lógica de políticas de outro provedor ou de uma planilha para o mecanismo de fluxos da Didit |
| Criar Usuários sem sessões históricas | `POST /v3/users/create/` ou importação CSV pelo Console | Linhas de perfil `VendorUser` | Carregar sua lista de usuários antes de iniciar novas verificações na Didit |
| Vincular rostos de perfil confiáveis aos usuários | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` | Evidência de rosto de perfil indexada para detecção de duplicatas e busca facial | Migrar imagens de rosto de perfil de outro provedor de KYC sem recriar sessões completas |
| Incluir rostos em lista de bloqueio ou de permissão | `POST /v3/lists/{list_uuid}/entries/face-upload/` ou `POST /v3/lists/{list_uuid}/entries/` com `reference_session_id` | Entrada de rosto na lista e embedding biométrico | Migrar rostos conhecidos de fraude ou rostos confiáveis da lista de permissão, ou incluir na lista de bloqueio um rosto de uma sessão existente da Didit |
| Criar Empresas sem sessões históricas de KYB | `POST /v3/businesses/create/` ou importação CSV pelo Console | Linhas de perfil `VendorBusiness` | Carregar uma lista de empresas clientes antes de executar o KYB |> [!NOTE]
>
> Se você só precisa de um perfil de usuário ou de empresa para verificações futuras, não importe uma sessão de verificação histórica. Use as APIs de entidades de Usuário ou de Empresa. Se você precisa que a decisão, os campos do documento, os avisos ou as evidências do provedor anterior apareçam como histórico de conformidade na Didit, use `POST /v3/session/imports/`.## O que pode ser migrado de cada fornecedor?O Didit aceita um arquivo CSV ou NDJSON canônico, então você pode migrar de qualquer fornecedor depois de exportar e transformar os dados. O contrato de importação é sempre o esquema canônico do Didit.| Tipo de fornecedor | Origens comuns | Geralmente migrável | Observações |
| - | - | - | - |
| Fornecedores de KYC | Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, HyperVerge, AU10TIX, Mitek, Ondato | ID do candidato, ID de usuário no fornecedor, status da decisão, campos do documento, imagens do documento, imagem de selfie/prova de vida, motivos de recusa, tags, metadados brutos do fornecedor | Use `import_type=user_verification`. Se o fornecedor não conseguir exportar imagens, importe os campos estruturados e deixe as URLs das imagens vazias. |
| Fornecedores de KYB | Fornecedores de dados de registro de empresas, Sumsub KYB, Trulioo KYB, exportações de registro no estilo Creditsafe, ferramentas internas de KYB | Nome da empresa, número de registro, país, status no registro, administradores, beneficiários finais, nível de risco, payload bruto do registro | Use `import_type=business_verification`. Administradores e UBOs são enviados como arrays JSON. |
| Fornecedores de monitoramento de transações / KYT | Sumsub Transaction Monitoring, exportações de KYT no estilo Chainalysis, Crystal, Merkle Science, Sardine, Unit21, Alloy, motores de regras internos | ID da transação, valor, moeda, direção, titular/contraparte, regras acionadas, resultados do fornecedor, status da Travel Rule, snapshot do grafo da rede | Use `import_type=transactions`. Transações importadas são registros históricos; por padrão, elas não passam por uma nova análise. |
| Planilhas de fluxos e políticas | Exportações de políticas de conformidade, tabelas de regras de fornecedores, planilhas internas de risco | Regras de status por recurso, como "se o país emissor for X, definir Verificação de identidade como Em revisão" | Use `import_type=status_rules`. As regras são validadas em relação ao catálogo de campos do fluxo de trabalho do Didit antes de serem salvas. |
| Bases de usuários/perfis | CRM, banco de dados de clientes, exportação de usuários do fornecedor, data warehouse | `vendor_data`, nome de exibição, metadados, tags, imagens faciais confiáveis | Use as APIs de usuários e o upload de rostos do perfil. Isso não é o mesmo que uma sessão de verificação concluída. |
| Dados de listas de bloqueio / listas de permissão | Listas de fraude de fornecedores, planilhas internas de operações antifraude, listas de chargeback, listas internas relacionadas a sanções | E-mails, telefones, documentos, carteiras, IPs, impressões digitais de dispositivos, rostos, países, usuários, empresas | Use as APIs de listas. Para imagens faciais, use o endpoint dedicado de upload de rostos para que o Didit possa extrair o embedding biométrico. |## Fluxo de migração1) Decida se você vai importar histórico, perfis, rostos, listas, transações ou regras.
2) Exporte você mesmo os dados do fornecedor antigo. Não envie chaves de API do fornecedor antigo ao Didit.
3) Transforme a exportação do fornecedor no modelo canônico CSV ou NDJSON correspondente do Didit.
4) Em migrações grandes, prefira NDJSON e divida os dados em arquivos que possam ser reenviados de forma independente.
5) Crie o job de importação e consulte o progresso.
6) Obtenha os erros por linha, corrija apenas as linhas com falha e tente importá-las novamente. Todos os jobs de importação são idempotentes com base no seu ID externo natural.## Criar um job de importaçãoCrie um job de importação com uma única requisição 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"
```Use CSV em migrações menores baseadas em planilhas e NDJSON em migrações grandes. Com 100k linhas ou mais, o NDJSON é mais fácil de transmitir, dividir, validar e tentar novamente.Em importações de transações, omita `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 da requisição| Campo | Obrigatório | Descrição |
| - | - | - |
| `import_type` | Não, o padrão é `user_verification` | Um entre `user_verification`, `business_verification`, `status_rules`, `transactions`. |
| `workflow_id` | Sim, exceto para `transactions` | UUID do workflow ao qual os registros importados são vinculados. `user_verification` e `status_rules` exigem um workflow de Verificação de usuários; `business_verification` exige um workflow de Verificação de empresas. |
| `file` | `file` ou `source_file_url` | O arquivo CSV ou NDJSON canônico, enviado diretamente na requisição. |
| `source_file_url` | `file` ou `source_file_url` | URL HTTPS de onde o Didit baixa o arquivo. URLs de redes privadas são rejeitadas. |
| `source_format` | Não | `csv` ou `ndjson`. Inferido pela extensão do arquivo quando omitido. |### Como os registros são rastreados e deduplicadosNão existe um campo na requisição para a origem dos dados: toda importação usa o esquema canônico do Didit. Cada registro importado armazena `metadata.imported_from = "generic"` para fins de rastreabilidade.Importações `user_verification` e `business_verification` deduplicam as linhas pelo `external_id` dentro da aplicação, então tentar novamente com o mesmo arquivo não cria duplicatas. Já as importações `transactions` deduplicam pelo `transaction_id`.## Importar fotos de documentos, vídeos e evidências de selfiePara `import_type=user_verification`, você pode importar as fotos originais dos documentos, os vídeos de captura do documento/prova de vida e a imagem da selfie do provedor anterior.Use estas colunas canônicas:| Evidência | Coluna preferencial | Alternativa para importações pequenas | Armazenado na Didit como |
| - | - | - | - |
| Imagem da frente do documento | `document_front_url` | `document_front_base64` | Imagem frontal do OCR da Verificação de identidade |
| Imagem do verso do documento | `document_back_url` | `document_back_base64` | Imagem do verso do OCR da Verificação de identidade |
| Imagem de selfie / prova de vida | `selfie_url` | `selfie_base64` | Imagem de referência de rosto/prova de vida |
| Vídeo da frente do documento | `document_front_video_url` | Somente URL | Vídeo frontal do OCR da Verificação de identidade |
| Vídeo do verso do documento | `document_back_video_url` | Somente URL | Vídeo do verso do OCR da Verificação de identidade |
| Vídeo de prova de vida | `liveness_video_url` | Somente URL | Vídeo de captura de rosto/prova de vida |Para migrações grandes, use **URLs HTTPS**. A Didit baixa cada arquivo, valida se a URL é segura, armazena uma cópia de propriedade da Didit e a vincula à sessão importada. As imagens são comprimidas; os vídeos são armazenados como estão. Base64 inline é aceito para imagens em importações pequenas, mas **os vídeos devem sempre ser fornecidos como URL**: o base64 aumentaria cada vídeo em \~33% e logo ultrapassaria o limite de importação por arquivo.Exemplo de linha NDJSON com URLs de mídia hospedadas pelo provedor:```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\"}"
}
```Regras importantes para mídia:- As URLs devem usar `https`.
- As URLs não podem resolver para IPs privados, localhost, faixas link-local ou hosts internos de metadados.
- As imagens aceitam uma coluna de URL ou sua alternativa `*_base64`; o base64 tem precedência quando ambos estão definidos. Os vídeos são somente por URL: não existe coluna `*_video_base64`.
- Os vídeos devem estar em `mp4`, `webm` ou `mov`, e cada vídeo pode ter no máximo **10 MB**. Arquivos maiores ou que não sejam vídeo são rejeitados como erros de linha.
- A Didit aplica timeouts de conexão/leitura, tamanho máximo de arquivo e não tenta novamente indefinidamente.
- Falhas no download de mídia são armazenadas como erros de linha, para que o restante da importação possa continuar.
- Se você não tiver mídia do provedor, deixe essas colunas vazias. A Didit ainda importa a decisão estruturada e os campos do documento.
- As imagens e os vídeos importados são evidências para revisão histórica. Por padrão, a Didit não executa novamente OCR, prova de vida ou análise de fraude documental na mídia histórica importada.
Prompt de importação de verificação de usuários
Copiar o prompt para a área de transferência
\
\`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.`
\
Colar em
Prompt de importação de verificação de empresas
Copiar o prompt para a área de transferência
\
\`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.`
\
Colar em
Prompt de importação com regras de status personalizadas
Copiar o prompt para a área de transferência
\
\`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.`
\
Colar em
Prompt de importação de transações
Copiar o prompt para a área de transferência
\
\`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.`
\
Colar em
## Consultar o progresso```bash theme={null}
curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \
-H "x-api-key: YOUR_API_KEY"
```A resposta inclui `status`, `import_type`, `total_rows`, `processed_rows`, `created_count`, `updated_count`, `skipped_count`, `failed_count` e `checkpoint_row`.## Baixe os erros por linha```bash theme={null}
curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \
-H "x-api-key: YOUR_API_KEY"
```Cada erro inclui `row_number`, `external_id`, `error` e `raw_row`, para que você possa corrigir apenas as linhas com falha e tentar novamente.## Proteção contra abusoOs jobs de importação histórica por meio de `POST /v3/session/imports/` ficam desativados por padrão. A Didit habilita esse recurso por organização após uma análise, porque esses jobs podem processar milhões de linhas e baixar mídia. As importações normais de dados operacionais deste guia (criar usuários, criar empresas, enviar fotos de perfil, enviar listas de bloqueio de rostos ou adicionar entradas a listas) não exigem nenhuma habilitação especial de migração além das permissões normais da chave de API, da disponibilidade do produto e dos limites de requisições desses endpoints.Os jobs de importação histórica também são executados em workers isolados, com limites de tamanho de arquivo, limites de linhas, URLs de mídia somente HTTPS, bloqueio de URLs de redes privadas, limites de jobs ativos por aplicação e captura de erros por linha.## Status padronizados| Resultado no provedor | Status na Didit |
| - | - |
| Aprovado / Verde / Verificado | `Approved` |
| Recusado / Vermelho / Rejeitado | `Declined` |
| Revisão manual / Pendente / Revisão necessária | `In Review` |
| Incompleto / Iniciado / Linha histórica desconhecida | `Expired` |## IdempotênciaA Didit usa `external_id` como chave de idempotência da importação nas importações de Verificação de usuários e de Verificação de empresas, com escopo por aplicação. As importações de transações usam `transaction_id` por aplicação. Ao tentar importar novamente o mesmo arquivo, as linhas já importadas são ignoradas e as linhas ainda não processadas são criadas.## Importar usuários, rostos de perfil e listas de bloqueioUse os seguintes endpoints quando você não estiver recriando uma sessão de verificação concluída:### Importar perfis de usuárioCrie usuários com [`POST /v3/users/create/`](https://docs.didit.me/pt-br/management-api/users/create) ou pela importação CSV do Business Console em [Importar e exportar usuários](https://docs.didit.me/pt-br/entities/users/import-export.md). Isso cria ou atualiza apenas o perfil `VendorUser`. Não cria sessão de verificação, decisão de KYC, relatório do documento, aviso nem histórico de webhooks.Use esta opção quando quiser que a Didit saiba que o cliente existe antes de verificações futuras, ou quando precisar preencher retroativamente campos no estilo de um CRM, como `display_name`, tags ou metadados.### Enviar rostos de perfil confiáveisDepois que um usuário existir, envie um rosto de perfil confiável com [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/pt-br/management-api/users/upload-face). Isso vincula evidências biométricas ao perfil do usuário e as indexa para detecção de duplicados e busca facial.Isso **não** adiciona o rosto a uma lista de bloqueio. É útil quando você tem uma imagem de perfil confiável de um provedor de KYC anterior e quer que as verificações futuras da Didit façam a comparação com ela.### Importar listas de bloqueio e listas de permissão de rostosPara bloquear ou permitir um rosto diretamente, use [`POST /v3/lists/{list_uuid}/entries/face-upload/`](https://docs.didit.me/pt-br/management-api/lists/upload-face) com uma lista do tipo rosto. A Didit extrai o embedding biométrico e armazena uma entrada na lista.Use esta opção para imagens de fraudadores conhecidos, rostos confiáveis de listas de permissão ou migrações de listas de fraude de provedores. Se o rosto vier de uma sessão existente da Didit, prefira [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/pt-br/management-api/lists/create-entry) com `reference_session_id`; a Didit extrai o rosto correto da sessão e vincula a entrada à origem.### Importar listas de usuários, empresas, documentos, carteiras, e-mails, telefones, IPs ou dispositivosUse [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/pt-br/management-api/lists/create-entry) para valores de lista que não sejam rostos. Este é o caminho certo para listas de bloqueio de provedores, listas de permissão, listas de chargeback, endereços de carteira, IPs sabidamente arriscados, impressões digitais de dispositivos, números de documentos, e-mails, telefones, usuários ou empresas.## Próximos passos> [card] [Importar usuários](https://docs.didit.me/pt-br/entities/users/import-export.md)
>
> Carregue perfis de usuário e vincule rostos de perfil confiáveis.> [card] [Importar empresas](https://docs.didit.me/pt-br/entities/businesses/import-export.md)
>
> Carregue perfis de empresa antes de executar o KYB.> [card] [Enviar rosto de perfil](https://docs.didit.me/pt-br/management-api/users/upload-face.md)
>
> Vincule imagens de rosto confiáveis aos usuários importados.> [card] [Enviar rosto para lista](https://docs.didit.me/pt-br/management-api/lists/upload-face.md)
>
> Adicione rostos a listas de bloqueio ou listas de permissão.> [card] [Criar entrada de lista](https://docs.didit.me/pt-br/management-api/lists/create-entry.md)
>
> Importe telefones, e-mails, carteiras, documentos, IPs, dispositivos, usuários ou empresas para listas.> [card] [Limites de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md)
>
> Projete loops de migração e novas tentativas de forma segura.
## OpenAPI
````yaml pt-br/openapi-25.json POST /v3/session/imports/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/imports/:
post:
tags:
- Sessions
summary: Criar um job de importação de verificações
description: >-
Cria um job de importação assíncrono para sessões históricas de
Verificação de usuários, sessões de Verificação de empresas, registros
de monitoramento de transações ou regras de status personalizado de
fluxos de verificação (workflow). Defina `source=provider` para migrar
de outro provedor: a Didit lê Sumsub, Onfido, Persona e ComplyCube com
sua chave somente leitura, lê os registros de Veriff, iDenfy e MetaMap
pelos IDs que você envia em `file` e importa um arquivo de exportação no
formato da Didit para os demais provedores. Os IDs de registro recebem
um namespace por provedor (`sumsub:`), de modo que uma nova execução
ignora tudo o que já está na Didit. As importações ficam desativadas por
padrão e precisam ser ativadas pela Didit para cada organização.
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: >-
O que importar: sessões históricas de Verificação de
usuários, sessões históricas de Verificação de empresas,
regras de status personalizados do fluxo de verificação
(workflow) ou registros históricos de monitoramento de
transações.
workflow_id:
type: string
format: uuid
description: >-
UUID do fluxo de verificação (workflow) ao qual as sessões
ou regras de status importadas devem ser vinculadas.
Obrigatório para user_verification, business_verification e
status_rules. Omita para transactions.
source_format:
type: string
enum:
- csv
- ndjson
description: >-
Opcional. Inferido a partir da extensão do arquivo enviado
quando omitido.
file:
type: string
format: binary
description: >-
Arquivo CSV ou NDJSON canônico. Use NDJSON para importações
grandes. Tamanho máximo de upload de 25 MB (use
`source_file_url` para arquivos maiores). Mutuamente
exclusivo com `source_file_url`.
source_file_url:
type: string
format: uri
description: >-
Alternativa ao upload de arquivo. Deve ser uma URL HTTPS que
resolva para um endereço público (redes privadas/loopback
são rejeitadas). Mutuamente exclusivo com `file`.
source:
type: string
enum:
- file
- provider
description: >-
`provider` torna esta importação uma migração de outro
provedor de verificação de identidade. Omita para uma
importação de arquivo.
provider:
type: string
enum:
- sumsub
- jumio
- veriff
- onfido
- persona
- metamap
- socure
- idnow
- shufti
- idenfy
- ondato
- trulioo
- au10tix
- complycube
- other
description: >-
Origem da migração, obtida de `GET
/v3/session/imports/providers/`. Obrigatório quando `source`
é `provider`.
credentials:
type: object
additionalProperties:
type: string
description: >-
A chave somente leitura do provedor, com os nomes de campo
listados em `credential_fields`. Criptografada em repouso,
nunca retornada e apagada quando a importação termina.
Envie-a como uma string JSON no multipart.
options:
type: object
properties:
region:
type: string
description: >-
A região do provedor, uma das suas `regions` (Onfido:
`eu`, `us`, `ca`).
status_mapping:
type: object
additionalProperties:
type: string
enum:
- Approved
- Declined
- In Review
- Expired
- Not Finished
- Abandoned
description: >-
Alterações no mapeamento de status padrão do provedor:
status de origem para status da Didit. `Not Finished` e
`Abandoned` são ignorados e contabilizados, nunca
importados.
dry_run:
type: boolean
default: false
description: >-
Conta o que a migração importaria (por status, já existente
na Didit, mesma pessoa, não concluído) e não grava nada. O
job termina em `READY`. Inicie-o com `POST
/v3/session/imports/{importId}/start/`.
face_templates:
type: boolean
default: false
description: >-
Gera templates faciais a partir das selfies importadas e os
busca entre os rostos e a lista de bloqueio da aplicação. As
correspondências são apenas sinalizadas para revisão. Requer
`lawful_basis_confirmed`.
lawful_basis_confirmed:
type: boolean
default: false
description: >-
Confirma que você tem uma base legal para compartilhar essas
selfies com a Didit, na qualidade de operadora.
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: >-
O que importar: sessões históricas de Verificação de
usuários, sessões históricas de Verificação de empresas,
regras de status personalizados do fluxo de verificação
(workflow) ou registros históricos de monitoramento de
transações.
workflow_id:
type: string
format: uuid
description: >-
UUID do fluxo de verificação (workflow) ao qual as sessões
ou regras de status importadas devem ser vinculadas.
Obrigatório para user_verification, business_verification e
status_rules. Omita para transactions.
source_format:
type: string
enum:
- csv
- ndjson
description: >-
Opcional. Inferido a partir da extensão de arquivo da URL
quando omitido.
source_file_url:
type: string
format: uri
description: >-
Alternativa ao upload de arquivo. Deve ser uma URL HTTPS que
resolva para um endereço público (redes privadas/loopback
são rejeitadas). Mutuamente exclusivo com `file`.
source:
type: string
enum:
- file
- provider
description: >-
`provider` torna esta importação uma migração de outro
provedor de verificação de identidade. Omita para uma
importação de arquivo.
provider:
type: string
enum:
- sumsub
- jumio
- veriff
- onfido
- persona
- metamap
- socure
- idnow
- shufti
- idenfy
- ondato
- trulioo
- au10tix
- complycube
- other
description: >-
Origem da migração, obtida de `GET
/v3/session/imports/providers/`. Obrigatório quando `source`
é `provider`.
credentials:
type: object
additionalProperties:
type: string
description: >-
A chave somente leitura do provedor, com os nomes de campo
listados em `credential_fields`. Criptografada em repouso,
nunca retornada e apagada quando a importação termina.
Envie-a como uma string JSON no multipart.
options:
type: object
properties:
region:
type: string
description: >-
A região do provedor, uma das suas `regions` (Onfido:
`eu`, `us`, `ca`).
status_mapping:
type: object
additionalProperties:
type: string
enum:
- Approved
- Declined
- In Review
- Expired
- Not Finished
- Abandoned
description: >-
Alterações no mapeamento de status padrão do provedor:
status de origem para status da Didit. `Not Finished` e
`Abandoned` são ignorados e contabilizados, nunca
importados.
dry_run:
type: boolean
default: false
description: >-
Conta o que a migração importaria (por status, já existente
na Didit, mesma pessoa, não concluído) e não grava nada. O
job termina em `READY`. Inicie-o com `POST
/v3/session/imports/{importId}/start/`.
face_templates:
type: boolean
default: false
description: >-
Gera templates faciais a partir das selfies importadas e os
busca entre os rostos e a lista de bloqueio da aplicação. As
correspondências são apenas sinalizadas para revisão. Requer
`lawful_basis_confirmed`.
lawful_basis_confirmed:
type: boolean
default: false
description: >-
Confirma que você tem uma base legal para compartilhar essas
selfies com a Didit, na qualidade de operadora.
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: >-
Tarefa de importação aceita. Consulte o `uuid` retornado até que
`status` seja `COMPLETED` ou `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: >-
Fluxo, tipo de arquivo, tamanho de arquivo, URL de origem ou
combinação de seletores inválidos. Uma migração cuja chave o
provedor recusa responde com `code` (`invalid_credentials`,
`missing_permission`, `wrong_region`, `provider_unavailable`,
`rate_limited`, `ids_required`, `record_not_found`),
`missing_permissions` e `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: >-
Importações não habilitadas, aplicação de sandbox ou chave de API
ausente (uma chave incorreta, revogada ou expirada retorna `401`).
As importações de verificações vêm desabilitadas por padrão e
precisam ser habilitadas pela Didit para cada organização.
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: >-
A aplicação já tem um job de importação ativo
(PENDING/PROCESSING/PAUSED). Aguarde a conclusão antes de iniciar
outro.
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 da tarefa de importação. Use este valor para consultar o
progresso e obter os erros das linhas.
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: >-
O estado da tarefa conforme exibido no console; `errors` é uma
tarefa concluída com linhas rejeitadas.
source:
type: string
enum:
- file
- api
- provider
provider:
type: string
description: Origem da migração; vazio para importação por arquivo ou API.
provider_options:
type: object
credential_hint:
type: string
description: >-
Os primeiros caracteres da chave que a migração guarda. A chave em
si nunca é retornada.
credentials_expires_at:
type: string
format: date-time
nullable: true
resumes_at:
type: string
format: date-time
nullable: true
description: >-
Quando um job pausado pelo limite de requisições do provedor é
retomado automaticamente.
status_mapping:
type: object
additionalProperties:
type: string
is_dry_run:
type: boolean
dry_run_summary:
type: object
description: >-
O que uma simulação (dry run) encontrou: `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: >-
Chave de API da sua aplicação, em Developers -> API keys no Business
Console. A chave principal tem acesso total. Uma chave nomeada pode ter
escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada
a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a
uma data de validade. 401 significa que a chave está errada, revogada ou
expirada; 403 significa que nenhuma chave foi enviada, que a chave não
tem acesso a este recurso ou ação, ou que a requisição veio de um
endereço fora da sua lista de IPs; 404 em uma rota de sessão significa
que a sessão está fora dos fluxos ou status da chave. Uma chave sem
acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave
sem permissão de escrita em sessões recebe links e tokens de sessão como
null. Consulte https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.