Result states

A BotShield Gate verification has exactly two outcomes. Either a real human confirmed they are present, or BotShield could not confirm that right now. There is no score, no confidence value, and no “bot” verdict.

The two states

Result state	Wire value	Meaning
Verified	`human_verified`	A real human is present. They confirmed with their device biometric, or they are a returning human on a Recent Presence gate.
Unavailable	`unavailable`	BotShield cannot return a verified result for this request. Nothing more is implied.

You see the same two states on every surface:

Surface	Verified	Unavailable
Widget events	`botshield:success`	`botshield:failure` with a `reason`
`botshield:census-status` event	`result_state: "human_verified"`	`result_state: "unavailable"`
Webhooks	`gate.human_verified`	`gate.unavailable`
`GET /verification/status`	`status: "completed"` or `"pass"`	`status: "failed"` or `"expired"`

(census in the event name is the API’s name for BotShield Gate.) The botshield:census-status event fires after the widget’s first check. On a Human Gate, unavailable at that point usually means “a confirmation on the phone is needed”, and the widget continues to the QR code or deep link. Wait for botshield:success or botshield:failure before you decide anything.

Why there is no score

A score asks you to pick a threshold and to accept that some humans fall under it. BotShield does not estimate how human a session looks. It asks a human to confirm on their own device, and reports whether that happened. That is also why there is no “bot” verdict. BotShield can observe that a human confirmed. It cannot observe that a human is absent. A person who declines, walks away, or has an unsupported phone looks the same as an automated client that never finishes. BotShield reports Unavailable in all of those cases and leaves the policy decision to you.

What Unavailable covers

A gate.unavailable webhook comes in two shapes. A failure carries failed_at and a reason. It is sent when the BotShield app reports that the confirmation did not succeed, and when a request that was opened fails on BotShield’s side.

`reason`	What happened
`user_denied`	The human cancelled or declined the confirmation, for example by dismissing the biometric prompt.
`device_lock_required`	The human’s phone reported no passcode, screen lock, or biometric, so it cannot produce a confirmation. See Device security.
`platform_declined`	The phone’s platform refused the confirmation, because it does not support it or blocked it for a security reason.
`internal_error`	Anything else. This is the default, and BotShield sends it whenever it has no more specific reason.

{
  "type": "gate.unavailable",
  "event_id": "req_3f9a1c…",
  "request_id": "req_3f9a1c…",
  "failed_at": "2026-09-21T17:05:40.000Z",
  "reason": "user_denied",
  "error_message": "User cancelled passkey verification",
  "environment": "development",
  "product": "census",
  "metadata": { "booking_ref": "MA-20418" }
}

environment tells you which environment the request ran in. metadata holds only the keys you supplied when you created the request, and is left out when you supplied none. See Webhook events. An expiry carries expired_at and no reason. A verification request expires five minutes after it is created. The expiry event is sent when the human opens the request after that point. reason is there to help you choose the right message: a person who cancelled needs a retry button, and a phone with no screen lock needs a line of help. All four values are still the same result state, Unavailable.

Do not wait for a gate.unavailable webhook before you let the user move on. A request that the human never opens on their phone expires without sending any webhook. Treat any request with no Verified result by its expires_at as Unavailable.

The widget reports its own reason on botshield:failure. expired and failed are user outcomes. origin_not_allowed (your page’s origin is not on the site key’s list), invalid_site_key (the site key is unknown or revoked), and gate_not_found (the key’s environment has no Active gate with that gate key) are configuration errors on your side. The separate botshield:cancel event, with request_id in its detail, fires when the person closes the widget’s modal before finishing. The widget goes back to idle, and no result state is reported, because the person can start again. See Web component for the full list.

The verification status enum

GET /verification/status?request_id=… returns a status field. It needs no API key, and it returns its payload directly under data.

`status`	Meaning	Result state
`pending`	The request exists and the human has not finished.	None yet
`completed`	The human confirmed on their phone. `verified_at` and `verification_token` are set.	Verified
`pass`	A recognized returning human passed a Recent Presence gate instantly. There is no token. The record reads `expired` 60 seconds after the check.	Verified
`failed`	The confirmation did not succeed. `error_message` may say why.	Unavailable
`expired`	The request passed its `expires_at` without completing.	Unavailable
`not_found`	No request has this `request_id`. `found` is `false`.	None
`error`	The lookup itself failed. Retry.	None

{
  "data": {
    "found": true,
    "status": "completed",
    "request_id": "req_3f9a1c…",
    "organization_id": "org_…",
    "created_at": "2026-09-21T17:03:52.000Z",
    "expires_at": "2026-09-21T17:08:52.000Z",
    "verified_at": "2026-09-21T17:04:11.000Z",
    "verification_token": "eyJhbGciOiJFUzI1NiIs…",
    "signed_token": null,
    "error_message": null,
    "sdk_type": "signal",
    "scope": "checkout",
    "presence_address": null,
    "gate_type": "human",
    "age_threshold": null,
    "age_verdict": null,
    "age_source": null,
    "metadata": {
      "scope": "checkout",
      "sdk_type": "signal",
      "environment": "development",
      "return_url": null,
      "parent_request_id": "req_8d02…"
    }
  }
}

Never test for status === "completed" alone. Accept completed or pass as Verified. Look up an instant pass as soon as your page reports it. If the record already reads expired, ask the user to verify again. See the Quick start.

On an Age Gate (Beta), status: "completed" means a human confirmed. It does not mean the age threshold was met. Read age_verdict as well. See Age Gate.

Design for Unavailable

Unavailable is an ordinary outcome for real people. Phones run out of battery, people change their minds, and some people do not have the BotShield app yet. Offer, never punish.

Offer a way forward. Let the user try again, or route them to the path you already had: a waiting room, your existing challenge, manual review, or a later attempt.
Do not label the user. Avoid copy such as “bot detected” or “verification failed, access denied”. Prefer “We couldn’t confirm you just now.”
Do not penalize the account. Do not lock, flag, or downgrade a user because a verification was Unavailable.
Reward Verified instead. Give verified humans the better path: earlier access, a skipped challenge, a reserved allocation. The gate then pulls people in rather than pushing them out.
Keep retries cheap. A new attempt creates a new request. Nothing carries over from the Unavailable one.

BotShield ID

Why returning humans pass Recent Presence gates instantly.

Webhook events

Full payloads for gate.human_verified and gate.unavailable.

Web component

Widget events and failure reasons.

Device security

What happens when the user’s phone has no screen lock.

Get Started

BotShield Gate

Trusted Accounts

Agents Ask

Webhooks

Console

Server SDK

Integrations

Concepts

Changelog

The two states

Why there is no score

What Unavailable covers

The verification status enum

Design for Unavailable

BotShield ID

Webhook events

Web component

Device security

​The two states

​Why there is no score

​What Unavailable covers

​The verification status enum

​Design for Unavailable

BotShield ID

Webhook events

Web component

Device security

The two states

Why there is no score

What Unavailable covers

The verification status enum

Design for Unavailable