Fingerprint Event Search API

openapi: 3.2.0
info:
  title: Fingerprint Server Event Search API
  description: The Fingerprint Server API lets you get, search, update, and delete identification Events and Visitors in a server environment.
  termsOfService: https://fingerprint.com/terms-conditions/
  contact:
    name: Fingerprint Support
    email: support@fingerprint.com
  license:
    name: MIT
    url: https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi/blob/main/LICENSE
  version: '3'
servers:
- url: https://api.fpjs.io
  description: Global
- url: https://eu.api.fpjs.io
  description: EU
- url: https://ap.api.fpjs.io
  description: Asia (Mumbai)
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Event Search
  description: Search identification events with filters.
paths:
  /events/search:
    get:
      tags:
      - Event Search
      operationId: searchEvents
      summary: Get events via search
      description: Search identification events for your workspace using a wide range of built-in filters, including visitorId, linkedId, bot, IP address, time range, suspect, and individual Smart Signal flags. Results are paginated with a cursor.
      parameters:
      - name: limit
        in: query
        required: true
        description: Limit the number of events returned.
        schema:
          type: integer
          format: int32
          minimum: 1
      - name: pagination_key
        in: query
        description: Cursor used to fetch the next page of results.
        schema:
          type: string
      - name: visitor_id
        in: query
        description: Filter events by visitorId.
        schema:
          type: string
      - name: bot
        in: query
        description: Filter by bot detection result (good, bad, all, none).
        schema:
          type: string
          enum:
          - good
          - bad
          - all
          - none
      - name: ip_address
        in: query
        description: Filter events by IP address or CIDR range.
        schema:
          type: string
      - name: linked_id
        in: query
        description: Filter events by linkedId.
        schema:
          type: string
      - name: start
        in: query
        description: Filter events created after this Unix epoch time (ms).
        schema:
          type: integer
          format: int64
      - name: end
        in: query
        description: Filter events created before this Unix epoch time (ms).
        schema:
          type: integer
          format: int64
      - name: reverse
        in: query
        description: Sort events from oldest to newest.
        schema:
          type: boolean
      - name: suspect
        in: query
        description: Filter events flagged as suspect.
        schema:
          type: boolean
      - name: vpn
        in: query
        description: Filter events where a VPN was detected.
        schema:
          type: boolean
      - name: virtual_machine
        in: query
        description: Filter events where a virtual machine was detected.
        schema:
          type: boolean
      - name: tampering
        in: query
        description: Filter events where request tampering was detected.
        schema:
          type: boolean
      - name: incognito
        in: query
        description: Filter events where incognito/private browsing was detected.
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEventsResponse'
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Identification:
      type: object
      properties:
        visitorId:
          type: string
          description: Stable unique identifier for the visitor.
        requestId:
          type: string
          description: Unique identifier of the identification event.
        linkedId:
          type: string
        timestamp:
          type: integer
          format: int64
          description: Time of the event as a Unix epoch (ms).
        time:
          type: string
          format: date-time
        url:
          type: string
        ip:
          type: string
        confidence:
          $ref: '#/components/schemas/Confidence'
        visitorFound:
          type: boolean
        incognito:
          type: boolean
        browserDetails:
          $ref: '#/components/schemas/BrowserDetails'
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. TokenRequired, RequestNotFound).
            message:
              type: string
              description: Human-readable error message.
    Confidence:
      type: object
      properties:
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
    EventsGetResponse:
      type: object
      properties:
        products:
          $ref: '#/components/schemas/Products'
    Products:
      type: object
      description: Container for identification and Smart Signal product results.
      properties:
        identification:
          $ref: '#/components/schemas/SignalResponseIdentification'
        botd:
          $ref: '#/components/schemas/SignalResponseBotd'
        ipInfo:
          type: object
        incognito:
          type: object
        vpn:
          type: object
        proxy:
          type: object
        tor:
          type: object
        tampering:
          type: object
        virtualMachine:
          type: object
        emulator:
          type: object
        velocity:
          type: object
    SignalResponseBotd:
      type: object
      properties:
        data:
          type: object
          properties:
            bot:
              type: object
              properties:
                result:
                  type: string
                  enum:
                  - notDetected
                  - good
                  - bad
    SignalResponseIdentification:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Identification'
    SearchEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventsGetResponse'
        paginationKey:
          type: string
    BrowserDetails:
      type: object
      properties:
        browserName:
          type: string
        browserMajorVersion:
          type: string
        browserFullVersion:
          type: string
        os:
          type: string
        osVersion:
          type: string
        device:
          type: string
        userAgent:
          type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Auth-API-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key