Skip to main content
POST
Create a verification request

Authorizations

Authorization
string
header
required

The single-use grant token (bss_…) returned by POST /sdk/create-session. It lives 5 minutes and is consumed by this call.

Body

application/json
user_email
string<email>
deprecated

Deprecated. Accepted and ignored — it is not stored.

return_url
string

Where the web flow returns after verification.

webhook_url
string<uri>
deprecated

Reserved. Webhook endpoints are configured in the Console (Settings → Developer Tools → Webhooks), not per request.

scope
string

The gate this request runs (the gate's action name, as listed in the Console under BotShield Gate).

sdk_type
enum<string>
Available options:
signal,
presence
mode
enum<string>
default:linked-account

linked-account = OAuth+passkey, private = direct WebAuthn (no PII)

Available options:
linked-account,
private
botshield_user_id
string<uuid>

Returning user ID to skip onboarding

partner_user_ref
string

Your own reference for this user (hashed at rest, never returned). Enables BotShield ID continuity: on later visits a returning human evaluates as human_verified without a ceremony.

Write the partner_user_ref ↔ BotShield ID linkage after a successful verification. Set false as a compliance escape hatch.

parent_request_id
string

The req_* id returned by the client pre-check (signal/evaluate) when this request is its presence ceremony; correlates the two events.

metadata
object

Response

Verification link created. NOTE: handler errors also arrive here (HTTP 200) as data.error — codes for this operation: 400 (partner not found / gate not active), 401, 403 (gate not in the token allowlist), 409 (pending request already exists — call revoke-verification).

data
object
required