HumanApproved™ Docs

Each check decides whether the purchase pauses. It looks for signs that an AI agent, rather than the customer, is completing the checkout. The decision is made by HumanApproved’s servers, not in the page, and the response is only ever continue or review: the detail behind each check is in the portal.

Two sources

Each product uses one source, chosen on its Agent detection page.

HumanApproved’s checks

The default. The embed looks at how the quote journey was used and at general device characteristics. HumanApproved adds what it can see about the request and its network, including agents that identify themselves. The checks are built into the embed.

Put the embed on every page of the quote journey, in your shared layout, not just the payment step. The checks consider the whole journey from the first page the script is on.

On the Agent detection page you can adjust the product’s sensitivity and exclude groups of checks. Agents that identify themselves always count.

Your own signal

If you already run bot detection, such as your CDN’s bot score or your own model, a product can use that instead. Pass the result as signal, to the embed or in the check’s body:

{
  "quoteRef": "HTA-4471920",
  "signal": { "source": "cloudflare", "score": 2, "verifiedBot": "ChatGPT-User" }
}

Field	What it is
`source`	Where the signal came from, for example `cloudflare` or `mcp`, for your records. Letters, digits, `_`, `.` and `-`, up to 40 characters. If it’s missing or doesn’t match, it’s recorded as `unknown`.
`score`	Your detector’s bot score, 0 to 100.
`verifiedBot`	The verified bot’s name, when your detector names one, for example `ChatGPT-User`.
`isAgent`	Your own verdict. `true` for every purchase through an agent-only flow.

On the Agent detection page you choose how the product reads it: your verdict (isAgent), a verified bot, or a bot score at or below a limit you set.

A signal passed through the browser can be altered by the agent driving it. Send it from your server where you can.

When to ask for approval

Whatever the source, the product’s When to ask for approval setting, on its Approval settings page, decides what happens next:

Setting	What happens
Only when an agent is detected	The checkout pauses when the check finds an agent. People buying for themselves go straight through.
Every purchase	Every checkout pauses for the customer’s approval, whoever is buying. For testing, demos, agent-only flows, or products where every sale needs it.
Never — monitor only	Every checkout is checked and recorded, but none pauses: every check returns `continue`.

New products start as monitor only. Review Agent detections in the portal over a representative period, including runs with the agents you expect, then switch to Only when an agent is detected and publish. See Monitor only.

From a server or agent flow

With no browser to look at, HumanApproved’s checks only see your server’s own request. Decide on the product instead: set Every purchase if every purchase through the flow is an agent’s, or use your own signal and send "signal": { "source": "mcp", "isAgent": true }. See Server and agent flows.

Fail-open behaviour

If a check gets no response within the configured timeout (default 2.5 seconds), or an error occurs, the embed lets the step proceed and reports the check as fail_open. The same applies if quoteDetails can’t provide the quote. See protect() options and Handling the outcome.

Limitations

Detection catches agents that identify themselves, automated browsers and most agents running in the cloud, but an agent designed to imitate a person may not be detected. Some real customers can look like agents too, for example someone using only a keyboard or a VPN. Keep your own controls at bind.

Privacy

The checks measure behaviour and general device characteristics: counts and timings of actions on the page. They never read what’s typed, which keys are pressed, where the pointer goes, or page addresses.
HumanApproved uses the request’s IP address to look up the network it came from.
A check carries no personal data. The quote and mobile are sent only when the checkout pauses for an approval.
The embed keeps one session value and one random visitor ID in the browser. Name the checks in your privacy notice and cookie policy before you go live, as you would fraud prevention.

See Regions and data.