Evaluations

An evaluation decides one benefit claim. You send what you know about the user and the claim. AbuseZero checks it against your policy, your workspace's full claim history and every signal family, and returns one final result, allow or deny, within the evaluation's time limit.

Every evaluation is saved before its response is sent. It keeps the exact policy version it ran under, so you can always explain a past decision, even after your rules change.

To report what happened after an evaluation, see Outcomes.

The evaluation objectCopy Anchor Link

GET /v1/evaluations/{id} returns the full evaluation object.

ReasonCopy Anchor Link

RiskCopy Anchor Link

SignalsCopy Anchor Link

An array with one entry for each signal family. It appears only in an evaluation's evidence, which needs the evaluation_evidence:read scope, and on the evaluation in the dashboard. Evaluation and preview responses don't include it.

See Risk Score and signals.

InputsCopy Anchor Link

Each key is received or missing.

missing inputs are the first thing to check when an integration behaves unexpectedly.

Browser dataCopy Anchor Link

You can fix site_not_listed, sdk_outdated and not_passed_on. The others are expected for some visitors, and evaluations still run without browser data.

Create an evaluationCopy Anchor Link

POST /v1/evaluations · Scope evaluations:create · Requires Idempotency-Key

Also available as abusezero evaluations create in the AbuseZero CLI, abusezero_create_evaluation on the AbuseZero MCP server and evaluate() in the AbuseZero Node.js SDK.

Evaluates one benefit claim and returns allow or deny. Call it from your server before you grant the benefit. Each evaluation uses workspace credits.

Request bodyCopy Anchor Link

Phone numbers and custom identifiers travel as keyed hashes, so AbuseZero matches them without ever receiving the raw value. See Send identifiers.

ExampleCopy Anchor Link

import { randomUUID } from "node:crypto";
import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({
  key: process.env.ABUSEZERO_SECRET_KEY!,
  outage: "throw",
});

// deviceToken is the value the browser SDK returned on your page.
export async function evaluateTrial(deviceToken: string) {
  // Reuse this key if you retry this attempt.
  const idempotencyKey = randomUUID();

  const evaluation = await abusezero.evaluate(
    {
      benefit: "pro_trial",
      claim_id: "trial_user_4821",
      subject: {
        external_id: "user_4821",
        email: "jordan@example.com",
        email_verified: true,
      },
      context: { ip: "203.0.113.42" },
      identifiers: { device_token: deviceToken },
    },
    idempotencyKey,
  );

  if ("status" in evaluation) {
    // Skipped: no allow or deny was decided.
  } else if (evaluation.result === "allow") {
    // Grant the trial.
  }
  return evaluation;
}

Replace the example IP address with the user's public address. 203.0.113.42 comes from a range reserved for documentation, and AbuseZero rejects documentation, private and other non-routable addresses with IP_NOT_ROUTABLE.

ResponseCopy Anchor Link

Returns 200 with the evaluation result.

{
  "object": "evaluation",
  "id": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
  "result": "allow",
  "risk": { "score": 10, "band": "low" },
  "reason": {
    "code": "default_allow",
    "message": "No rule matched, so the policy's default allowed this claim."
  },
  "outcome": { "state": "assumed_granted", "due_at": null }
}

{
  "object": "evaluation",
  "id": "eval_8a1d4f20-6c3b-4e57-b9d2-0f7e6a5c3b18",
  "result": "deny",
  "risk": { "score": null, "band": "not_assessed" },
  "reason": {
    "code": "prior_claim_email",
    "message": "An earlier claim used this email address."
  },
  "outcome": null
}

When the claim's outcome is awaiting_outcome, report it by outcome.due_at. See Outcomes.

An allowed claim's response also carries its outcome in two headers, AbuseZero-Outcome-State and, when there is a due time, AbuseZero-Outcome-Due-At.

Re-evaluating a claim_idCopy Anchor Link

A claim ID stands for one award of a benefit. AbuseZero keeps every claim consistent, however often you evaluate it:

• The same Idempotency-Key and body returns the original response. Nothing is evaluated twice.
• A new key for a claim that was allowed returns allow with the reason previously_authorized and the original evaluation's id.
• A claim whose outcome you reported as not_granted is evaluated again from the start.
• A claim ID already used by a different user returns CLAIM_CONFLICT. Use a new claim ID for each award.
• A claim ID from an earlier period of a calendar-based benefit returns CLAIM_PERIOD_ENDED. Use a new claim ID for each period.
• A claim whose outcome report is overdue returns OUTCOME_CONFLICT. Report its outcome before evaluating it again.

Skipped evaluationsCopy Anchor Link

When the workspace can't run an evaluation, the response is 200 with status: "skipped" and no result. No allow or deny was decided, so handle skips as their own branch.

{
  "object": "evaluation",
  "status": "skipped",
  "reason": "insufficient_credits"
}

New skip reasons can be added within v1. Handle an unknown reason like any other skip. The workspace owner manages credits, payments and plan limits in Workspace settings → Billing & Subscriptions.

ErrorsCopy Anchor Link

List evaluationsCopy Anchor Link

GET /v1/evaluations · Scope evaluations:read

Also available as abusezero evaluations list in the AbuseZero CLI, abusezero_list_evaluations on the AbuseZero MCP server and evaluations() in the AbuseZero Node.js SDK.

Lists evaluations, newest first.

Query parametersCopy Anchor Link

ExampleCopy Anchor Link

const page = await abusezero.evaluations({ result: "deny", days: 30, limit: 20 });

ResponseCopy Anchor Link

{
  "object": "list",
  "data": [
    {
      "object": "evaluation",
      "id": "eval_8a1d4f20-6c3b-4e57-b9d2-0f7e6a5c3b18",
      "benefit": "pro_trial",
      "claim_id": "trial_user_5307",
      "result": "deny",
      "reason": {
        "code": "prior_claim_email",
        "message": "An earlier claim used this email address."
      },
      "outcome": { "state": null },
      "policy_version": 3,
      "created_at": "2026-10-29T14:05:12.000Z"
    }
  ],
  "next_cursor": null
}

Each item is a summary. Retrieve an evaluation for its full detail.

ErrorsCopy Anchor Link

Retrieve an evaluationCopy Anchor Link

GET /v1/evaluations/{id} · Scope evaluations:read

Also available as abusezero evaluations get in the AbuseZero CLI, abusezero_get_evaluation on the AbuseZero MCP server and getEvaluation() in the AbuseZero Node.js SDK.

Returns the full evaluation object.

ExampleCopy Anchor Link

const evaluation = await abusezero.getEvaluation("eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93");

ResponseCopy Anchor Link

{
  "object": "evaluation",
  "id": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
  "benefit": "pro_trial",
  "claim_id": "trial_user_4821",
  "result": "allow",
  "reason": {
    "code": "default_allow",
    "message": "No rule matched, so the policy's default allowed this claim."
  },
  "outcome": { "state": "granted", "due_at": null },
  "policy_version": 3,
  "created_at": "2026-10-29T14:02:47.000Z",
  "mode": "protect",
  "risk": { "score": 10, "band": "low" },
  "inputs": {
    "email": "received",
    "ip": "received",
    "user_id": "received",
    "phone": "missing",
    "payment": "missing",
    "device": "received",
    "browser": "received"
  },
  "browser_data": "collected",
  "policy": {
    "id": "pol_c4d8e2a7-1b5f-4a93-8e6d-2f0b9c7a1e35",
    "version": 3
  }
}

ErrorsCopy Anchor Link

Retrieve an evaluation's evidenceCopy Anchor Link

GET /v1/evaluations/{id}/evidence · Scope evaluation_evidence:read

Also available as abusezero evaluations evidence in the AbuseZero CLI, abusezero_get_evaluation_evidence on the AbuseZero MCP server and evaluationEvidence() in the AbuseZero Node.js SDK.

Returns the full evaluation object with its signal family assessments, plus the request details AbuseZero retained for it. With an OAuth access token, the signed-in member also needs permission to reveal evidence.

ExampleCopy Anchor Link

const evaluation = await abusezero.evaluationEvidence("eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93");

ResponseCopy Anchor Link

The evaluation object, with signals and one more field:

{
  "object": "evaluation",
  "id": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
  "result": "allow",
  "signals": [
    { "family": "identity", "assessment": "clear" },
    { "family": "device", "assessment": "clear" },
    { "family": "network", "assessment": "clear" },
    { "family": "automation", "assessment": "clear" },
    { "family": "benefit_history", "assessment": "clear" }
  ],
  "evidence": {
    "request": {
      "benefit": "pro_trial",
      "claim_id": "trial_user_4821",
      "subject": {
        "external_id": "user_4821",
        "email": "jordan@example.com",
        "email_verified": true
      },
      "context": { "ip": "203.0.113.42" }
    },
    "device_profile": {
      "status": "captured",
      "expires_at": "2026-11-28T14:02:47.000Z"
    }
  }
}

The example shows only some fields of the evaluation object.

ErrorsCopy Anchor Link

Retrieve an evaluation's association graphCopy Anchor Link

GET /v1/evaluations/{id}/graph · Scope evaluations:read

Also available as abusezero evaluations graph in the AbuseZero CLI, abusezero_get_evaluation_graph on the AbuseZero MCP server and evaluationGraph() in the AbuseZero Node.js SDK.

Returns the other outcomes for the same benefit that are linked to this evaluation's claim through shared identifiers. See Association graph.

An allowed claim's graph starts from its outcome. A claim with no outcome, such as a denied claim, starts from the identifiers its evaluation recorded, so a prior-claim denial shows the earlier outcomes behind it.

ExampleCopy Anchor Link

const graph = await abusezero.evaluationGraph("eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93");

ResponseCopy Anchor Link

{
  "object": "evaluation_links",
  "evaluation": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
  "links": [
    { "outcome": "out_9e7c5a31-2d4b-4f86-b0a9-6c1e8d3f5a72", "family": "identity" },
    { "outcome": "out_9e7c5a31-2d4b-4f86-b0a9-6c1e8d3f5a72", "family": "device" },
    { "outcome": "out_1f3a5c7e-9b2d-4e6f-8a0c-3d5e7f9a1b24", "family": "network" }
  ],
  "linked_outcomes": 2,
  "complete": true
}

A link shows an observed association. A shared device or network doesn't by itself mean two claims came from one person.

ErrorsCopy Anchor Link