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

# User KYC History

> Retrieve every Didit verification session tied to a User entity, inspect feature-level results, trigger re-verification, and export compliance reports.

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="KYC History Prompt"
  prompt={`# Goal — read a user's full KYC history and trigger re-verification

Every KYC session a user has ever run stays permanently linked to the User entity via \`vendor_data\`. The session list endpoint is the entry point; the decision endpoint is the detail view.

## List every session for a user

\`\`\`bash
curl -G https://verification.didit.me/v3/sessions/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
--data-urlencode "vendor_data=user-42" \\
--data-urlencode "page_size=50"
\`\`\`

Response covers every status (approved, declined, in review, abandoned, expired). Paginate with the \`next\` cursor / \`page\` param until empty.

## Inspect a single session decision

\`\`\`bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \\
-H "x-api-key: $DIDIT_API_KEY"
\`\`\`

V3 returns plural arrays — always iterate them:

- \`id_verifications[]\`
- \`liveness_checks[]\`
- \`face_matches[]\`
- \`aml_screenings[]\`
- \`nfc_verifications[]\`
- \`proof_of_address_checks[]\`

Never assume V2 singular fields.

## Trigger re-verification

Annual re-KYC, document expiry, trigger-based re-checks — same pattern: create a new session against the same \`vendor_data\`. The new session attaches to the existing User entity and updates the \`features\` map on completion.

\`\`\`bash
curl -X POST https://verification.didit.me/v3/session/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"workflow_id": "wf_reverification", "vendor_data": "user-42"}'
\`\`\`

## Fast path — fully verified right now?

The User entity carries a \`features\` map summarising the **latest** state of each feature across all sessions:

\`\`\`bash
curl https://verification.didit.me/v3/users/user-42/ \\
-H "x-api-key: $DIDIT_API_KEY"
# data.features = { id_verification: "APPROVED", liveness: "APPROVED", aml: "IN_REVIEW", ... }
\`\`\`

Use \`features\` for "is the user verified right now?" without iterating every session.

## Generate a PDF for any session

\`\`\`bash
curl https://verification.didit.me/v3/session/$SESSION_ID/generate-pdf/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-o session-report.pdf
\`\`\`

## Resubmit vs new session

| Scenario | Use |
|---|---|
| Declined for fixable reason (blurry ID, bad lighting) | Resubmit the existing session (re-deliver \`url\`); the workflow advances through resubmission |
| Annual / trigger-based re-KYC | Create a brand new session via \`POST /v3/session/\` |
| Transaction-rule triggered remediation | The transaction creates a remediation session automatically (\`Awaiting User\` status) |

## Share a session with a partner (Reusable KYC)

\`\`\`bash
# Issue a shareable token
curl -X POST https://verification.didit.me/v3/session/$SESSION_ID/share/ \\
-H "x-api-key: $DIDIT_API_KEY"

# Receiver imports the shared session
curl -X POST https://verification.didit.me/v3/session/import-shared/ \\
-H "x-api-key: $RECEIVER_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"share_token": "..."}'
\`\`\`

## Failure modes

- \`404\` on the user — wrong \`vendor_data\` casing or no sessions yet.
- Empty \`results[]\` — no sessions for this \`vendor_data\` in this application.
- Stale signed image URLs — re-fetch the decision.
- Sharing rejected — receiving application must have Reusable KYC enabled.

## Sources of truth

- /sessions-api/retrieve-session — V3 decision schema
- /reference/data-models — per-feature plural-array contract
- /core-technology/reusable-kyc/overview — share / import pattern
- /entities/users/data-model — features map computation
- /integration/integration-prompt — canonical end-to-end prompt
`}
/>

Every User Verification (KYC) session a user has ever run stays permanently linked to their User entity. You can retrieve the full history, inspect individual session results, trigger re-verification, and export compliance reports.

## Listing all sessions for a user

Filter the Sessions list by `vendor_data`:

```bash theme={null}
curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "vendor_data=user-42" \
  --data-urlencode "page_size=50"
```

Response includes every session (regardless of status) — approved, declined, in review, abandoned, or expired.

## Understanding the feature aggregates

The User entity's `features` map reflects the **latest** status of each feature across all sessions:

```json theme={null}
"features": {
  "id_verification": "APPROVED",
  "liveness": "APPROVED",
  "face_match": "APPROVED",
  "aml": "IN_REVIEW"
}
```

Use this as the fast path to answer "is the user verified right now?". For the historical record — all sessions, all features, all results — list sessions and inspect each decision.

## Inspecting a single session

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/decision/ \
  -H "x-api-key: YOUR_API_KEY"
```

The decision includes:

* Per-feature results (ID, liveness, face match, AML, POA, NFC, etc.)
* Extracted document data and images (signed URLs)
* AML hits with match/risk scores
* Device & IP Analysis and device context
* Reviewer notes and manual actions

See [retrieve session](/sessions-api/retrieve-session) for the full schema.

## Triggering re-verification

When you need a user to re-verify (e.g. annual re-KYC, document expiry, trigger-based re-check):

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_reverification",
    "vendor_data": "user-42"
  }'
```

The new session attaches to the same User entity. On completion, the entity's `features` map updates to reflect the new results.

## Resubmission vs new session

| Scenario                                                                     | Use                                                                                  |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| User's session was declined due to a fixable issue (blurry ID, bad lighting) | [Resubmit](/console/manual-review) — same session, new upload                        |
| Full re-verification or periodic re-KYC                                      | Create a brand new session                                                           |
| Remediation triggered by a transaction rule                                  | The transaction creates a remediation session automatically (`AWAITING_USER` status) |

## Exporting a compliance report

For audits, SARs, or regulator requests, generate a PDF for any session:

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/generate-pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -o session-report.pdf
```

For bulk exports across many sessions, use the console's CSV/PDF export from *Users → \[user] → Verifications* or the app-wide export at *Review & Operations → Export PDF/CSV*.

## Sharing a session with a third party

When you need to share a user's verification with a partner app (e.g. a reusable KYC scenario), use:

* `POST /v3/session/{session_id}/share/` — generate a shareable token.
* `POST /v3/session/import-shared/` — import a shared session on the receiving side.

See [reusable KYC](/core-technology/reusable-kyc/overview) for the full pattern.

## History-driven workflows

Use session history to drive smarter compliance decisions:

* **Skip steps** if the user already has an approved liveness within N days.
* **Require additional checks** if the user's most recent session was declined.
* **Flag** when a user's session count spikes unexpectedly.
* **Monitor** ongoing AML rescans via the [continuous monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) feature.

## Next steps

<CardGroup cols={3}>
  <Card title="Data model" icon="database" href="/entities/users/data-model">
    How the features map and counters are computed.
  </Card>

  <Card title="Retrieve session" icon="file-lines" href="/sessions-api/retrieve-session">
    Full session decision schema.
  </Card>

  <Card title="Reusable KYC" icon="arrows-rotate" href="/core-technology/reusable-kyc/overview">
    Reuse verified data across applications.
  </Card>
</CardGroup>