IP Enrichment

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:

You submit POST /v3/transactions/ with subject.device_context.network_context.ip_address (or any party’s device IP).
Didit looks up the IP in an in-memory cache (24-hour TTL).
If not cached, checks the shared IP-enrichment table (~30-day freshness).
If stale or missing, resolves the IP through Didit’s enrichment pipeline with multi-provider failover.
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

Field	Description
`ip_country`	Country name
`ip_country_code`	ISO 3166-1 alpha-2 when resolved by Didit (a value you submitted is kept as sent); rule conditions normalize both forms
`ip_state`	Subdivision (state, region)
`ip_city`	City name
`latitude`, `longitude`	Geographic coordinates
`isp`	Internet service provider name
`organization`	Registering organization name
`is_vpn_or_tor`	Boolean — the IP is a known VPN or Tor exit
`is_data_center`	Boolean — the IP belongs to a hosting/data-center range
`time_zone`	IANA time zone (e.g. `America/New_York`)
`time_zone_offset`	Offset from UTC
`asn_number`	Autonomous System Number
`asn_organization`	ASN’s registered organization
`connection_type`	`mobile`, `broadband`, `dialup`, `corporate`, …
`carrier`	Mobile carrier (for mobile IPs)
`proxy_type`	`VPN`, `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

Layer	TTL	Purpose
In-memory cache	24 hours	Sub-millisecond lookup for hot IPs
Shared IP-enrichment table	~30 days	Shared across instances; cheaper than re-resolving
Enrichment pipeline	n/a	Fresh 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. There is no separate enrichment block. The enriched fields are written into the party’s own device.network_context object, next to the ip_address you submitted, on the matching entry of the parties array:

"parties": [
  {
    "role": "APPLICANT",
    "vendor_data": "user-42",
    "device": {
      "network_context": {
        "ip_address": "203.0.113.5",
        "ip_country": "United States",
        "ip_country_code": "US",
        "ip_state": "California",
        "ip_city": "San Francisco",
        "is_vpn_or_tor": false,
        "is_data_center": false,
        "asn_number": 64496,
        "asn_organization": "Example ISP",
        "proxy_type": null
      }
    }
  }
]

Fields you supplied on the request are preserved; enrichment only fills the keys you left out, and keys the resolver returned empty are omitted. See the response schema for the full device shape. 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.

Getting Started

Features

Reference

Console

When enrichment runs

Enriched fields

Using enriched fields in rules

Cache layers

Failure behavior

Validity filtering

Inspecting enrichment for a transaction

Privacy considerations

Next steps

Rules

Rule library

Response schema

​When enrichment runs

​Enriched fields

​Using enriched fields in rules

​Cache layers

​Failure behavior

​Validity filtering

​Inspecting enrichment for a transaction

​Privacy considerations

​Next steps

Rules

Rule library

Response schema

When enrichment runs

Enriched fields

Using enriched fields in rules

Cache layers

Failure behavior

Validity filtering

Inspecting enrichment for a transaction

Privacy considerations

Next steps