# Evaluate entity

Evaluates an entity against the tenant's configured recommendation rules. The entity is enriched with third-party intelligence data and matched against enabled rules in priority order. Only the first matching production rule applies to the returned `recommendation`. Any matching preview rule is returned separately in `preview_rule` for impact analysis without affecting the final decision.
If no production rule matches, the recommendation defaults to `ALLOW`.

Endpoint: POST /evaluate
Security: risk_access_token

## Request fields (application/json):

  - `entity_type` (string, required)
    The type of entity to evaluate.
    Enum: "ip_address"

  - `entity_value` (string, required)
    The value of the entity to evaluate. When `entity_type` is `ip_address`, this must be a valid IPv4 or IPv6 address.
    Example: 1.2.3.4

## Response 200 fields (application/json):

  - `entity_type` (string, required)
    The type of entity to evaluate.
    Enum: "ip_address"

  - `entity` (string, required)
    The entity value that was evaluated (echoed back from the request).
    Example: 1.2.3.4

  - `recommendation` (string, required)
    Recommendation derived from the first matching production rule. Defaults to `ALLOW` when no production rule matches.
    Enum: "ALLOW", "TRUST", "CHALLENGE", "DENY"

  - `matched_rule` (object)
    The production rule that matched the entity, if any. Only present when a production rule matches.

  - `matched_rule.rule_name` (string)
    Name of the matched production rule.
    Example: Block restricted jurisdictions

  - `data` (any, required)
    Enrichment data for the evaluated entity. The structure depends on the `entity_type`.

  - `data.country_code` (string)
    Country code resolved from the IP, per ISO 3166-1 alpha-2.
    Example: CN

  - `data.asn_id` (string)
    Autonomous System Number detected using the IP address.
    Example: AS4134

  - `data.organization_name` (string)
    Organization name associated with the IP address.
    Example: Example ISP

  - `data.organization_type` (string)
    Organization type associated with the IP address (e.g., `hosting`, `isp`, `business`).
    Example: hosting

  - `data.ip_timezone` (string)
    Timezone resolved from the IP address (TZ identifier).
    Example: Asia/Shanghai

  - `data.ip_is_vpn` (boolean)
    Whether the IP is associated with a known anonymizing VPN service.
    Example: true

  - `data.ip_is_anonymizer` (boolean)
    Whether the IP is associated with an anonymous proxy.
    Example: false

  - `preview_rule` (object)
    Preview rule that would have matched if it were in production mode. Allows you to assess the impact of preview rules before promoting them to production.

  - `preview_rule.rule_name` (string)
    Name of the matching preview rule.
    Example: Flag suspicious IPs

  - `preview_rule.recommendation` (string)
    Recommendation the preview rule would have applied.
    Enum: "ALLOW", "TRUST", "CHALLENGE", "DENY"