# Evaluate entities

Entity Evaluation lets you evaluate a standalone entity, such as an IP address, against your configured [risk rules](/guides/risk/rules) and receive a recommendation (`ALLOW`, `CHALLENGE`, `DENY`, or `TRUST`) in a single API call. Unlike the main [recommendations flow](/guides/risk/recommendations), this capability does not require a user action, a device ID, or SDK telemetry—just the entity to evaluate.

This makes it well suited for:

- **Pre-flight checks** at the edge or API gateway before traffic reaches sensitive endpoints.
- **Offline lookups** and manual investigations by your fraud team.
- **Support tooling**, batch review scripts, and allow/deny list validation.
- Lightweight **server-to-server integrations** where no SDK is deployed.


For example, a regulated customer (e.g., a bank or payments provider) needs to verify the traffic origin and block traffic from countries on their sanctions list before any transaction is processed.

## How it works

When you submit an entity for evaluation, Mosaic:

1. **Enriches the entity** with third-party intelligence. For IP addresses, this includes geolocation, ASN, organization, timezone, and VPN/anonymizer signals.
2. **Matches against your rules** in priority order. Only enabled rules are considered. A rule matches when its conditions are satisfied by either the submitted entity or its enriched attributes.
3. **Returns the first matching production rule** and issues a `recommendation`. If no production rule matches, the recommendation defaults to `ALLOW`.
4. **Separately reports any matching preview rule** in `preview_rule`, so you can assess the impact of rules before promoting them to production. Preview rules never affect the returned recommendation.


```mermaid
sequenceDiagram
    participant B as Your backend
    participant M as Mosaic

    B->>M: POST /risk/v1/evaluate<br>entity type and value
    M-->>M: Enrich data for entity
    M-->>M: Validate production rules
    M-->>M: Validate preview rules
    alt Matching rule
      M-->>B:Recommendation as prescribed by rule <br>with rule name
    end
    alt No matching rules
      M-->>B: Allow recommendation<br> with preview rule name (if any)
    end
```

## Supported entity types

| Entity type | Description |
|  --- | --- |
| `ip_address` | An IPv4 or IPv6 address to evaluate against network-based rules. |


## Step 1: Set up rules

Create rules specifically for entity evaluation or reuse existing rules. In the Admin Portal, proceed to **Fraud Prevention** > **Rules** or manage rules via [Rules API](/openapi/risk/rules.openapi). For more guidance on rule creation and management, see [Enforce rules](/guides/risk/rules).

For example, create a production rule that blocks IP traffic coming from sanctioned countries:

![](/assets/rule_entity_evaluation.b73b33f4b21113ec4dbe2a5e8ca44ed392ca2af24ecc6d71b02fe76627ba94f8.e95a590b.png)

Note
Only a subset of rule matchers is relevant when evaluating IP addresses. The following matchers are supported: `ip_cidrs`, `country_codes`, `asn_id`, `organization_name`, `organization_type`, `ip_timezone`. Matchers that require device, user, or session context (e.g., `device_ids`, `user_ids`, `action_type`) are not evaluated and won't affect the decision.

## Step 2: Evaluate an IP address

Send a `POST` request to `/risk/v1/evaluate` with the entity you want to evaluate. The request must be authenticated using a [client access token](/openapi/token.openapi/other/getaccesstoken) generated by your client.

```shell
curl -X POST 'https://api.transmitsecurity.io/risk/v1/evaluate' \
  -H 'Authorization: Bearer <CLIENT_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_type": "ip_address",
    "entity_value": "192.0.2.45"
  }'
```

The response includes the recommendation, enrichment data, and a matched rule, if any. For example:

```json
{
  "entity_type": "ip_address",
  "entity": "192.0.2.45",
  "recommendation": "DENY",
  "matched_rule": {
    "rule_name": "Block sanctioned jurisdictions"
  },
  "data": {
    "country_code": "IR",
    "asn_id": "AS64501",
    "organization_name": "Example Telecom",
    "organization_type": "isp",
    "ip_timezone": "Asia/Tehran",
    "ip_is_vpn": false,
    "ip_is_anonymizer": false
  }
}
```

### Evaluating entities with preview rules

Alternatively, a response can include a `preview_rule` if an evaluated entity matched a non-production rule. Matching a preview rule doesn't affect the recommendation but allows you to simulate a rule's impact before making it live.

```json
{
  "entity_type": "ip_address",
  "entity": "5.6.7.8",
  "recommendation": "ALLOW",
  "data": {
    "country_code": "US",
    "organization_type": "hosting",
    "ip_is_vpn": false,
    "ip_is_anonymizer": false
  },
  "preview_rule": {
    "rule_name": "Flag cloud-hosted IPs",
    "recommendation": "CHALLENGE"
  }
}
```

In this example, no production rule matched (so the recommendation is `ALLOW`), but a preview rule would have returned `CHALLENGE`. Use this to validate a rule's behavior with real traffic patterns before [promoting it to production](/guides/risk/rules#manage-rules).

## Step 3: Act on recommendation

Design backend logic that acts on the entity evaluation result and returned recommendation. For example, when the recommendation is `DENY` because the entity matched a `Block sanctioned jurisdictions` rule, the backend must block the request before it reaches downstream services. Persist the returned enrichment data in the audit log as evidence for the compliance decision.

section article ul li {
        margin-top: 8px !important;
    }