Skip to main content
POST
/
v3
/
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 workflow_id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form provider=generic \
  --form import_type=user_verification \
  --form file='@example-file' \
  --form 'source_file_url=<string>'
{
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "source_filename": "<string>",
  "total_rows": 123,
  "processed_rows": 123,
  "created_count": 123,
  "updated_count": 123,
  "skipped_count": 123,
  "failed_count": 123,
  "checkpoint_row": 123,
  "total_media_bytes": 123,
  "last_error": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}
Use the verification import API to migrate historical User Verification records, Business Verification records, transaction monitoring records, or workflow custom status rules into Didit. You prepare a canonical CSV or NDJSON file, create an import job, and poll the job until it finishes. Verification imports create historical sessions with session_type: "MIGRATED". 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 sessions appear in session lists, entity profiles, and GET /v3/session/{session_id}/decision/.

​
Create an import job

curl -X POST https://verification.didit.me/v3/session/imports/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "import_type=user_verification" \
  -F "provider=sumsub" \
  -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 "provider=generic" \
  -F "file=@didit-transactions.ndjson"

​
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

Verification imports are disabled by default. Didit enables them per application after review because large imports can process millions of rows and download media. Imports 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 outcomeDidit status
Approved / Green / VerifiedApproved
Declined / Red / RejectedDeclined
Manual review / Pending / Review neededIn Review
Incomplete / Init / Unknown historical rowExpired

​
Idempotency

Didit uses provider + external_id as the import idempotency key for one application. Retrying the same file skips rows that were already imported and creates rows that were not processed yet.

Authorizations

​
x-api-key
string
header
required

Body

multipart/form-data
​
workflow_id
string<uuid>
required

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

​
provider
enum<string>
default:generic
Available options:
generic,
sumsub,
metamap
​
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
​
source_format
enum<string>

Optional. Inferred from the uploaded file extension when omitted.

Available options:
csv,
ndjson
​
file
file

Canonical CSV or NDJSON file. Use NDJSON for large imports.

​
source_file_url
string<uri>

Alternative to file upload. Must be an HTTPS URL and must not resolve to a private network address.

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
​
provider
enum<string>
required
Available options:
generic,
sumsub,
metamap
​
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