{
  "openapi": "3.0.2",
  "info": {
    "title": "Entity Evaluation",
    "version": "",
    "description": "Entity Evaluation API provided by Fraud Prevention lets you evaluate an entity (such as an IP address) against your configured [risk rules](/guides/risk/rules.md) without requiring a full user action. The entity is enriched with third-party intelligence (e.g., geolocation, ASN, VPN/anonymizer signals) and matched against tenant rules in priority order, returning a recommendation (`ALLOW`, `CHALLENGE`, `DENY`, or `TRUST`).\nTypical use cases include pre-flight checks (for example, blocking risky IPs at the edge before they reach sensitive endpoints), support tooling, and offline lookups.\n"
  },
  "servers": [
    {
      "url": "https://api.sbx.transmitsecurity.io/risk/v1",
      "description": "Sandbox environment"
    },
    {
      "url": "https://api.transmitsecurity.io/risk/v1",
      "description": "US production environment"
    },
    {
      "url": "https://api.eu.transmitsecurity.io/risk/v1",
      "description": "EU production environment"
    },
    {
      "url": "https://api.ca.transmitsecurity.io/risk/v1",
      "description": "CA production environment"
    },
    {
      "url": "https://api.au.transmitsecurity.io/risk/v1",
      "description": "AU production environment"
    },
    {
      "url": "https://api.gasne1-ts01.transmitsecurity.io/risk/v1",
      "description": "JP production environment"
    }
  ],
  "paths": {
    "/evaluate": {
      "post": {
        "summary": "Evaluate entity",
        "description": "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.\nIf no production rule matches, the recommendation defaults to `ALLOW`.\n",
        "operationId": "evaluateEntity",
        "security": [
          {
            "risk_access_token": []
          }
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/evaluate_entity_request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/success_evaluate_entity"
          },
          "400": {
            "$ref": "#/components/responses/bad_request"
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/forbidden"
          },
          "429": {
            "$ref": "#/components/responses/rate_limit_reached"
          },
          "500": {
            "$ref": "#/components/responses/internal_error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "evaluate_entity_request": {
        "type": "object",
        "required": [
          "entity_type",
          "entity_value"
        ],
        "properties": {
          "entity_type": {
            "$ref": "#/components/schemas/entity_type"
          },
          "entity_value": {
            "type": "string",
            "description": "The value of the entity to evaluate. When `entity_type` is `ip_address`, this must be a valid IPv4 or IPv6 address.\n",
            "example": "1.2.3.4"
          }
        }
      },
      "entity_type": {
        "type": "string",
        "description": "The type of entity to evaluate.\n",
        "enum": [
          "ip_address"
        ],
        "example": "ip_address"
      },
      "evaluate_entity_response": {
        "type": "object",
        "required": [
          "entity_type",
          "entity",
          "recommendation",
          "data"
        ],
        "properties": {
          "entity_type": {
            "$ref": "#/components/schemas/entity_type"
          },
          "entity": {
            "type": "string",
            "description": "The entity value that was evaluated (echoed back from the request).",
            "example": "1.2.3.4"
          },
          "recommendation": {
            "type": "string",
            "description": "Recommendation derived from the first matching production rule. Defaults to `ALLOW` when no production rule matches.\n",
            "enum": [
              "ALLOW",
              "TRUST",
              "CHALLENGE",
              "DENY"
            ],
            "example": "DENY"
          },
          "matched_rule": {
            "$ref": "#/components/schemas/matched_rule"
          },
          "data": {
            "description": "Enrichment data for the evaluated entity. The structure depends on the `entity_type`.\n",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ip_enrichment_data"
              }
            ]
          },
          "preview_rule": {
            "$ref": "#/components/schemas/preview_rule_result"
          }
        }
      },
      "matched_rule": {
        "type": "object",
        "description": "The production rule that matched the entity, if any. Only present when a production rule matches.\n",
        "properties": {
          "rule_name": {
            "type": "string",
            "description": "Name of the matched production rule.",
            "example": "Block restricted jurisdictions"
          }
        }
      },
      "preview_rule_result": {
        "type": "object",
        "description": "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.\n",
        "properties": {
          "rule_name": {
            "type": "string",
            "description": "Name of the matching preview rule.",
            "example": "Flag suspicious IPs"
          },
          "recommendation": {
            "type": "string",
            "description": "Recommendation the preview rule would have applied.",
            "enum": [
              "ALLOW",
              "TRUST",
              "CHALLENGE",
              "DENY"
            ],
            "example": "DENY"
          }
        }
      },
      "ip_enrichment_data": {
        "type": "object",
        "description": "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.\n",
        "properties": {
          "country_code": {
            "type": "string",
            "description": "Country code resolved from the IP, per ISO 3166-1 alpha-2.",
            "example": "CN"
          },
          "asn_id": {
            "type": "string",
            "description": "Autonomous System Number detected using the IP address.",
            "example": "AS4134"
          },
          "organization_name": {
            "type": "string",
            "description": "Organization name associated with the IP address.",
            "example": "Example ISP"
          },
          "organization_type": {
            "type": "string",
            "description": "Organization type associated with the IP address (e.g., `hosting`, `isp`, `business`).",
            "example": "hosting"
          },
          "ip_timezone": {
            "type": "string",
            "description": "Timezone resolved from the IP address (TZ identifier).",
            "example": "Asia/Shanghai"
          },
          "ip_is_vpn": {
            "type": "boolean",
            "description": "Whether the IP is associated with a known anonymizing VPN service.",
            "example": true
          },
          "ip_is_anonymizer": {
            "type": "boolean",
            "description": "Whether the IP is associated with an anonymous proxy.",
            "example": false
          }
        }
      }
    },
    "responses": {
      "success_evaluate_entity": {
        "description": "Entity evaluated successfully.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/evaluate_entity_response"
            },
            "examples": {
              "matched_production_rule": {
                "summary": "Example of a production rule matched (DENY)",
                "value": {
                  "entity_type": "ip_address",
                  "entity": "1.2.3.4",
                  "recommendation": "DENY",
                  "matched_rule": {
                    "rule_name": "Block restricted jurisdictions"
                  },
                  "data": {
                    "country_code": "CN",
                    "asn_id": "AS4134",
                    "organization_name": "Example ISP",
                    "organization_type": "hosting",
                    "ip_timezone": "Asia/Shanghai",
                    "ip_is_vpn": true,
                    "ip_is_anonymizer": false
                  }
                }
              },
              "no_match_with_preview": {
                "summary": "Example of a no production rule matched, but a preview rule would match",
                "value": {
                  "entity_type": "ip_address",
                  "entity": "5.6.7.8",
                  "recommendation": "ALLOW",
                  "data": {
                    "country_code": "US",
                    "asn_id": "AS15169",
                    "organization_name": "Example Cloud",
                    "organization_type": "hosting",
                    "ip_timezone": "America/Los_Angeles",
                    "ip_is_vpn": false,
                    "ip_is_anonymizer": false
                  },
                  "preview_rule": {
                    "rule_name": "Flag cloud-hosted IPs",
                    "recommendation": "CHALLENGE"
                  }
                }
              },
              "allow_default": {
                "summary": "Example of a no rule matched",
                "value": {
                  "entity_type": "ip_address",
                  "entity": "9.9.9.9",
                  "recommendation": "ALLOW",
                  "data": {
                    "ip_is_vpn": false,
                    "ip_is_anonymizer": false
                  }
                }
              }
            }
          }
        }
      },
      "unauthorized": {
        "description": "Invalid authentication"
      },
      "forbidden": {
        "description": "Invalid authorization"
      },
      "rate_limit_reached": {
        "description": "Rate limit reached"
      },
      "internal_error": {
        "description": "Internal error"
      },
      "bad_request": {
        "description": "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`).\n"
      },
      "not_found": {
        "description": "Not found"
      }
    },
    "securitySchemes": {
      "risk_access_token": {
        "type": "http",
        "scheme": "bearer",
        "description": "An access token generated by the [token endpoint](/openapi/token.openapi/other/getaccesstoken)",
        "bearerFormat": "JWT"
      }
    }
  }
}