Policies and rules

A policy decides allow or deny for every claim of every benefit that uses it. Protection levels are policies AbuseZero manages. Custom policies are yours: an optional protection level to build on, your own rules, a risk threshold and a default result.

Why it mattersCopy Anchor Link

Every product has its own idea of a fair claim. You may want to approve every user whose email and phone your app verified, or deny claims from networks you never serve. Custom policies let you write that down once, in AbuseZero, and change it at any time without touching your code.

Key capabilitiesCopy Anchor Link

• Validation on save. Unsupported conditions, values of the wrong type and out-of-range numbers are rejected when you save, so a broken rule never reaches a live evaluation.
• Immutable versions. Each change creates a new policy version. Every evaluation records the version it ran under, and the full history stays readable.
• Consistent conditions. Conditions mean exactly the same thing in live evaluations, previews, simulations and replays.
• Shared policies. A change applies to every benefit that uses the policy, for future evaluations.
• Safe concurrent edits. Updates carry a revision. An update against an older revision is refused with POLICY_CONFLICT.

Rule orderCopy Anchor Link

A policy reads from top to bottom:

1. Your rules, in the order you list them. The first rule that matches decides the claim.
2. The protection level you build on, if any, for the claims your rules don't decide.
3. The risk threshold. A claim whose AbuseZero Risk Score reaches it is denied.
4. The default result for everything else.

Allow and block list entries decide a matching claim outright, whatever the policy says. So does a benefit whose automation setting is deny, for claims with detected automation. See Allow and block lists and Bots and AI agents.

{
  "base": "balanced",
  "risk_threshold": 75,
  "default_result": "allow",
  "rules": [
    {
      "id": "allow_verified_first_claims",
      "name": "Verified users with no earlier claims",
      "result": "allow",
      "when": {
        "all": [
          { "signal": "email.verified", "operator": "eq", "value": true },
          { "signal": "phone.verified", "operator": "eq", "value": true },
          { "signal": "user.prior_claims", "operator": "eq", "value": 0 }
        ]
      }
    },
    {
      "id": "deny_disposable_on_anonymous_network",
      "name": "Disposable email on an anonymous network",
      "result": "deny",
      "when": {
        "all": [
          { "signal": "email.disposable", "operator": "eq", "value": true },
          { "signal": "network.anonymous", "operator": "eq", "value": true }
        ]
      }
    }
  ]
}

RulesCopy Anchor Link

A group holds 1 to 10 entries. Groups can contain groups, up to two levels deep. A rule can have up to 10 conditions in total.

When one of your rules decides a claim, the evaluation's reason has the code custom_rule and the rule's id as rule. When you read the evaluation, the message names the rule:

"reason": { "code": "custom_rule", "message": "Your rule “Disposable email on an anonymous network” matched this claim.", "rule": "deny_disposable_on_anonymous_network" }

ConditionsCopy Anchor Link

Each condition compares one signal with a value:

{ "signal": "network.risk", "operator": "eq", "value": "high" }

A comparison never matches when the signal has no known value. To act on a missing or unavailable signal, add a condition with is_missing, is_unknown or is_unavailable.

Available signalsCopy Anchor Link

GET /v1/policy-signals returns the built-in signals with their labels, types and allowed values, so your tools can build rule editors from it.

VersionsCopy Anchor Link

Each save creates a new version, and the policy's active_version moves to it. GET /v1/policies/{id}/versions lists every version, and GET /v1/policies/{id}/versions/{version} returns your definition as it was in that version. When an evaluation surprises you, open it, note its policy.version, and read that version.

ConfigurationCopy Anchor Link

• Create, update, duplicate and delete custom policies in the dashboard or through the Policies API. A policy can't be deleted while a benefit uses it. Reassign those benefits first.
• Test before you save. Preview a claim, simulate a sequence of claims, or replay recent traffic against a new policy. See Test changes safely.
• Attach the policy by setting a benefit's policy_key to the policy's key.

Programmatic accessCopy Anchor Link

Next stepsCopy Anchor Link