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
deprecated

The gate this request runs (the gate's action name, as listed in the Console under BotShield Gate). Deprecated (alias window, sunset 2027-01-15): use gate. Accepted through the window; responses carry both. https://docs.botshield.ai/changelog/alias-window

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 stable reference for this user (hashed at rest, never returned). Identifies the user for the pending-request check (409) and for Verified Accounts.

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
notarize
boolean

Run this ceremony as a notarize ceremony. The gate's Console switch (notarize_enabled) is the authority: the ceremony runs only when the switch is on. true with the switch off falls back to a plain verification with notarize_fallback_reason = notarize_not_enabled. false opts this placement out. Absent → inherited from the grant window, else offered when the switch is on. Requires partner_user_ref; never on an Age Gate. verification/complete writes the Verified Account binding in the same transaction as the completion.

gate
string

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

act
string

BotShield Actions: the act this tap is for — e.g. watch or dibs:listing_4417. The part before the first ':' must name a placed, live BotShield Action (Console → Verified Accounts › BotShield Actions, or the Gates API); the rest is yours and is never read — it rides the signed token as the act claim (verify-token echoes it verbatim), so your own check can tell one tap from another. Never together with gate/scope (action_not_a_gate). An action always stands on a verified account: partner_user_ref is required (action_requires_user_ref) and the tap runs the linking ceremony.

Maximum string length: 128
Pattern: ^[A-Za-z0-9][A-Za-z0-9_:.\-]{0,127}$
Example:

"dibs:listing_4417"

act_label
string

What the person is confirming, shown verbatim on their card (e.g. "Trade with sam_k — 2 GA for $180"). Only with act (act_label_without_act). Display only — it is NOT in the token; bind terms through act (e.g. a hash of them), which the token carries.

Required string length: 1 - 90
Example:

"Trade with sam_k — 2 GA for $180"

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). BotShield Actions and linking codes (data.error.code): act_label_without_act (400), action_not_a_gate (400), action_invalid (400 — act malformed), action_not_found (400 — no action with that key here), action_off (409), action_requires_user_ref (400), link_requires_user_ref (400 — the gate's policy is link: required and no partner_user_ref was sent).

data
object
required