> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deflect.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Bot Verdict

> Fetch bot verdict for a user session token

## Response Format

The API returns detailed information about the request, including:

* **Verdict** - Whether the request should be allowed (`can_pass: true/false`) and whether the token had already been redeemed (`redeemed: true/false`)
* **Device information** - Browser details, fingerprint, user agent
* **IP analysis** - Location, threat indicators, proxy/VPN detection
* **Session data** - Timing and behavioral analysis

## Token Redemption

Tokens can be verified more than once — replay does not produce an error. Use `verdict.redeemed` to detect it:

* `verdict.redeemed: false` — first time this token has been verified
* `verdict.redeemed: true` — this token was already verified by a previous `/verify` call

If your defense action should treat a token as single-use (e.g. login, signup, payment), reject the request when `verdict.redeemed` is `true`.

## Testing

For local development, use test action IDs that return predictable results without consuming API credits:

* **Success**: `t/FFFFFFFFFFFFF/111111111` (always returns `can_pass: true`)
* **Failure**: `t/FFFFFFFFFFFFF/000000000` (always returns `can_pass: false`)

See the [Defense Actions guide](/get_started/defense_action#testing-defense-actions) for more details.


## OpenAPI

````yaml POST /verify
openapi: 3.1.0
info:
  title: Deflect API
  description: API endpoints for Deflect Antibot
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.deflect.bot
security: []
paths:
  /verify:
    post:
      description: Fetch bot verdict for a user session token
      requestBody:
        description: Verdict request with session token and optional user identification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Verdict'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerdictResponse'
        '401':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  schemas:
    Verdict:
      required:
        - api_key
        - token
        - action_id
      type: object
      properties:
        api_key:
          type: string
          description: Your Deflect API Key
        action_id:
          description: Your Deflect Action ID
          type: string
        token:
          description: The user session token from the protected endpoint.
          type: string
        id:
          description: >-
            Optional user identifier for multi-accounting detection. Highly
            recommended to include.
          type: string
        email:
          description: >-
            Optional user email address. Response will include email risk
            assessment.
          type: string
          format: email
        phone_number:
          description: >-
            Optional user phone number in E.164 format. Response will include
            phone validation.
          type: string
    VerdictResponse:
      type: object
      properties:
        success:
          type: boolean
        user_id:
          type: string
          description: Echo of the user identifier passed in the request.
        score:
          type: integer
          description: Bot detection score from 0 (bot) to 100 (human).
        verdict:
          type: object
          properties:
            can_pass:
              type: boolean
              description: Whether the request should be allowed.
            redeemed:
              type: boolean
              description: >-
                True if the token had already been redeemed before this call.
                First call always returns false; subsequent calls with the same
                token return true. Use this to detect token replay.
        device:
          type: object
          properties:
            fingerprint:
              type: string
              description: >-
                Device fingerprint hash derived from canvas, audio, and font
                signals.
            user_agent:
              type: string
            browser:
              type: string
              description: Detected browser brand (e.g. chrome, firefox, edge, safari).
            languages:
              type: string
            timezone:
              type: string
            os:
              type: string
              description: >-
                Detected operating system (e.g. windows, macos, android, ios,
                linux).
            is_mobile:
              type: boolean
        ip:
          type: object
          properties:
            address:
              type: string
            type:
              type: string
              description: IP version (ipv4 or ipv6).
            is_datacenter:
              type: boolean
            is_proxy:
              type: boolean
            is_tor:
              type: boolean
            is_vpn:
              type: boolean
            is_threat:
              type: boolean
            is_bogon:
              type: boolean
            asn:
              type: string
              description: ASN organization name.
            asn_number:
              type: integer
        location:
          type: object
          properties:
            city:
              type: string
            postal_code:
              type: string
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code.
            continent:
              type: string
              description: Two-letter continent code.
            latitude:
              type: number
            longitude:
              type: number
        email:
          type: object
          description: Included when an email address is passed in the request.
          properties:
            address:
              type: string
              description: The email address as provided.
            normalized:
              type: string
              description: Normalized form with aliases resolved (e.g. Gmail dots removed).
            valid:
              type: boolean
              description: >-
                Whether the email address is syntactically and domain-level
                valid.
            trust_score:
              type: number
              description: Trust score from 0 (untrusted) to 1 (trusted).
            domain_name:
              type: string
            domain_type:
              type: string
              description: 'Domain classification: free, disposable, corporate, or unknown.'
            flags:
              type: array
              items:
                type: string
              description: Additional flags such as aliased, alias, or public_inbox.
        phone:
          type: object
          description: Included when a phone number is passed in the request.
          properties:
            valid:
              type: boolean
              description: Whether the phone number is valid.
            country_code:
              type: string
              description: ISO 3166-1 alpha-2 country code.
            country_name:
              type: string
            carrier:
              type: string
            line_type:
              type: string
              description: Line type such as mobile, fixed_line, voip, or toll_free.
        session:
          type: object
          properties:
            started_at:
              type: string
              format: date-time
            finished_at:
              type: string
              format: date-time
        rules:
          type: array
          description: Bot rules and access rules that matched this request.
          items:
            type: object
            properties:
              action:
                type: string
                description: Rule action (e.g. block, allow, shadow).
              name:
                type: string
              id:
                type: string
              source:
                type: string
                description: Rule source (e.g. bot_rule, access_rule, list).
              shadow:
                type: boolean
                description: If true, the rule matched but is in shadow/monitor mode.
        multi_accounting:
          type: object
          description: >-
            Multi-accounting detection results. Requires a user id in the
            request.
          properties:
            detected:
              type: boolean
              description: Whether linked accounts were found.
            risk:
              type: string
              description: 'Risk level: none, low, medium, or high.'
            score:
              type: integer
              description: Highest confidence score across linked accounts (0-100).
            accounts:
              type: array
              description: Linked accounts sharing signals with this user.
              items:
                type: object
                properties:
                  user_id:
                    type: string
                  email:
                    type: string
                  signals:
                    type: array
                    items:
                      type: string
                    description: Shared signals (e.g. device_id, ip, email, email_domain).
                  confidence:
                    type: integer
                    description: Confidence score 0-100 for this linked account.
                  session_count:
                    type: integer
                    description: Number of sessions from this linked account.
                  last_activity:
                    type: string
                    format: date-time
    UnauthorizedError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: invalid_token
      required:
        - success
        - message

````