Know the device.
Know the IP. On every session.

# Didit Device & IP Analysis — integrate in 5 minutes

You are integrating Didit's Device & IP Analysis (VPN, datacenter, Tor, geolocation,
device intelligence) module into <my_stack>. Follow these steps exactly.
Every URL, header, and enum value below is canonical — do not paraphrase
or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Integration path — Workflow Builder (session-only)

Device & IP Analysis runs inside a Didit session — there is no standalone
POST /v3/ip-analysis/ endpoint. The IP and device fingerprint are
captured automatically when the user lands on the hosted UI, so you
do not collect or send them yourself.

1. Create a workflow that includes the IP_ANALYSIS feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array including
         { feature: "IP_ANALYSIS" }   (UPPERCASE — strict enum)
   Combine with ID_VERIFICATION, LIVENESS, FACE_MATCH in the same
   workflow for the full $0.33 Know Your Customer (KYC) bundle (Device & IP Analysis is included).

2. (Optional) Configure per-warning actions in the console for the
   application — pick Decline, Review, or Approve for each of
   PRIVATE_NETWORK_DETECTED, COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP,
   EXPECTED_IP_ADDRESS_MISMATCH, DUPLICATED_IP_ADDRESS,
   DUPLICATED_DEVICE_FINGERPRINT.

3. (Optional) Pin an expected IP per session: pass expected_ip_address
   in the POST /v3/session/ body if you already know where the user
   should be (for example: their last known login IP).

4. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id),
         optional expected_ip_address.
   Response: session_url — redirect the user to it.

5. Listen for webhook callbacks (see "Webhooks" below).

## 3. Webhooks
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 4. Reading the report
The session decision payload contains an ip_analysis object with:
- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- ip_address, ip_country, ip_country_code, ip_state, ip_city
- latitude, longitude, time_zone, time_zone_offset
- isp, organization
- is_vpn_or_tor (boolean) — fires the PRIVATE_NETWORK_DETECTED warning
- is_data_center (boolean) — hosting/datacenter origin
- device_brand, device_model, browser_family, os_family, platform
  (mobile or desktop)
- locations_info with ip, id_document, poa_document blocks — each
  carries a location object plus distance_from_* fields in kilometres
- matches array — cross-session matches on ip_address or
  device_fingerprint when the same value appears under a different
  vendor_data
- warnings array — each entry has risk, log_type,
  short_description, long_description

Auto-decline risks (always enforced by Didit, not configurable):
- IP_ADDRESS_IN_BLOCKLIST
- DEVICE_FINGERPRINT_IN_BLOCKLIST

Configurable risks (action per workflow — Decline, Review, or Approve):
- PRIVATE_NETWORK_DETECTED (VPN, proxy, Tor)
- COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP
- EXPECTED_IP_ADDRESS_MISMATCH
- DUPLICATED_IP_ADDRESS (default: Approve)
- DUPLICATED_DEVICE_FINGERPRINT (default: Approve)

## 5. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: IP_ANALYSIS, ID_VERIFICATION, LIVENESS, FACE_MATCH, AML.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- Always pass vendor_data (your own user id). Without it, every session
  is treated as a unique user and DUPLICATED_IP_ADDRESS /
  DUPLICATED_DEVICE_FINGERPRINT noise rises sharply.

## 6. Pricing reference (public)
- IP_ANALYSIS as a session add-on: $0.03 per check
- Bundled in a full KYC workflow (ID_VERIFICATION + LIVENESS +
  FACE_MATCH + IP_ANALYSIS): $0.33 per session — Device & IP Analysis is
  already included at the bundle price.
- 500 free checks every month, forever, on every account.

## 7. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test IPs: deterministic synthetic responses returned in sandbox (Approved
  by default; trigger PRIVATE_NETWORK_DETECTED by using a known VPN exit IP
  on the verification device).
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/ip-analysis/overview