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

# Device & IP Analysis

> Detect duplicate devices, fraud rings, VPNs, proxies, Tor, location mismatches, and suspicious device fingerprints during KYC verification.

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>;
};

export const VideoEmbed = ({src, title = "Video", type = "iframe"}) => <div className={type === "iframe" ? "didit-video-embed" : "didit-video-embed didit-video-native"}>
    {type === "iframe" ? <iframe src={src} title={title} style={{
  width: "100%",
  height: "100%",
  border: 0,
  borderRadius: "12px"
}} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen /> : <video controls autoPlay muted loop playsInline src={src} title={title} style={{
  width: "100%",
  height: "auto",
  display: "block",
  borderRadius: "12px"
}} />}
  </div>;

Didit's Device & IP Analysis combines device fingerprinting, duplicate-device recovery, IP intelligence, and geolocation checks in the verification flow. It helps detect when the same physical device is trying to access multiple accounts, even when the user changes sessions, clears browser storage, opens an incognito window, or rotates network information.

<AgentPromptAccordion
  title="Device & IP Analysis Integration Prompt"
  prompt={`# Goal
Integrate Didit Device & IP Analysis (device fingerprinting + IP intelligence + geolocation) into your app.

# Delivery mode
IP Analysis is **session-only**. The Web/Mobile SDK collects the device fingerprint and IP during the hosted flow — there is no standalone /v3/ip-analysis/ endpoint. It runs automatically on every session and does not require a workflow feature toggle for the basic signal set.

# Steps
1. (Optional) In the Business Console enable strict-mode rules for IP / device — e.g. "decline on VPN", "review on duplicate device", "decline on country mismatch with document".
2. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3. Open session.url for the user — the SDK collects fingerprint + IP in-band.
4. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\`\`\`bash
curl -X POST 'https://verification.didit.me/v3/session/' \\
-H 'x-api-key: YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-123",
"callback": "https://yourapp.com/post-kyc"
}'
\`\`\`

# Decision surface
The result lands under \`ip_analyses[]\` on the decision payload (one entry per IP/device collection point in the workflow). Each entry carries the resolved geo, ASN, VPN / proxy / Tor flags, device fingerprint id, duplicate-device matches, and the warnings array.

# Status enum (per ip_analyses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

# Warnings (LogWarningChoices.LOCATION)
Heads-up: IP Analysis emits warnings under the **LOCATION** bucket (not "IP_ANALYSIS"). Risk codes include:
VPN_DETECTED, PROXY_DETECTED, TOR_DETECTED, DATACENTER_IP, HIGH_RISK_COUNTRY, LOCATION_MISMATCH_WITH_DOCUMENT, DUPLICATED_DEVICE, POSSIBLE_DUPLICATED_DEVICE, IMPOSSIBLE_TRAVEL, DEVICE_FINGERPRINT_BLOCKLISTED.
Full catalogue: /core-technology/ip-analysis/warnings-ip-analysis.

# Failure modes to handle
- ip_analyses[] empty — the user blocked the SDK fingerprinting script (privacy extensions, content blockers). Decide whether to fail-closed or fall back to soft signals.
- VPN_DETECTED / PROXY_DETECTED / TOR_DETECTED — treat per your fraud policy (decline, manual review, additional liveness step).
- DUPLICATED_DEVICE — same device previously enrolled under a different vendor_data; merge accounts or block per policy.
- LOCATION_MISMATCH_WITH_DOCUMENT — the IP country does not match the document's issuing country; route to review.

# See also
- Canonical schema: /reference/data-models#ip-analysis
- Per-feature report: /core-technology/ip-analysis/report-ip-analysis
- Risk catalogue: /core-technology/ip-analysis/warnings-ip-analysis
- Full integration playbook: /integration/integration-prompt`}
/>

The feature is designed for fraud-prevention decisions where false positives are expensive. Exact duplicate-device matches use stable persistent identifiers. Recovered-device matches use the v2 fingerprint signal vector and high-confidence gates, so Didit can surface suspicious reuse without merging unrelated users too aggressively.

<VideoEmbed src="https://www.youtube.com/embed/h0i9Q0-izcw?start=923&rel=0&playsinline=1" title="Device & IP Analysis" />

<Frame>
  <img src="https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis.png?fit=max&auto=format&n=z6T2GHM4Zh-iSj-K&q=85&s=a2fbbbdd3d6fed3d759e54f362bf4762" alt="Didit Device and IP Analysis overview showing geolocation, device fingerprinting, device intelligence and VPN detection" width="1889" height="886" data-path="images/ip-analysis.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis-how-it-works.jpg?fit=max&auto=format&n=z6T2GHM4Zh-iSj-K&q=85&s=3519ad9ad50091a00db5e09d5197fdfe" alt="Didit Device and IP Analysis architecture diagram cross-checking IP, device fingerprint and declared location" width="4558" height="2021" data-path="images/ip-analysis-how-it-works.jpg" />
</Frame>

## How it works

Device & IP Analysis runs automatically during the verification session and links the device, network, and identity context into one risk surface.

<Steps>
  <Step title="Device fingerprint capture" icon="fingerprint">
    The verification client sends a privacy-safe v2 fingerprint payload with web or mobile device signals:

    | Data Point               | Description                                                                                                      |
    | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
    | **Persistent device ID** | First-party identifier used for exact same-device detection when storage persists.                               |
    | **Composite hash**       | Stable grouped signal hash used for deterministic duplicate checks with collision safeguards.                    |
    | **Signal vector**        | Device and browser/app attributes vectorized for high-confidence recovery.                                       |
    | **Platform context**     | Browser, OS, app, hardware, WebGL/canvas, media, locale, timezone, and mobile integrity signals where available. |
  </Step>

  <Step title="IP and connection analysis" icon="wifi">
    Didit enriches the observed connection data with network risk information:

    * IP geolocation by country, region, city, and coordinates
    * VPN, proxy, Tor, data center, and private-network detection
    * Expected IP checks when you provide an allowed IP for the session
    * IP blocklist checks configured in your application
  </Step>

  <Step title="Duplicate and recovery matching" icon="code-compare">
    Didit checks whether the current session matches previous sessions from another `vendor_data`:

    | Check                             | Purpose                                                                           |
    | --------------------------------- | --------------------------------------------------------------------------------- |
    | **Duplicated IP**                 | Detects the same IP address across different users.                               |
    | **Duplicated device fingerprint** | Detects exact reuse of the same persistent device identity.                       |
    | **Recovered device**              | Detects a high-confidence v2 fingerprint recovery when the persistent ID changed. |
    | **Collision guard**               | Suppresses low-quality pooled hashes instead of merging unrelated devices.        |
  </Step>

  <Step title="Location cross-checks" icon="map-location-dot">
    Device & IP Analysis compares location context against trusted reference points:

    * Document country and address coordinates
    * Expected session IP address
    * IP country and city
    * Distance and direction between address and IP location
  </Step>

  <Step title="Action and reporting" icon="paper-plane">
    You can configure each risk category independently and consume the result in every Didit output:

    | Channel               | Description                                                                                                               |
    | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
    | **Workflow actions**  | Approve, review, or decline for VPN/proxy, location mismatch, duplicate IP, exact duplicate device, and recovered device. |
    | **Dashboard**         | Review warnings, matching sessions, device information, and network details in the Didit console.                         |
    | **Webhooks and APIs** | Receive structured warnings and matches in decision payloads.                                                             |
    | **Reports**           | Export Device & IP Analysis details in verification PDFs.                                                                 |
  </Step>
</Steps>

## Matching Model

Device & IP Analysis separates exact matches from recovered matches so you can tune fraud response safely:

| Layer                   | What it detects                                                                                  | False-positive posture                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Exact persistent ID** | The same first-party device identity appears in another user's session.                          | Strongest signal. Used for `DUPLICATED_DEVICE_FINGERPRINT`.                                                |
| **Composite hash**      | The same deterministic device hash appears in another user's session.                            | Guarded by collision detection so common WebView/browser pools are suppressed.                             |
| **v2 recovered device** | The persistent ID changed, but rich device signals match a previous device with high confidence. | Conservative. Used for `DEVICE_RECOVERED_HIGH_CONFIDENCE` only after hard gates pass.                      |
| **IP reuse**            | The same IP address appears across users.                                                        | Contextual. Useful for fraud rings, but shared offices, households, and mobile carriers can be legitimate. |

Recovered-device matching uses a dedicated vector recovery index. If that index is not available, Didit continues exact duplicate checks and does not emit fuzzy recovery candidates.

## Fraud Patterns Detected

Device & IP Analysis helps identify and reduce:

* Multi-accounting and duplicate-account creation
* KYC bypass attempts using the same device across different identities
* Fraud rings coordinating many accounts from shared devices or infrastructure
* Bonus abuse, referral abuse, promo abuse, and free-trial abuse
* Synthetic identity onboarding from repeated devices
* Money mule onboarding patterns
* Account takeover risk from unfamiliar or high-risk devices
* Credential stuffing and automated signup attempts
* Card testing, chargeback abuse, and refund abuse supported by repeated device/network patterns
* VPN, proxy, Tor, data center, and residential proxy evasion
* Device tampering, emulator usage, jailbreak/root risk, and app cloning where mobile signals are available
* Location spoofing and mismatches between document, IP, timezone, carrier, and device context
* Bot-driven verification attempts using headless browsers or scripted clients

## Key Capabilities

#### Device fingerprinting and recovery

* **Exact duplicate-device detection**: Detect the same device identity across sessions from different `vendor_data` values.
* **High-confidence recovery**: Recover likely same-device relationships when storage changes or incognito/private browsing changes the persistent ID.
* **Collision protection**: Avoid merging unrelated users when a device hash looks too common across many distinct persistent IDs.
* **Mobile and web coverage**: Use web browser signals and native mobile signals, including integrity-related fields when available.

#### IP and network intelligence

* **VPN and proxy detection**: Identify masked or anonymized connections.
* **Tor and data-center detection**: Flag high-risk infrastructure.
* **IP blocklists**: Automatically decline when the IP appears in your application blocklist.
* **Expected IP enforcement**: Compare the observed IP to an expected IP supplied during session creation.

#### Geolocation and document comparison

* **Country mismatch detection**: Compare document country and IP country.
* **Address distance checks**: Compare document address coordinates and IP geolocation.
* **Session match context**: Return matching sessions with device and location details for staff review.

## Configure Actions

Use workflow settings to choose the action for each risk. Conservative customers often set `recovered_device_action` to `REVIEW` first, inspect recovered-device warnings for a few weeks, and only move to `DECLINE` after confirming the local false-positive profile.

| Setting                    | Recommended starting action | Why                                                                                                       |
| -------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------- |
| `vpn_detection_action`     | `REVIEW` or `DECLINE`       | Depends on whether VPN usage is allowed in your product.                                                  |
| `ip_mismatch_action`       | `REVIEW`                    | Location mismatch is strong context but can be legitimate.                                                |
| `duplicated_ip_action`     | `REVIEW`                    | Shared networks can create false positives.                                                               |
| `duplicated_device_action` | `REVIEW` or `DECLINE`       | Exact same-device reuse across users is a strong fraud signal.                                            |
| `recovered_device_action`  | `REVIEW`                    | High-confidence recovery is intentionally conservative, but should be monitored before automatic decline. |

See [Device & IP Analysis warnings](/core-technology/ip-analysis/warnings-ip-analysis) for all risk tags and [Workflow Feature Configs](/management-api/workflows/feature-configs#device--ip-analysis) for API fields.