Skip to main content
Every transaction that includes a device IP address is enriched server-side in real time before rules evaluate it. Enrichment adds country, city, VPN/Tor/data-center flags, ASN, and carrier — all available as rule conditions.

​
When enrichment runs

Inline during transaction creation:
  1. You submit POST /v3/transactions/ with applicant.device.ip (or any party’s device IP).
  2. Didit looks up the IP in an in-memory cache (24-hour TTL).
  3. If not cached, checks the shared IP-enrichment table (~30-day freshness).
  4. If stale or missing, resolves the IP through Didit’s enrichment pipeline with multi-provider failover.
  5. Enriched fields are written back to the transaction record and made available to rules.
Enrichment is inline — it completes before rules run — but non-blocking on failure. If enrichment cannot complete, the transaction still goes through; the IP simply appears without enrichment data.

​
Enriched fields

FieldDescription
ip_countryCountry name
ip_country_codeISO 3166-1 alpha-3
ip_stateSubdivision (state, region)
ip_cityCity name
latitude, longitudeGeographic coordinates
ispInternet service provider name
organizationRegistering organization name
is_vpn_or_torBoolean — the IP is a known VPN or Tor exit
is_data_centerBoolean — the IP belongs to a hosting/data-center range
time_zoneIANA time zone (e.g. America/New_York)
time_zone_offsetOffset from UTC
asn_numberAutonomous System Number
asn_organizationASN’s registered organization
connection_typemobile, broadband, dialup, corporate, …
carrierMobile carrier (for mobile IPs)
proxy_typeVPN, TOR, PUBLIC_PROXY, or null

​
Using enriched fields in rules

Any of the enriched fields can be a rule condition. Common patterns: High-risk jurisdiction by IP 
condition: applicant.ip_country_code IN ['IRN', 'PRK', 'SYR']
action: add_score(35), add_tags(['high_risk_ip_country'])
VPN / Tor usage 
condition: applicant.is_vpn_or_tor == true
action: change_status('IN_REVIEW'), add_tags(['anonymization'])
Data center / non-residential origin 
condition: applicant.is_data_center == true AND amount > 10000
action: add_score(30)
IP country ≠ KYC country 
condition: applicant.ip_country_code != applicant.country_code
action: add_score(15), add_tags(['geo_mismatch'])

​
Cache layers

LayerTTLPurpose
In-memory cache24 hoursSub-millisecond lookup for hot IPs
Shared IP-enrichment table~30 daysShared across instances; cheaper than re-resolving
Enrichment pipelinen/aFresh data when nothing else has it
Hits on the first two layers don’t cost you anything extra. Fresh resolutions may be metered — see your billing console.

​
Failure behavior

  • Transaction creation never fails because enrichment failed.
  • Missing enrichment fields simply don’t match any rule conditions that reference them.
  • Alerts about stuck enrichment are surfaced to your ops team via internal monitoring; no customer-facing impact.

​
Validity filtering

Non-routable IPs are skipped before enrichment:
  • Private (10/8, 172.16/12, 192.168/16)
  • Loopback (127/8)
  • Link-local (169.254/16)
  • Multicast, unspecified
These save provider quota and avoid nonsense enrichment data.

​
Inspecting enrichment for a transaction

Via API. The transaction response includes an ip_enrichment block: 
"applicant": {
  "vendor_data": "user-42",
  "device": { "ip": "203.0.113.5" },
  "ip_enrichment": {
    "ip_country": "United States",
    "ip_country_code": "USA",
    "ip_state": "California",
    "ip_city": "San Francisco",
    "is_vpn_or_tor": false,
    "is_data_center": false,
    "asn_number": 15169,
    "asn_organization": "Google LLC",
    "proxy_type": null
  }
}
In the console. The transaction detail page shows IP enrichment in the IP & Device tab with a geo-map pin.

​
Privacy considerations

  • Raw IPs are stored with the transaction.
  • Enrichment data lives on a shared IP-keyed table — not per user.
  • Right-to-be-forgotten deletion removes IPs from the transaction; the shared cache entry remains (it’s not personally identifying).

​
Next steps

Rules

Use enriched fields in conditions.

Rule library

Preset IP-based rules.

Response schema

Where IP enrichment appears.