Skip to main content
POST
/
v3
/
session
/
import-shared
/
curl
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": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "trust_review": false,
    "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab",
    "vendor_data": "user-1"
  }'
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_url": null,
  "status": "In Review",
  "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab",
  "vendor_data": "user-1",
  "created_at": "2026-05-17T08:42:11Z",
  "expires_at": "2026-05-24T08:42:11Z"
}

​
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

JWT share token issued by POST /v3/session/{sessionId}/share/.

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
trust_review
boolean
required

If true, the cloned session keeps the source's final status. If false, it is forced into In Review.

Example:

false

​
workflow_id
string<uuid>
required

UUID of a workflow in the calling application. Cross-application IDs are rejected with 404.

Example:

"9f9b1234-aaaa-bbbb-cccc-1234567890ab"

​
vendor_data
string | null

Optional override for the cloned session's vendor_data.

Example:

"user-1"

Response

Session cloned. For user (KYC) sessions the body is the V2 decision payload (session_id, session_number, status, workflow_id, per-feature blocks such as id_verification, liveness, aml, plus created_at/expires_at — no session_kind field). For business (KYB) sessions it is the V3 KYB decision payload, which includes session_kind: "business" and blocks like registry_checks and aml_screenings. With trust_review: false the cloned session's status is forced to In Review.