Import Shared Session

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

import requests

response = requests.post(
    "https://verification.didit.me/v3/session/import-shared/",
    headers={
        'x-api-key': 'YOUR_API_KEY',
        "Content-Type": "application/json",
    },
    json={
        "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "trust_review": False,
        "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab",
        "vendor_data": "user-1",
    },
)
response.raise_for_status()
imported = response.json()

const response = await fetch(
  'https://verification.didit.me/v3/session/import-shared/',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      share_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
      trust_review: false,
      workflow_id: '9f9b1234-aaaa-bbbb-cccc-1234567890ab',
      vendor_data: 'user-1',
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const imported = await response.json();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/session/import-shared/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'share_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'trust_review' => false,
    'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',
    'vendor_data' => 'user-1'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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/import-shared/"

	payload := strings.NewReader("{\n  \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"trust_review\": false,\n  \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n  \"vendor_data\": \"user-1\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	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/import-shared/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"trust_review\": false,\n  \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n  \"vendor_data\": \"user-1\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/session/import-shared/")

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["Content-Type"] = 'application/json'
request.body = "{\n  \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"trust_review\": false,\n  \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n  \"vendor_data\": \"user-1\"\n}"

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

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "shared_from_session": "99999999-8888-7777-6666-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"
}

POST

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

import requests

response = requests.post(
    "https://verification.didit.me/v3/session/import-shared/",
    headers={
        'x-api-key': 'YOUR_API_KEY',
        "Content-Type": "application/json",
    },
    json={
        "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "trust_review": False,
        "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab",
        "vendor_data": "user-1",
    },
)
response.raise_for_status()
imported = response.json()

const response = await fetch(
  'https://verification.didit.me/v3/session/import-shared/',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      share_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
      trust_review: false,
      workflow_id: '9f9b1234-aaaa-bbbb-cccc-1234567890ab',
      vendor_data: 'user-1',
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const imported = await response.json();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/session/import-shared/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'share_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'trust_review' => false,
    'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',
    'vendor_data' => 'user-1'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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/import-shared/"

	payload := strings.NewReader("{\n  \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"trust_review\": false,\n  \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n  \"vendor_data\": \"user-1\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	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/import-shared/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"trust_review\": false,\n  \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n  \"vendor_data\": \"user-1\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/session/import-shared/")

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["Content-Type"] = 'application/json'
request.body = "{\n  \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"trust_review\": false,\n  \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n  \"vendor_data\": \"user-1\"\n}"

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

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "shared_from_session": "99999999-8888-7777-6666-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"
}

KYC and KYB support

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

Import a User Verification (KYC) session
Import a Business Verification (KYB) session

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",
  "shared_from_session": "original-uuid",
  "status": "In Review",
  "vendor_data": "partner-user-42",
  "id_verifications": [...],
  "liveness_checks": [...],
  "...": "..."
}

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-kyb-workflow-id",
    "vendor_data": "partner-biz-acme",
    "trust_review": true
  }'

Response (201 Created):

{
  "session_id": "new-uuid",
  "session_kind": "business",
  "shared_from_session": "original-uuid",
  "status": "Approved",
  "vendor_data": "partner-biz-acme",
  "registry_checks": [...],
  "key_people_checks": [...],
  "document_verifications": [...],
  "...": "..."
}

`trust_review` parameter

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

Errors

Status	Reason
`401`	Share token invalid or expired.
`403`	Token not intended for your application, or session has already been imported.
`404`	Original session no longer exists.
`404`	`workflow_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

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. The body is the V3 decision payload for both kinds, discriminated by session_kind: "user" (KYC) with list-based feature blocks such as id_verifications, liveness_checks, aml_screenings; "business" (KYB) with blocks like registry_checks and key_people_checks. Both include shared_from_session — the session_id of the original session in the source application. With trust_review: false the cloned session's status is forced to In Review.

⌘I

Overview

User and Business Verifications

Lists

Workflows

Questionnaires

Users

Businesses

Cases

Case Blueprints

Report Templates

Regulatory Reports

Transactions

Travel Rule

Session Operations

Customization

Webhook

Billing

Management API Overview

Auth API (Programmatic)

Identity & Documents

Database Validation

Biometrics & Face

Compliance & Risk

Email Verification

Phone Verification

KYC and KYB support

What gets created

Examples

`trust_review` parameter

Errors

Idempotency

Authorizations

Body

Response

​KYC and KYB support

​What gets created

​Examples

​trust_review parameter

​Errors

​Idempotency

​Related

Authorizations

Body

Response

KYC and KYB support

What gets created

Examples

`trust_review` parameter

Errors

Idempotency

Related