> ## 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.

# Import Shared Session

> Redeem a share token to clone a KYC or KYB session into the calling application with a fresh `session_id`. Not idempotent — a token redeems once per receiver.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Import Shared Session Prompt"
  prompt={`Import a verification session shared by a partner application (Reusable KYC / KYB).

Endpoint:
POST https://verification.didit.me/v3/session/import-shared/

Authentication:
Use the x-api-key header with the receiving application's Didit API key. Privilege: write:sessions.

Request body:
- share_token (string, required) — JWT minted by the partner via POST /v3/session/{id}/share/. Didit decodes it, reads the embedded session_kind, and clones the matching kind.
- workflow_id (string, UUID, required) — Workflow in YOUR application to attach the imported session to. KYC token → pass a KYC workflow_id. KYB token → pass a KYB workflow_id.
- vendor_data (string, optional) — Your stable identifier for the entity. Auto-creates a User or Business entity if it does not already exist.
- trust_review (boolean, optional, default false) — false → imported session lands in "In Review" so your team can re-review. true → imported session preserves the original status (e.g. "Approved"). Use true only when you fully trust the sharing partner's decision.

curl example:
curl -X POST https://verification.didit.me/v3/session/import-shared/ \\
-H "x-api-key: <RECEIVING_API_KEY>" \\
-H "Content-Type: application/json" \\
-d '{
"share_token": "<JWT_FROM_PARTNER>",
"workflow_id": "<YOUR_WORKFLOW_ID>",
"vendor_data": "partner-user-42",
"trust_review": false
}'

Response (201 Created):
- session_id (UUID) — NEW UUID minted in your application.
- session_kind ("user" | "business") — same as the original.
- session_number — fresh sequence in your application.
- status — original status (if trust_review=true) or "In Review" (if trust_review=false).
- shared_from_session — pointer to the original session in the source application.
- vendor_data, workflow_id — what you sent.
- All cloned feature arrays: KYC tokens clone id_verifications + liveness_checks + face_matches + face + AML + location + POA + phone + email + database_validations + logs; KYB tokens clone registry_checks + key_people_checks + document_verifications + AML + phone + email + location + questionnaire + logs.

Backward compatibility:
Tokens minted before the unified-sharing rollout (no session_kind field) default to "user" when decoded.

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

Failure modes:
- 401 — { "detail": "Invalid or expired share token." } when the JWT is malformed or its exp has passed.
- 403 — { "detail": "..." } when the token's for_application_id does not match the calling application, or when the session has already been imported.
- 404 — { "detail": "Not found." } when the original session no longer exists, or when workflow_id is not found in your application.

When to call:
- Cross-organization Reusable KYC (bank → fintech, marketplace → payment provider, etc.).
- Promoting a verified user from your sandbox application to your production application.
- Group-company sharing across sibling applications.

After import:
- The new session works like any other session — fetch with GET /v3/session/{session_id}/decision/ (see /sessions-api/retrieve-session) and react to status / data webhooks.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`}
/>

## 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

<Tabs>
  <Tab title="Import a User Verification (KYC) session">
    ```bash theme={null}
    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):**

    ```json theme={null}
    {
      "session_id": "new-uuid",
      "session_kind": "user",
      "status": "In Review",
      "vendor_data": "partner-user-42",
      "id_verifications": [...],
      "liveness_checks": [...],
      "...": "..."
    }
    ```
  </Tab>

  <Tab title="Import a Business Verification (KYB) session">
    ```bash theme={null}
    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):**

    ```json theme={null}
    {
      "session_id": "new-uuid",
      "session_kind": "business",
      "status": "Approved",
      "vendor_data": "partner-biz-acme",
      "registry_checks": [...],
      "key_people_checks": [...],
      "document_verifications": [...],
      "...": "..."
    }
    ```
  </Tab>
</Tabs>

## `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`.

## Related

* [Share session](/sessions-api/share-session/share)
* [Reusable KYC guide](/core-technology/reusable-kyc/share-kyc-via-api)
* [Sessions overview](/sessions-api/overview)


## OpenAPI

````yaml POST /v3/session/import-shared/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/session/import-shared/:
    post:
      tags:
        - Sessions
      summary: >-
        Redeem a share token to clone a verification session into your
        application
      description: >-
        Redeem a share token to clone a KYC or KYB session into the calling
        application with a fresh `session_id`. Not idempotent — a token redeems
        once per receiver.
      operationId: post_v3_session_import_shared
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - share_token
                - trust_review
                - workflow_id
              properties:
                share_token:
                  type: string
                  description: >-
                    JWT share token issued by [`POST
                    /v3/session/{sessionId}/share/`](/sessions-api/share-session).
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                trust_review:
                  type: boolean
                  description: >-
                    If `true`, the cloned session keeps the source's final
                    `status`. If `false`, it is forced into `In Review`.
                  example: false
                workflow_id:
                  type: string
                  format: uuid
                  description: >-
                    UUID of a workflow in the calling application.
                    Cross-application IDs are rejected with `404`.
                  example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
                vendor_data:
                  type: string
                  nullable: true
                  description: Optional override for the cloned session's `vendor_data`.
                  example: user-1
            example:
              share_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
              trust_review: false
              workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
              vendor_data: user-1
      responses:
        '201':
          description: >-
            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`.
          content:
            application/json:
              examples:
                User session imported:
                  summary: >-
                    Cloned KYC session (truncated — full V2 decision payload in
                    reality)
                  value:
                    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'
                Business session imported:
                  summary: >-
                    Cloned KYB session (truncated — full V3 KYB decision payload
                    in reality)
                  value:
                    session_id: 22222222-3333-4444-5555-666666666666
                    session_kind: business
                    session_number: 982
                    session_url: null
                    status: Approved
                    workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab
                    vendor_data: company-1
        '400':
          description: >-
            Validation error (token invalid, expired, wrong target, or
            references a session that no longer exists).
          content:
            application/json:
              examples:
                Invalid Share Token:
                  summary: Invalid JWT
                  value:
                    share_token:
                      - Invalid share token.
                Expired Share Token:
                  summary: Token past `exp`
                  value:
                    share_token:
                      - Share token has expired.
                Wrong audience:
                  summary: Token not bound to this application
                  value:
                    share_token:
                      - This token is not valid for this application.
                Original missing:
                  summary: Source session was deleted
                  value:
                    share_token:
                      - Original session does not exist.
        '403':
          description: >-
            Missing/invalid API key (this endpoint returns `403`, never `401`,
            for authentication failures), or this source session has already
            been imported into the calling application (one redeem per
            receiver).
          content:
            application/json:
              examples:
                Forbidden:
                  summary: Forbidden
                  value:
                    detail: You do not have permission to perform this action.
                Already imported:
                  summary: Source already imported once
                  value:
                    detail: >-
                      This session has already been shared with your
                      application.
        '404':
          description: '`workflow_id` does not belong to the calling application.'
          content:
            application/json:
              examples:
                Workflow not found:
                  summary: Workflow unknown
                  value:
                    detail: Workflow does not exist for this application.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            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"
              }'
        - lang: python
          label: Python
          source: |-
            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()
        - lang: javascript
          label: JavaScript
          source: |-
            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();
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````