---
title: "Evaluate entity"
method: POST
path: "/evaluate"
---

# Evaluate entity

`POST /evaluate`

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

## Request body

- EvaluateEntityRequest
  - `entity_type` 'ip_address', required — The type of entity to evaluate.
  - `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.

## Response `200`

Entity evaluated successfully.

- EvaluateEntityResponse
  - `entity_type` 'ip_address', required — The type of entity to evaluate.
  - `entity` string, required — The entity value that was evaluated (echoed back from the request).
  - `recommendation` 'ALLOW' | 'TRUST' | 'CHALLENGE' | 'DENY', required — Recommendation derived from the first matching production rule. Defaults to `ALLOW` when no production rule matches.
  - `matched_rule` MatchedRule — The production rule that matched the entity, if any. Only present when a production rule matches.
    - `rule_name` string — Name of the matched production rule.
  - `data` IpEnrichmentData, required — Third-party intelligence data used during evaluation. Fields are populated on a best-effort basis; any field may be omitted when the provider does not return a value for the given IP.
    - `country_code` string — Country code resolved from the IP, per ISO 3166-1 alpha-2.
    - `asn_id` string — Autonomous System Number detected using the IP address.
    - `organization_name` string — Organization name associated with the IP address.
    - `organization_type` string — Organization type associated with the IP address (e.g., `hosting`, `isp`, `business`).
    - `ip_timezone` string — Timezone resolved from the IP address (TZ identifier).
    - `ip_is_vpn` boolean — Whether the IP is associated with a known anonymizing VPN service.
    - `ip_is_anonymizer` boolean — Whether the IP is associated with an anonymous proxy.
  - `preview_rule` PreviewRuleResult — 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.
    - `rule_name` string — Name of the matching preview rule.
    - `recommendation` 'ALLOW' | 'TRUST' | 'CHALLENGE' | 'DENY' — Recommendation the preview rule would have applied.

## Other responses

- `400` — Bad request. Returned when `entity_type` is not supported or when `entity_value` is not valid for the given `entity_type` (for example, a malformed IP address when `entity_type` is `ip_address`).
- `401` — Invalid authentication
- `403` — Invalid authorization
- `429` — Rate limit reached
- `500` — Internal error

---

[API](https://skmtc.dev/transmitsecurity/apis/entity-evaluation.md) · [All operations](https://skmtc.dev/transmitsecurity/apis/entity-evaluation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/transmitsecurity/entity-evaluation/revisions/6b8944d6130d/schema)