{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","product":"Fraud Prevention","type":"markdown"},"seo":{"title":"Evaluate entities","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"evaluate-entities","__idx":0},"children":["Evaluate entities"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Entity Evaluation lets you evaluate a standalone entity, such as an IP address, against your configured ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/risk/rules"},"children":["risk rules"]}," and receive a recommendation (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ALLOW"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHALLENGE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DENY"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRUST"]},") in a single API call. Unlike the main ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/risk/recommendations"},"children":["recommendations flow"]},", this capability does not require a user action, a device ID, or SDK telemetry—just the entity to evaluate."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This makes it well suited for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pre-flight checks"]}," at the edge or API gateway before traffic reaches sensitive endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Offline lookups"]}," and manual investigations by your fraud team."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Support tooling"]},", batch review scripts, and allow/deny list validation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lightweight ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["server-to-server integrations"]}," where no SDK is deployed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you submit an entity for evaluation, Mosaic:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Enriches the entity"]}," with third-party intelligence. For IP addresses, this includes geolocation, ASN, organization, timezone, and VPN/anonymizer signals."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Returns the first matching production rule"]}," and issues a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommendation"]},". If no production rule matches, the recommendation defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ALLOW"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Separately reports any matching preview rule"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preview_rule"]},", so you can assess the impact of rules before promoting them to production. Preview rules never affect the returned recommendation."]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant B as Your backend\n participant M as Mosaic\n\n B->>M: POST /risk/v1/evaluate
entity type and value\n M-->>M: Enrich data for entity\n M-->>M: Validate production rules\n M-->>M: Validate preview rules\n alt Matching rule\n M-->>B:Recommendation as prescribed by rule
with rule name\n end\n alt No matching rules\n M-->>B: Allow recommendation
with preview rule name (if any)\n end\n\n","diagramHtml":"MosaicYour backendMosaicYour backendalt[Matching rule]alt[No matching rules]POST /risk/v1/evaluateentity type and valueEnrich data for entityValidate production rulesValidate preview rulesRecommendation as prescribed by rule with rule nameAllow recommendation with preview rule name (if any)","diagramHtmlDark":"MosaicYour backendMosaicYour backendalt[Matching rule]alt[No matching rules]POST /risk/v1/evaluateentity type and valueEnrich data for entityValidate production rulesValidate preview rulesRecommendation as prescribed by rule with rule nameAllow recommendation with preview rule name (if any)"},"children":["sequenceDiagram\n participant B as Your backend\n participant M as Mosaic\n\n B->>M: POST /risk/v1/evaluate
entity type and value\n M-->>M: Enrich data for entity\n M-->>M: Validate production rules\n M-->>M: Validate preview rules\n alt Matching rule\n M-->>B:Recommendation as prescribed by rule
with rule name\n end\n alt No matching rules\n M-->>B: Allow recommendation
with preview rule name (if any)\n end\n\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-entity-types","__idx":2},"children":["Supported entity types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Entity type"},"children":["Entity type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ip_address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An IPv4 or IPv6 address to evaluate against network-based rules."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-set-up-rules","__idx":3},"children":["Step 1: Set up rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create rules specifically for entity evaluation or reuse existing rules. In the Admin Portal, proceed to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fraud Prevention"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rules"]}," or manage rules via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/risk/rules.openapi"},"children":["Rules API"]},". For more guidance on rule creation and management, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/risk/rules"},"children":["Enforce rules"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, create a production rule that blocks IP traffic coming from sanctioned countries:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/rule_entity_evaluation.b73b33f4b21113ec4dbe2a5e8ca44ed392ca2af24ecc6d71b02fe76627ba94f8.e95a590b.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only a subset of rule matchers is relevant when evaluating IP addresses. The following matchers are supported: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ip_cidrs"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country_codes"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asn_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization_type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ip_timezone"]},". Matchers that require device, user, or session context (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_ids"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_ids"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action_type"]},") are not evaluated and won't affect the decision."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-evaluate-an-ip-address","__idx":4},"children":["Step 2: Evaluate an IP address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/risk/v1/evaluate"]}," with the entity you want to evaluate. The request must be authenticated using a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/token.openapi/other/getaccesstoken"},"children":["client access token"]}," generated by your client."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://api.transmitsecurity.io/risk/v1/evaluate' \\\n -H 'Authorization: Bearer ' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"entity_type\": \"ip_address\",\n \"entity_value\": \"192.0.2.45\"\n }'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes the recommendation, enrichment data, and a matched rule, if any. For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"entity_type\": \"ip_address\",\n \"entity\": \"192.0.2.45\",\n \"recommendation\": \"DENY\",\n \"matched_rule\": {\n \"rule_name\": \"Block sanctioned jurisdictions\"\n },\n \"data\": {\n \"country_code\": \"IR\",\n \"asn_id\": \"AS64501\",\n \"organization_name\": \"Example Telecom\",\n \"organization_type\": \"isp\",\n \"ip_timezone\": \"Asia/Tehran\",\n \"ip_is_vpn\": false,\n \"ip_is_anonymizer\": false\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"evaluating-entities-with-preview-rules","__idx":5},"children":["Evaluating entities with preview rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, a response can include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"entity_type\": \"ip_address\",\n \"entity\": \"5.6.7.8\",\n \"recommendation\": \"ALLOW\",\n \"data\": {\n \"country_code\": \"US\",\n \"organization_type\": \"hosting\",\n \"ip_is_vpn\": false,\n \"ip_is_anonymizer\": false\n },\n \"preview_rule\": {\n \"rule_name\": \"Flag cloud-hosted IPs\",\n \"recommendation\": \"CHALLENGE\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, no production rule matched (so the recommendation is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ALLOW"]},"), but a preview rule would have returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHALLENGE"]},". Use this to validate a rule's behavior with real traffic patterns before ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/risk/rules#manage-rules"},"children":["promoting it to production"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-act-on-recommendation","__idx":6},"children":["Step 3: Act on recommendation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Design backend logic that acts on the entity evaluation result and returned recommendation. For example, when the recommendation is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DENY"]}," because the entity matched a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"style","attributes":{},"children":["\n section article ul li {\n margin-top: 8px !important;\n }\n"]}]},"headings":[{"value":"Evaluate entities","id":"evaluate-entities","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Supported entity types","id":"supported-entity-types","depth":2},{"value":"Step 1: Set up rules","id":"step-1-set-up-rules","depth":2},{"value":"Step 2: Evaluate an IP address","id":"step-2-evaluate-an-ip-address","depth":2},{"value":"Evaluating entities with preview rules","id":"evaluating-entities-with-preview-rules","depth":3},{"value":"Step 3: Act on recommendation","id":"step-3-act-on-recommendation","depth":2}],"frontmatter":{"markdown":{"toc":{"depth":2}},"seo":{"title":"Evaluate entities"}},"lastModified":"2026-05-17T08:01:26.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/risk/evaluate_entity","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}