Create a verification import job

curl --request POST \
  --url https://verification.didit.me/v3/session/imports/ \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form import_type=user_verification \
  --form workflow_id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form file='@example-file' \
  --form 'source_file_url=<string>'

import requests

url = "https://verification.didit.me/v3/session/imports/"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "import_type": "user_verification",
    "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "source_file_url": "<string>"
}
headers = {"x-api-key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('import_type', 'user_verification');
form.append('workflow_id', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('file', '<string>');
form.append('source_file_url', '<string>');

const options = {method: 'POST', headers: {'x-api-key': '<api-key>'}};

options.body = form;

fetch('https://verification.didit.me/v3/session/imports/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/session/imports/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/session/imports/"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/session/imports/")
  .header("x-api-key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/session/imports/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "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
}

User and Business Verifications

Import Data from Another Provider

Create an asynchronous import job for historical User Verification sessions, Business Verification sessions, transaction monitoring records, or workflow custom status rules. Use this to migrate from providers such as Sumsub, MetaMap, Veriff, Onfido, Persona, Trulioo, Jumio, Incode, iDenfy, or any other provider after transforming the export into Didit’s canonical CSV/NDJSON format. Imports are disabled by default and must be enabled per organization by Didit.

POST

session

imports

Create a verification import job

curl --request POST \
  --url https://verification.didit.me/v3/session/imports/ \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form import_type=user_verification \
  --form workflow_id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form file='@example-file' \
  --form 'source_file_url=<string>'

import requests

url = "https://verification.didit.me/v3/session/imports/"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "import_type": "user_verification",
    "workflow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "source_file_url": "<string>"
}
headers = {"x-api-key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('import_type', 'user_verification');
form.append('workflow_id', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('file', '<string>');
form.append('source_file_url', '<string>');

const options = {method: 'POST', headers: {'x-api-key': '<api-key>'}};

options.body = form;

fetch('https://verification.didit.me/v3/session/imports/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/session/imports/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/session/imports/"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/session/imports/")
  .header("x-api-key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/session/imports/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"import_type\"\r\n\r\nuser_verification\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workflow_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source_file_url\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "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
}

Use this guide to choose the right import path when you move data from another provider into Didit. There are two different jobs customers often call “import”:

Import historical verification work — recreate completed KYC, KYB, transaction monitoring, or workflow-rule records so Didit shows the old provider history. Use POST /v3/session/imports/.
Import operating data — create Users, Businesses, profile faces, blocklist entries, or allowlist entries so Didit can use them in future checks. Use the entity, face, and list APIs.

Verification imports create historical records with session_type: "MIGRATED" for KYC and KYB. They do not send end-user emails, do not redirect users into the hosted flow, and do not re-run the original verification. The imported records appear in session lists, entity profiles, transaction views, and GET /v3/session/{session_id}/decision/ where applicable.

Which import should you use?

Goal	Use this import path	What it creates	Best for
Recreate historical KYC sessions	`POST /v3/session/imports/` with `import_type=user_verification`	`Session`, ID Verification data, optional document/selfie images, document and liveness videos, tags, metadata	Moving completed applicants from Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, or another KYC provider
Recreate historical KYB sessions	`POST /v3/session/imports/` with `import_type=business_verification`	`BusinessSession`, registry company data, officers, beneficial owners, tags, metadata	Moving completed business checks from KYB vendors, company registry providers, or internal KYB tooling
Recreate historical transaction monitoring records	`POST /v3/session/imports/` with `import_type=transactions`	`Transaction`, subject/counterparty parties, provider results, Travel Rule data, network snapshot, metadata	Moving rule-engine, KYT, wallet-screening, or fiat transaction monitoring history
Import custom workflow status rules	`POST /v3/session/imports/` with `import_type=status_rules`	`VerificationSettings.feature_status_rules`	Moving policy logic from another provider or spreadsheet into Didit’s workflow engine
Create Users without historical sessions	`POST /v3/users/create/` or Console CSV import	`VendorUser` profile rows	Loading your user roster before starting new Didit checks
Attach trusted profile faces to users	`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`	Profile face evidence indexed for duplicate detection and face search	Migrating profile face images from another KYC provider without recreating full sessions
Blocklist or allowlist faces	`POST /v3/lists/{list_uuid}/entries/face-upload/` or `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id`	Face list entry and biometric embedding	Migrating known fraud faces, trusted allowlist faces, or blocklisting a face from an existing Didit session
Create Businesses without historical KYB sessions	`POST /v3/businesses/create/` or Console CSV import	`VendorBusiness` profile rows	Loading a business customer roster before running KYB

If you only need a user or business profile for future checks, do not import a historical verification session. Use the User or Business entity APIs. If you need the old provider’s decision, document fields, warnings, or evidence to appear as compliance history in Didit, use POST /v3/session/imports/.

What can migrate from each provider?

Didit accepts a canonical CSV or NDJSON file, so you can migrate from any provider once you export and transform the data. The import contract is always Didit’s canonical schema.

Provider family	Typical sources	Usually migratable	Notes
KYC providers	Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, HyperVerge, AU10TIX, Mitek, Ondato	Applicant id, vendor user id, decision status, document fields, document images, selfie/liveness image, rejection labels, tags, raw provider metadata	Use `import_type=user_verification`. If the provider cannot export images, import the structured fields and keep image URLs empty.
KYB providers	Company registry providers, Sumsub KYB, Trulioo KYB, Creditsafe-style registry exports, internal KYB tools	Company name, registration number, country, registry status, officers, beneficial owners, risk level, raw registry payload	Use `import_type=business_verification`. Officers and UBOs are passed as JSON arrays.
Transaction monitoring / KYT providers	Sumsub Transaction Monitoring, Chainalysis-style KYT exports, Crystal, Merkle Science, Sardine, Unit21, Alloy, internal rule engines	Transaction id, amount, currency, direction, subject/counterparty, rule hits, provider results, Travel Rule status, network graph snapshot	Use `import_type=transactions`. Imported transactions are historical records; they are not re-screened by default.
Workflow and policy spreadsheets	Compliance policy exports, provider rule tables, internal risk spreadsheets	Per-feature status rules such as “if issuing country is X, set ID Verification to In Review”	Use `import_type=status_rules`. Rules are validated against Didit’s workflow field catalog before they are saved.
User/profile stores	CRM, customer DB, provider user export, data warehouse	`vendor_data`, display name, metadata, tags, trusted face images	Use User APIs and profile face upload. This is not the same as a completed verification session.
Blocklist / allowlist data	Provider fraud lists, internal fraud ops sheets, chargeback lists, sanctions-adjacent internal lists	Emails, phones, documents, wallets, IPs, device fingerprints, faces, countries, users, businesses	Use Lists APIs. For face images, use the dedicated face upload endpoint so Didit can extract the biometric embedding.

Migration workflow

Decide whether you are importing history, profiles, faces, lists, transactions, or rules.
Export the data from the old provider yourself. Do not send old-provider API keys to Didit.
Transform the provider export into the matching Didit canonical CSV or NDJSON template.
For large migrations, prefer NDJSON and split into files you can retry independently.
Create the import job and poll progress.
Fetch row errors, fix only failed rows, and retry them. All import jobs are idempotent on their natural external id.

Create an import job

Create an import job with a single multipart request:

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 for smaller spreadsheet-driven migrations and NDJSON for large migrations. For 100k+ rows, NDJSON is easier to stream, split, validate, and retry. For transaction imports, omit workflow_id:

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"

Request fields

Field	Required	Description
`import_type`	No, defaults to `user_verification`	One of `user_verification`, `business_verification`, `status_rules`, `transactions`.
`workflow_id`	Yes, except for `transactions`	UUID of the workflow the imported records attach to. `user_verification` and `status_rules` need a User Verification workflow; `business_verification` needs a Business Verification workflow.
`file`	Either `file` or `source_file_url`	The canonical CSV or NDJSON file, uploaded inline.
`source_file_url`	Either `file` or `source_file_url`	HTTPS URL Didit downloads the file from. Private-network URLs are rejected.
`source_format`	No	`csv` or `ndjson`. Inferred from the file extension when omitted.

How records are tracked and deduplicated

There is no request field for the data source — every import uses Didit’s canonical schema. Each imported record stores metadata.imported_from = "generic" for traceability. user_verification and business_verification imports deduplicate rows on external_id within the application, so retrying the same file won’t create duplicates. transactions imports deduplicate on transaction_id instead.

Import document photos, videos, and selfie evidence

For import_type=user_verification, you can import the original document photos, document/liveness capture videos, and selfie image from the previous provider. Use these canonical columns:

Evidence	Preferred column	Small-import fallback	Stored in Didit as
Document front image	`document_front_url`	`document_front_base64`	ID Verification OCR front image
Document back image	`document_back_url`	`document_back_base64`	ID Verification OCR back image
Selfie / liveness image	`selfie_url`	`selfie_base64`	Face/Liveness reference image
Document front video	`document_front_video_url`	URL only	ID Verification OCR front video
Document back video	`document_back_video_url`	URL only	ID Verification OCR back video
Liveness video	`liveness_video_url`	URL only	Face/Liveness capture video

For large migrations, use HTTPS URLs. Didit downloads each file, validates the URL is safe, stores a Didit-owned copy, and links it to the imported session. Images are compressed; videos are stored as-is. Inline base64 is accepted for images on small imports, but videos must always be supplied as a URL — base64 would inflate each video by ~33% and quickly exceed the per-file import limit. Example NDJSON row with provider-hosted media URLs:

{
  "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\"}"
}

Important media rules:

URLs must use https.
URLs must not resolve to private IPs, localhost, link-local ranges, or internal metadata hosts.
Images accept either a URL column or its *_base64 fallback; base64 takes precedence when both are set. Videos are URL only — there is no *_video_base64 column.
Videos must be mp4, webm, or mov, and each video may be at most 10 MB. Larger or non-video files are rejected as row errors.
Didit enforces connect/read timeouts, maximum file size, and no infinite retries.
Media download failures are stored as row errors so the rest of the import can continue.
If you do not have media from the provider, leave these columns empty. Didit still imports the structured decision and document fields.
Imported images and videos are evidence for historical review. Didit does not re-run OCR, liveness, or document-fraud analysis on imported historical media by default.

Poll progress

curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \
  -H "x-api-key: YOUR_API_KEY"

The response includes status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count, and checkpoint_row.

Download row errors

curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \
  -H "x-api-key: YOUR_API_KEY"

Each error includes row_number, external_id, error, and raw_row, so you can fix only the failed rows and retry.

Abuse protection

Historical import jobs through POST /v3/session/imports/ are disabled by default. Didit enables this capability per organization after review because these jobs can process millions of rows and download media. The normal operating-data imports in this guide — creating Users, creating Businesses, uploading profile faces, uploading face blocklists, or adding list entries — do not require special migration enablement beyond the normal API key permissions, product availability, and rate limits for those endpoints. Historical import jobs also run on isolated workers with file size limits, row budgets, HTTPS-only media URLs, private-network URL blocking, per-application active-job limits, and per-row error capture.

Canonical statuses

Provider outcome	Didit status
Approved / Green / Verified	`Approved`
Declined / Red / Rejected	`Declined`
Manual review / Pending / Review needed	`In Review`
Incomplete / Init / Unknown historical row	`Expired`

Idempotency

Didit uses external_id as the import idempotency key for User Verification and Business Verification imports, scoped per application. Transaction imports use transaction_id per application. Retrying the same file skips rows that were already imported and creates rows that were not processed yet.

Import users, profile faces, and blocklists

Use these paths when you are not recreating a completed verification session:

Import user profiles

Create users with POST /v3/users/create/ or the Business Console CSV import in Import and Export Users. This creates or updates the VendorUser profile only. It does not create a verification session, KYC decision, document report, warning, or webhook history. Use this when you want Didit to know the customer exists before future checks, or when you need to backfill CRM-like fields such as display_name, tags, or metadata.

Upload trusted profile faces

After a User exists, upload a trusted profile face with

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

. This attaches biometric evidence to the User profile and indexes it for duplicate detection and face search. This does not blocklist the face. It is useful when you have a trusted profile image from a previous KYC provider and want future Didit checks to compare against it.

Import face blocklists and allowlists

To block or allow a face directly, use POST /v3/lists/{list_uuid}/entries/face-upload/ with a face-type list. Didit extracts the biometric embedding and stores a list entry. Use this for known fraudster images, trusted allowlist faces, or provider fraud-list migrations. If the face comes from an existing Didit session, prefer POST /v3/lists/{list_uuid}/entries/ with reference_session_id; Didit extracts the right face from the session and links the entry back to the source.

Import user, business, document, wallet, email, phone, IP, or device lists

Use POST /v3/lists/{list_uuid}/entries/ for non-face list values. This is the right path for provider blocklists, allowlists, chargeback lists, wallet addresses, known risky IPs, device fingerprints, document numbers, emails, phones, users, or businesses.

Next steps

Import users

Load User profiles and attach trusted profile faces.

Import businesses

Load Business profiles before running KYB.

Upload profile face

Attach trusted face images to imported Users.

Upload face to list

Add faces to blocklists or allowlists.

Create list entry

Import phones, emails, wallets, documents, IPs, devices, users, or businesses into lists.

Rate limits

Design safe migration loops and retries.

Authorizations

x-api-key

string

header

required

Body

import_type

enum<string>

default:user_verification

What to import: historical User Verification sessions, historical Business Verification sessions, workflow custom status rules, or historical transaction monitoring records.

Available options:

user_verification,

business_verification,

status_rules,

transactions

workflow_id

string<uuid>

Workflow UUID that imported sessions or status rules should be attached to. Required for user_verification, business_verification, and status_rules. Omit for transactions.

source_format

enum<string>

Optional. Inferred from the uploaded file extension when omitted.

Available options:

csv,

ndjson

file

Canonical CSV or NDJSON file. Use NDJSON for large imports. Maximum upload size 25 MB (use source_file_url for bigger files). Mutually exclusive with source_file_url.

source_file_url

string<uri>

Alternative to file upload. Must be an HTTPS URL resolving to a public address (private/loopback networks are rejected). Mutually exclusive with file.

Response

Import job accepted. Poll the returned uuid until status is COMPLETED or FAILED.

uuid

string<uuid>

required

Import job id. Use this value to poll progress and fetch row errors.

status

enum<string>

required

Available options:

PENDING,

PROCESSING,

COMPLETED,

FAILED,

PAUSED,

CANCELLED

import_type

enum<string>

required

Available options:

user_verification,

business_verification,

status_rules,

transactions

source_format

enum<string>

required

Available options:

csv,

ndjson

source_filename

string

required

total_rows

integer<int64>

required

processed_rows

integer<int64>

required

created_count

integer<int64>

required

updated_count

integer<int64>

required

skipped_count

integer<int64>

required

failed_count

integer<int64>

required

checkpoint_row

integer<int64>

total_media_bytes

integer<int64>

last_error

string | null

created_at

string<date-time>

updated_at

string<date-time>

started_at

string<date-time> | null

completed_at

string<date-time> | null

Create Session Retrieve Session

⌘I

​Which import should you use?

​What can migrate from each provider?

​Migration workflow

​Create an import job

​Request fields

​How records are tracked and deduplicated

​Import document photos, videos, and selfie evidence

​Poll progress

​Download row errors

​Abuse protection

​Canonical statuses

​Idempotency

​Import users, profile faces, and blocklists

​Import user profiles

​Upload trusted profile faces

​Import face blocklists and allowlists

​Import user, business, document, wallet, email, phone, IP, or device lists

​Next steps

Import users

Import businesses

Upload profile face

Upload face to list

Create list entry

Rate limits

Authorizations

Body

Response

Which import should you use?

What can migrate from each provider?

Migration workflow

Create an import job

Request fields

How records are tracked and deduplicated

Import document photos, videos, and selfie evidence

Poll progress

Download row errors

Abuse protection

Canonical statuses

Idempotency

Import users, profile faces, and blocklists

Import user profiles

Upload trusted profile faces

Import face blocklists and allowlists

Import user, business, document, wallet, email, phone, IP, or device lists

Next steps