Skip to main content
POST
/
v3
/
session
/
import-shared
Import a shared User Verification (KYC) or Business Verification (KYB) session
curl --request POST \
  --url https://verification.didit.me/v3/session/import-shared/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "share_token": "<string>",
  "trust_review": true,
  "workflow_id": "<string>",
  "vendor_data": "<string>"
}
'
"{\n  \"session_id\": \"11111111-2222-3333-4444-555555555555\",\n  \"session_number\": 43762,\n  \"session_url\": \"https://verify.didit.me/session/11111111-2222-3333-4444-555555555555\",\n  \"status\": \"In Review\",\n  \"workflow_id\": \"11111111-2222-3333-4444-555555555555\",\n  \"features\": [\n    \"ID_VERIFICATION\",\n    \"LIVENESS\",\n    \"FACE_MATCH\",\n  ],\n  \"vendor_data\": \"11111111-1111-1111-1111-111111111111\",\n  \"metadata\": {\n    \"user_type\": \"premium\",\n    \"account_id\": \"ABC123\"\n  },\n  \"expected_details\": {\n    \"first_name\": \"Carmen\",\n    \"last_name\": \"Española Española\"\n  },\n  \"contact_details\": {\n    \"email\": \"carmen@example.com\",\n    \"email_lang\": \"es\"\n  },\n  \"callback\": \"https://verify.didit.me/\",\n  \"id_verification\": {\n    \"status\": \"Approved\",\n    \"document_type\": \"Identity Card\",\n    \"document_number\": \"CAA000000\",\n    \"personal_number\": \"99999999R\",\n    \"portrait_image\": \"https://example.com/portrait.jpg\",\n    \"front_image\": \"https://example.com/front.jpg\",\n    \"front_video\": \"https://example.com/front.mp4\",\n    \"back_image\": \"https://example.com/back.jpg\",\n    \"back_video\": \"https://example.com/back.mp4\",\n    \"full_front_image\": \"https://example.com/full_front.jpg\",\n    \"full_back_image\": \"https://example.com/full_back.jpg\",\n    \"date_of_birth\": \"1980-01-01\",\n    \"age\": 45,\n    \"expiration_date\": \"2031-06-02\",\n    \"date_of_issue\": \"2021-06-02\",\n    \"issuing_state\": \"ESP\",\n    \"issuing_state_name\": \"Spain\",\n    \"first_name\": \"Carmen\",\n    \"last_name\": \"Española Española\",\n    \"full_name\": \"Carmen Española Española\",\n    \"gender\": \"F\",\n    \"address\": \"Avda de Madrid 34, Madrid, Madrid\",\n    \"formatted_address\": \"Avda de Madrid 34, Madrid, Madrid 28822, Spain\",\n    \"place_of_birth\": \"Madrid\",\n    \"marital_status\": \"Single\",\n    \"nationality\": \"ESP\",\n    \"extra_fields\": {\n      \"dl_categories\": [],\n      \"blood_group\": null\n    },\n    \"parsed_address\": {\n      \"id\": \"7c6280a2-fb6a-4258-93d5-2ac987cbc6ba\",\n      \"address_type\": \"Avda\",\n      \"city\": \"Madrid\",\n      \"label\": \"Spain ID Card Address\",\n      \"region\": \"Madrid\",\n      \"street_1\": \"Avda de Madrid 34\",\n      \"street_2\": null,\n      \"postal_code\": \"28822\",\n      \"raw_results\": {\n        \"geometry\": {\n          \"location\": {\n            \"lat\": 37.4222804,\n            \"lng\": -122.0843428\n          },\n          \"location_type\": \"ROOFTOP\",\n          \"viewport\": {\n            \"northeast\": {\n              \"lat\": 37.4237349802915,\n              \"lng\": -122.083183169709\n            },\n            \"southwest\": {\n              \"lat\": 37.4210370197085,\n              \"lng\": -122.085881130292\n            }\n          }\n        }\n      }\n    },\n    \"extra_files\": [\n      \"https://example.com/extra_id_verification.jpg\"\n    ],\n    \"warnings\": [\n      {\n        \"risk\": \"QR_NOT_DETECTED\",\n        \"additional_data\": null,\n        \"log_type\": \"information\",\n        \"short_description\": \"QR not detected\",\n        \"long_description\": \"The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.\"\n      }\n    ]\n  },\n  \"nfc\": null,\n  \"liveness\": {\n      \"status\": \"Approved\",\n      \"method\": \"ACTIVE_3D\",\n      \"score\": 89.92,\n      \"reference_image\": \"https://example.com/reference.jpg\",\n      \"video_url\": \"https://example.com/video.mp4\",\n      \"age_estimation\": 24.3,\n      \"warnings\": [\n        {\n          \"risk\": \"LOW_LIVENESS_SCORE\",\n          \"additional_data\": null,\n          \"log_type\": \"information\",\n          \"short_description\": \"Low liveness score\",\n          \"long_description\": \"The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.\"\n        }\n      ]\n    },\n  \"face_match\": {\n      \"status\": \"In Review\",\n      \"score\": 65.43,\n      \"source_image\": \"https://example.com/source-image.jpg\",\n      \"target_image\": \"https://example.com/target-image.jpg\",\n      \"warnings\": [\n        {\n          \"risk\": \"LOW_FACE_MATCH_SIMILARITY\",\n          \"additional_data\": null,\n          \"log_type\": \"warning\",\n          \"short_description\": \"Low face match similarity\",\n          \"long_description\": \"The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.\"\n        }\n      ]\n    },\n  \"phone\": null,\n  \"poa\": null,\n  \"aml\": null,\n  \"ip_analysis\": null,\n  \"reviews\": [\n      {\n        \"user\": \"compliance@example.com\",\n        \"new_status\": \"Declined\",\n        \"comment\": \"Possible match found in AML screening\",\n        \"created_at\": \"2024-07-18T13:29:00.366811Z\"\n      }\n    ],\n  \"created_at\": \"2024-07-24T08:54:25.443172Z\"\n}"

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.

​
Session kind

Didit decodes the share token, reads the embedded session_kind, and clones the corresponding kind of session:
  • session_kind: "user" — clones the user session plus its related identity, face, liveness, face-match, AML, location, POA, phone, email, database-validation, and log rows.
  • session_kind: "business" — clones the business session plus its related registry check, key-people records, documents, AML screenings, phone, email, location, questionnaire, and log rows.
If the token predates the unified sharing rollout and has no session_kind field, Didit defaults to "user" for backward compatibility.

​
What gets created

  • A new session of the same kind in your application with a fresh session_id, session_number, and session_url.
  • The new session’s shared_from_session field points at the original session in the source application.
  • The new session’s status is either the original status (trust_review: true) or IN_REVIEW (trust_review: false).
  • A new entity (User or Business) is auto-created for the vendor_data if one doesn’t exist.

​
Examples

curl -X POST https://verification.didit.me/v3/session/import-shared/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "share_token": "eyJhbGciOiJIUzI1NiJ9...",
    "workflow_id": "your-kyc-workflow-id",
    "vendor_data": "partner-user-42",
    "trust_review": false
  }'
Response (201 Created):
{
  "session_id": "new-uuid",
  "session_kind": "user",
  "status": "In Review",
  "vendor_data": "partner-user-42",
  "id_verifications": [...],
  "liveness_checks": [...],
  "...": "..."
}

​
trust_review parameter

ValueEffect
trueThe imported session preserves the original status (e.g. APPROVED). Use when you fully trust the sharing partner’s decision.
falseThe imported session lands in IN_REVIEW so your team can re-review before acting. Safe default for external partners.

​
Errors

StatusReason
401Share token invalid or expired.
403Token not intended for your application, or session has already been imported.
404Original session no longer exists.
404workflow_id not found in your application.

​
Idempotency

Importing the same share_token twice is rejected with 403 — the duplicate-import check runs against both user and business tables depending on session_kind.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
share_token
string
required

The share token to import the session with.

​
trust_review
boolean
required

Whether to trust the review of the session to be imported. If true, the session will be imported as is, otherwise the session will be set to 'In Review' so it can be reviewed by the application.

​
workflow_id
string
required

The workflow ID to import the session with.

​
vendor_data
string

Sets your own user vendor_data for the imported verification session.

Response