openapi: 3.0.1
info:
  title: Fingerprint Server API
  description: >-
    The Fingerprint Server API lets you get, search, update, and delete
    identification Events and Visitors in a server environment. Each event
    carries device attributes and the enabled Smart Signals (bot, VPN, proxy,
    Tor, IP blocklist, tampering, virtual machine, incognito, emulator, root,
    jailbreak, Frida, cloned app, factory reset, velocity). Requests are
    authenticated with the `Auth-API-Key` header carrying your workspace Secret
    API Key. The API is served from regional hosts; use the host that matches
    your workspace region (Global, EU, or Asia). The product also exposes a
    Related Visitors endpoint and Webhooks that POST the same event payload to a
    configured endpoint.
  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: Events
    description: Get and update individual identification events.
  - name: Event Search
    description: Search identification events with filters.
  - name: Visitors
    description: Get visit history and delete visitor data.
  - name: Related Visitors
    description: Find visitorIds likely belonging to the same person.
paths:
  /events/{request_id}:
    get:
      tags:
        - Events
      operationId: getEvent
      summary: Get event by request ID
      description: >-
        Get a detailed analysis of an individual identification event,
        including all Smart Signals enabled for your workspace.
      parameters:
        - name: request_id
          in: path
          required: true
          description: The unique identifier (requestId) of the identification event.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsGetResponse'
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Event not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Events
      operationId: updateEvent
      summary: Update an event with a given request ID
      description: >-
        Update an event with a linkedId, one or more tags, or a suspect flag to
        support your decision-making and labeling workflows.
      parameters:
        - name: request_id
          in: path
          required: true
          description: The unique identifier (requestId) of the identification event.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventUpdateRequest'
      responses:
        '200':
          description: OK. Event updated.
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Event not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /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'
  /visitors/{visitor_id}:
    get:
      tags:
        - Visitors
      operationId: getVisits
      summary: Get visits by visitor ID
      description: >-
        Get the visit history for a single visitorId, with pagination and
        time-range filtering.
      parameters:
        - name: visitor_id
          in: path
          required: true
          description: Unique identifier of the visitor.
          schema:
            type: string
        - name: request_id
          in: query
          description: Filter visits by a single requestId.
          schema:
            type: string
        - name: linked_id
          in: query
          description: Filter visits by linkedId.
          schema:
            type: string
        - name: limit
          in: query
          description: Limit the number of visits returned.
          schema:
            type: integer
            format: int32
        - name: pagination_key
          in: query
          description: Cursor used to fetch the next page of visits.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Visitor not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Visitors
      operationId: deleteVisitorData
      summary: Delete data by visitor ID
      description: >-
        Delete all data associated with the specified visitorId. Used for
        privacy and data-subject (GDPR/CCPA) deletion requests. The deletion is
        asynchronous and irreversible.
      parameters:
        - name: visitor_id
          in: path
          required: true
          description: Unique identifier of the visitor whose data should be deleted.
          schema:
            type: string
      responses:
        '200':
          description: OK. Deletion request accepted.
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Visitor not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /related-visitors:
    get:
      tags:
        - Related Visitors
      operationId: getRelatedVisitors
      summary: Get related visitors
      description: >-
        Get a list of visitorIds that are likely to belong to the same person
        as the provided visitorId, across browsers and incognito sessions.
      parameters:
        - name: visitor_id
          in: query
          required: true
          description: The visitorId for which related visitors are requested.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelatedVisitorsResponse'
        '403':
          description: Forbidden - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Auth-API-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
  schemas:
    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
    SignalResponseIdentification:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Identification'
    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'
    Confidence:
      type: object
      properties:
        score:
          type: number
          format: float
          minimum: 0
          maximum: 1
    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
    SignalResponseBotd:
      type: object
      properties:
        data:
          type: object
          properties:
            bot:
              type: object
              properties:
                result:
                  type: string
                  enum: [notDetected, good, bad]
    SearchEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/EventsGetResponse'
        paginationKey:
          type: string
    Response:
      type: object
      properties:
        visitorId:
          type: string
        visits:
          type: array
          items:
            $ref: '#/components/schemas/Visit'
        lastTimestamp:
          type: integer
          format: int64
        paginationKey:
          type: string
    Visit:
      type: object
      properties:
        requestId:
          type: string
        incognito:
          type: boolean
        linkedId:
          type: string
        timestamp:
          type: integer
          format: int64
        time:
          type: string
          format: date-time
        url:
          type: string
        ip:
          type: string
        confidence:
          $ref: '#/components/schemas/Confidence'
        visitorFound:
          type: boolean
    RelatedVisitorsResponse:
      type: object
      properties:
        relatedVisitors:
          type: array
          items:
            type: object
            properties:
              visitorId:
                type: string
    EventUpdateRequest:
      type: object
      properties:
        linkedId:
          type: string
        tag:
          type: object
          additionalProperties: true
        suspect:
          type: boolean
    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.