> ## Documentation Index > Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a verification request > Creates a verification request (deep link, web URL, QR code) for a gate. Requires an grant token from create-session. Returns 409 when a pending request already exists for the same gate and user. ## OpenAPI ````yaml /openapi.json post /sdk/create-verification-link openapi: 3.1.0 info: title: BotShield API version: 2.0.0 description: >- The BotShield partner API. **BotShield Gate** — ask whether a live human is present (Human Gate) or over an age threshold (Age Gate). The person confirms with their device biometric in the BotShield app and you receive a signed result. Partners learn *that* a user is human, never *who*. **Agents Ask** — your agent proposes an action, a verified human confirms or denies it, and BotShield signs a Proof of Resolution you can verify offline. Every operation answers HTTP 200 with a `data` envelope; handler errors arrive as `data.error`. See the API overview and error reference. In the `botshield-sdk` package these operations live under `client.census.*`, `client.verification.*` and `client.actions.*`. contact: name: BotShield Support email: support@botshield.ai url: https://botshield.ai servers: - url: https://api.botshield.ai/operations description: Production security: [] tags: - name: BotShield Gate description: >- Place a gate and learn whether a present human (Human Gate) or a human over an age threshold (Age Gate) confirmed. - name: Agents Ask description: >- Your agent proposes an action; a verified human confirms or denies it in the BotShield app; you receive a signed Proof of Resolution. paths: /sdk/create-verification-link: post: tags: - BotShield Gate summary: Create a verification request description: >- Creates a verification request (deep link, web URL, QR code) for a gate. Requires an grant token from create-session. Returns 409 when a pending request already exists for the same gate and user. operationId: SdkCreateVerificationLink requestBody: required: true content: application/json: schema: type: object properties: user_email: type: string format: email deprecated: true description: Deprecated. Accepted and ignored — it is not stored. return_url: type: string description: Where the web flow returns after verification. webhook_url: type: string format: uri deprecated: true description: >- Reserved. Webhook endpoints are configured in the Console (Settings → Developer Tools → Webhooks), not per request. scope: type: string description: >- The gate this request runs (the gate's action name, as listed in the Console under BotShield Gate). sdk_type: type: string enum: - signal - presence mode: type: string enum: - linked-account - private default: linked-account description: >- linked-account = OAuth+passkey, private = direct WebAuthn (no PII) botshield_user_id: type: string format: uuid description: Returning user ID to skip onboarding partner_user_ref: type: string description: >- 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. link_on_verify: type: boolean default: true description: >- Write the partner_user_ref ↔ BotShield ID linkage after a successful verification. Set false as a compliance escape hatch. parent_request_id: type: string description: >- The req_* id returned by the client pre-check (signal/evaluate) when this request is its presence ceremony; correlates the two events. metadata: type: object additionalProperties: true responses: '200': description: >- 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). content: application/json: schema: type: object required: - data properties: data: type: object properties: data: type: object required: - request_id - deep_link - web_url - qr_code_url - expires_at - pushed_to_devices properties: request_id: type: string deep_link: type: string web_url: type: string qr_code_url: type: string deprecated: true description: Reserved. Render your own QR code from `web_url`. expires_at: type: string format: date-time sdk_type: type: string enum: - signal - presence auth_mode: type: string enum: - linked-account - private scope: type: string organization: type: object properties: id: type: string pushed_to_devices: type: integer description: >- Number of the user's registered devices the request was pushed to (0 when the user is unknown or has no devices). gate_type: type: string enum: - human - age description: The type of gate this request ran against. age_threshold: type: - integer - 'null' enum: - 13 - 18 - 21 - null description: >- Age Gate (Beta): the threshold the gate asks about. Present on age gates only. error: $ref: '#/components/schemas/ErrorBody' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalError' security: - GrantTokenAuth: [] components: schemas: ErrorBody: type: object required: - message - statusCode description: >- Handler error. Arrives inside data.error with HTTP 200 — check for it before reading the result. properties: message: type: string statusCode: type: integer description: >- The HTTP status the error stands for (401, 403, 404, 409, 422, 500, 502). code: type: string description: Machine code when present, e.g. ttl_below_floor, ttl_above_ceiling. min_ttl_seconds: type: integer max_ttl_seconds: type: integer violations: type: array items: type: object properties: type: type: string path: type: string severity: type: string description: Adaptive Card TRUST-layer rejections (statusCode 422). InvalidInputError: type: object required: - message - input - errors properties: message: type: string example: Invalid input provided input: type: object additionalProperties: true errors: type: array items: type: object required: - propertyPath - invalidValue - message properties: propertyPath: type: string invalidValue: description: The invalid value message: type: string ErrorResponse: type: object required: - error properties: error: type: object required: - message - statusCode properties: message: type: string statusCode: type: integer responses: BadRequest: description: Invalid input content: application/json: schema: $ref: '#/components/schemas/InvalidInputError' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: GrantTokenAuth: type: http scheme: bearer description: >- The single-use grant token (`bss_…`) returned by `POST /sdk/create-session`. It lives 5 minutes and is consumed by this call. ````