4. The fields to act on

The verdictCopy Anchor Link

With the package, heedeo.evaluate() answers a verdict: the answer below in data, and the same answer read for you. Read the verdict first, and reach into data for a count or a fact.

const verdict = await heedeo.evaluate({ token, action: "signup", email });

verdict.flagged;                  // stop this action
verdict.trusted;                  // you pressed Trust on this person
verdict.has("vpn", "tor");        // any of these reasons fired
verdict.certain("repeat_action"); // it fired at full strength
verdict.noToken;                  // no usable token: ask for your own verification step
verdict.toLog();                  // one object for your log line
verdict.data;                     // the whole answer, below; null when Heedeo did not answer

Every read is safe when Heedeo did not answer: nothing is flagged, so an outage never refuses anyone, and error.code says what happened. data.flagged and data.no_token are the same reading, made by Heedeo: every answer carries them first, a stored one replayed by request_id and a webhook’s event too, so a caller without the package reads them as they are. The verdict reads them (from @heedeo/sdk 0.2.0-beta.1, the first with the verdict), and on an answer from before them reads flag, listed and the notes the same way. data.flag does not know about Trust: it is still true for a flagged person you trust, which is why a rule reads flagged. A copy (a spread, JSON) keeps the values, flagged among them, and loses the four functions. verdictOf({ data, error: null }) from @heedeo/sdk reads an answer you already hold the same way, such as the event of an event.scored webhook or an answer in a test.

Read this, not thatCopy Anchor Link

Some facts appear twice in an answer. Read one:

The fields under Not stay in every answer, for the code that already reads them. On a workspace still on the legacy verdict, decision is a preview of the decision and can disagree with flag, so it does not say why: read it as the reason only where decision.flag equals flag, the check toLog().by makes. The same holds for an answer stored while a workspace was legacy.

Trust and Block, in each placeCopy Anchor Link

One label, named four ways. It sits on a person, an email address or a network; Review and an assistant set it on a person or an email address, and a network’s comes through the package or POST /v1/lists.

An evaluation’s listed reads every label that matches it, the person’s, the email’s and the network’s, and a Block wins over a Trust.

A Trust also keeps Auto-confirm (Settings) off the flags it covers, on the person, the email or the network: they are still raised and sent as flag.created, and wait in Review for you, unless a Block outweighs the Trust, as in listed.

Dismiss is not Trust. Dismiss on a flag records the outcome legit, as outcome(), resolve_flag with dismiss and POST /v1/outcomes do: the person’s next events score lower, and verdict.trusted stays false. Only a Trust label makes flagged false whatever the score.

trust(), block() and clearLabel() need @heedeo/sdk 0.2.0-beta.1 or later.

The answerCopy Anchor Link

The answer to a signup that Heedeo flagged: the same person signed up a second time, under another email, from the same browser.

{ "flagged": true,
  "no_token": false,
  "flag": true,
  "score": 150,
  "threshold": 100,
  "thresholds": { "verify": 60, "review": 100, "block": null, "action": null },
  "suggested": "review",
  "decision": { "flag": true, "band": "review", "score": 150, "risk": "account_abuse", "by": "risk", "judged": ["account_abuse"] },
  "risks": { "account_abuse": { "score": 150, "judged": true,
                                "reasons": [{ "code": "repeat_action", "weight": 100 }, { "code": "many_identities", "weight": 50 }] } },
  "version": null,
  "reasons": [{ "code": "repeat_action", "text": "signup already done by this visitor on 7 Nov from this browser", "weight": 100, "base": 100 },
              { "code": "many_identities", "text": "This event raised the visitor's identities to 2; the threshold is 3", "weight": 50, "base": 50 }],
  "visitor": { "id": "613d…", "confidence": 1, "first_seen": "…", "last_seen": "…",
               "emails": { "24h": 2, "7d": 2, "all": 2 }, "accounts": { "24h": 0, "7d": 0, "all": 0 },
               "addresses": { "1h": 1, "24h": 1, "7d": 1 }, "countries": { "1h": 1, "24h": 1, "7d": 1 },
               "browsers": [{ "id": "613d…", "kind": "stored", "confidence": 1, "merged_by": "this browser", "evidence": {}, "first_seen": "…", "last_seen": "…" }],
               "aliases": [],
               "actions": { "signup": { "count": 2, "first": "2026-11-07T18:10:31Z", "last": "…" } } },
  "related": [],
  "account": null,
  "counts": { "24h": 2, "7d": 2 },
  "activity": { "last_hour": 2, "hourly_norm": 0.4, "burst": false },
  "listed": null,
  "email": { "disposable": false, "alias_of_existing": false, "pattern": false, "free_provider": true, "role_address": false,
             "young_domain": false, "domain_registered": null, "domain_age_unknown": false, "breach": null },
  "network": { "link_weight": 0.5, "datacenter": false, "vpn": false, "vpn_confidence": null, "vpn_service": null,
               "residential_proxy": false, "residential_proxy_confidence": null, "proxy_services": [], "proxy": false, "tor": false,
               "private_relay": false, "anonymous": false, "network_type": "isp", "asn": "AS7922", "devices": 3, "risks": [],
               "country": "US", "city": "Boston", "region": "Massachusetts", "timezone_mismatch": false },
  "agent": null,
  "environment": { "tampered": false, "tamper": [], "tampered_confidence": null, "anti_detect": null, "virtual_machine": false, "vm": [],
                   "virtual_machine_confidence": null, "private_mode": false, "rarity": 1, "connection": null,
                   "automation_framework": null, "interaction": { "pointer": 41, "key": 52, "touch": 0 } },
  "event_id": "79c7…" }

flagged and no_token. flagged is whether to stop this action: flag, unless you pressed Trust on the person (listed: "allow"). no_token is whether the event came with no usable token (a note no_token, token_expired or unknown_visitor in reasons), false for a person you trust: ask for your own verification step. Each is derived from the answer when it is sent, so an answer read back later says what it said then.

flag and decision. flag is whether the action reached your flag line, or you blocked or reported the person; it does not know about Trust, so read flagged to decide. decision says why, in the same six fields on every event: flag; band, which your thresholds under Settings make of score (allow, verify, review from the flag line, block once you set one); score; risk, the question that reached your flag line; by, what decided: risk (Heedeo’s answer to that question), label (your Block label on the person, their email or their network) report (your abuse report on the person or an account they used) or retry (a once action tried again by the same person under the email or account of an earlier attempt, which keeps at least that attempt’s band until you resolve it as legit), and null when nothing flagged; and judged, the questions Heedeo judges this action on: account_abuse for the once actions of section 3, none for a login or a name of your own. That is Heedeo’s rule, read from the action’s name; nothing in the call chooses it. A flag can also appear later on an earlier signup, when Heedeo learns that two people are one, and it goes away again (withdrawn, section 12) if that turns out wrong.

risks. What Heedeo answers to each question about the person. There is one today, account_abuse: one person making more than one account. Each has its score, judged (whether Heedeo judges this action on it) and its reasons, each with the weight it contributed. Every question is scored on every event: on a login, risks.account_abuse still says what a signup would have answered, with judged: false.

The rest of the decision:

• score and suggested: the decision’s score and band, at the top level as integrations read them.
• threshold and thresholds: your flag line and your Verify, Flag and Block lines under Settings, Advanced (60, 100 and none by default). An action can have its own three (Settings, Advanced, Actions): then thresholds.action names it.
• version: when your weights last changed, or null while you use the defaults (Settings, Advanced, Weights; section 9).
• reasons: every reason that fired, each with one line of text for you, never for the end user, its weight, what it contributed to this action (0 on an action judged on nothing), and base, the same at the default weights. Every code, and the four notes that ride in reasons with weight 0 (no_token, token_expired, unknown_visitor, no_identity), is in the table under Reasons and default weights, below.
• listed: your own label for this visitor, email or network: "block", "allow" or null.

Heedeo enforces nothing: your code reads the answer and decides (section 5).

The visitor (visitor is null without a usable token):

• visitor.id: the visitor, one id for the person across their browsers, decided by Heedeo on every event: your code stores nothing to group them. An id you stored earlier is the visitor’s id or one of its aliases (section 7, Merges, has the undo).
• visitor.confidence: how sure Heedeo is that every browser in visitor.browsers is this person: 1 when it is certain.
• visitor.first_seen and last_seen: when Heedeo first and last saw the visitor.
• visitor.browsers: the person’s browsers, the oldest first, each with the fields in the table after this list. A browser of the person is here, not in related.
• visitor.aliases: the ids a merge retired into this one, the newest first (up to 100). Each still resolves: GET /v1/visitors/<id> and POST /v1/outcomes with a retired id answer the visitor it joined, with merged_into set to its id (section 10), so a customer who stored the old id learns the new one on its next lookup, or at once from a visitor.merged webhook (section 12).
• visitor.actions: what the visitor did, by action name, across its browsers, this event included: count, and the first and last time. Kept 13 months (section 7).
• visitor.emails.all and visitor.accounts.all: distinct canonical emails and account ids this visitor has shown you across its browsers, ever (also 24h, 7d), this event included. At signup, before a user id exists, emails is the one to use.
• visitor.addresses and visitor.countries: how many different network addresses and countries this visitor’s browsers came from in the last hour, day and week (1h, 24h, 7d), this event included. Mobile networks, Private Relay and Tor are not counted: many people share them. Home, work and a café are three addresses in a day; many in an hour, or several countries in a day, deserves a look.
• The principal (acting_for): the people a declared or verified agent acts for are expected, and do not count as its accounts. An anonymous browser acting for many people is multi-accounting under another name, and they count.

Each browser in visitor.browsers has:

Around the visitor:

• counts: this browser’s events of this action, over 24h and 7d.
• related: browsers of other visitors related to this visitor’s browsers, one entry per link, the strongest first. Each has visitor_id (the visitor that browser is in now), link, weight (how much the link proves, from 0 to 1) and the other browser’s own identities. The visitor’s own browsers are in visitor.browsers. link is one of the values in the table after this list.
• account, when you sent a user_id, the facts for a login rule (section 5): visitors, the browsers that have presented this account over 24h, 7d and all, this one included, and new_browser, whether this browser is new to it. They are facts for your rule, never a flag. null without a user_id.
• email, what Heedeo read from the address (Email depth, in section 3), with the fields in the table after this list.
• network, what Heedeo knows of the event’s address, with the fields in the table after this list.
• agent, null when nothing says an agent or a program sent the request: operator (the operator the agent names or proves), verified (it signed with Web Bot Auth, or your edge verified it), declared (what its user agent claims), operator_network (the address is in an agent operator’s network), automation (the browser shows automation), http_client and missing_headers. A headless or automated browser shows in agent.automation, and is the automation reason only when no agent is declared or verified.
• agent.http_client: the HTTP library, tool or crawler the request’s user agent names, such as curl, python-requests or googlebot, or null. A name means a program, not a person’s browser, sent the request.
• agent.missing_headers: the headers every browser sends that this request lacked, such as ["accept-language"]; [] when none was missing. null when Heedeo cannot tell, as from @heedeo/sdk before 0.1.0-pilot.17 or a call without :forwarded (section 3). A non-empty list means the request most likely did not come from a person’s browser.
• Your own server-to-server calls, your mobile app, and a CDN or proxy in front of your server that does not pass the browser’s headers through can show in either field, so check for those before a rule refuses on either. Neither field is a reason; use them in your own rule.
• environment, what the identification’s browser showed of itself, null without an identification, with the fields in the table after this list.
• activity: your traffic for this action in the last hour against its weekly hourly norm, and burst when it is well above. It is about your traffic, not this visitor. On a new or quiet account a few test signups are already a burst.

The values of related[].link:

The fields of email:

The fields of network. A field Heedeo could not learn for this address is null:

A confidence says how far to trust its flag in a rule of your own. Neither vpn nor residential_proxy is enough to act on alone, at any confidence: count high or medium beside another sign, and treat low as a hint, not enough to refuse anyone (RULES.md).

The fields of environment:

Testing: test traffic flags. Check what your rule does, not flag. Section 5, Test your rule, says what each test signup answers and why local tests score higher than real ones.

Reasons and default weightsCopy Anchor Link

Every reason, with its default as your Settings, Advanced, Weights table shows it before you accept your own. A trust reason speaks for the person and shows negative in reasons. A reason whose default is 0 is recorded: it shows in reasons wherever it fires, so you can see what it would catch, and decides nothing. A note says something about the call itself and decides nothing. The evidence reasons and how to send their evidence are under Evidence in section 3.