Class FingerprintJsServerApiClient

constructor

• new FingerprintJsServerApiClient(options): FingerprintJsServerApiClient

• FingerprintJS server API client used to fetch data from FingerprintJS

  Parameters

  • options: Readonly<Options>

    Options for FingerprintJS server API client

  Returns FingerprintJsServerApiClient

Readonly apiKey

Readonly authenticationMode

Readonly region

deleteVisitorData

• deleteVisitorData(visitorId): Promise<void>

• Delete data by visitor ID Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. All delete requests are queued: Recent data (10 days or newer) belonging to the specified visitor will be deleted within 24 hours. * Data from older (11 days or more) identification events will be deleted after 90 days. If you are interested in using this API, please contact our support team to activate it for you. Otherwise, you will receive a 403.

  Parameters

  • visitorId: string

    The visitor ID you want to delete.*

  Returns Promise<void>

  Promise that resolves when the deletion request is successfully queued

  Example

  client
    .deleteVisitorData('<visitorId>')
    .then(() => {
      // Data deletion request was successfully queued
    })
    .catch((error) => {
      if (isDeleteVisitorError(error)) {
        console.log(error.statusCode, error.message)
      }
    })
  Copy

getEvent

• getEvent(requestId): Promise<{
      error?: {
          code: "Failed" | "TooManyRequests";
          message: string;
      };
      products: {
          botd?: {
              data?: {
                  bot: {
                      result: "notDetected" | "good" | "bad";
                      type?: string;
                  };
                  ip: string;
                  linkedId?: string;
                  requestId: string;
                  time: string;
                  url: string;
                  userAgent: string;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          clonedApp?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          developerTools?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          emulator?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          factoryReset?: {
              data?: {
                  time: string;
                  timestamp: number;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          frida?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          highActivity?: {
              data?: {
                  dailyRequests?: number;
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          identification?: {
              data?: {
                  browserDetails: {
                      botProbability?: number;
                      browserFullVersion: string;
                      browserMajorVersion: string;
                      browserName: string;
                      device: string;
                      os: string;
                      osVersion: string;
                      userAgent: string;
                  };
                  confidence?: {
                      revision?: string;
                      score: number;
                  };
                  firstSeenAt: {
                      global: null | string;
                      subscription: null | string;
                  };
                  incognito: boolean;
                  ip: string;
                  ipLocation?: {
                      accuracyRadius?: number;
                      city?: {
                          name?: ...;
                      };
                      continent?: {
                          code: ...;
                          name: ...;
                      };
                      country?: {
                          code: ...;
                          name: ...;
                      };
                      latitude?: number;
                      longitude?: number;
                      postalCode?: string;
                      subdivisions?: (...)[];
                      timezone?: string;
                  };
                  lastSeenAt: {
                      global: null | string;
                      subscription: null | string;
                  };
                  linkedId?: string;
                  requestId: string;
                  tag: {
                      [key: string]: unknown;
                  };
                  time: string;
                  timestamp: number;
                  url: string;
                  visitorFound: boolean;
                  visitorId: string;
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          incognito?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          ipBlocklist?: {
              data?: {
                  details: {
                      attackSource: boolean;
                      emailSpam: boolean;
                  };
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          ipInfo?: {
              data?: {
                  v4?: {
                      address: string;
                      asn?: {
                          asn: ...;
                          name?: ...;
                          network: ...;
                      };
                      datacenter?: {
                          name?: ...;
                          result: ...;
                      };
                      geolocation: {
                          accuracyRadius?: (...) | (...);
                          city?: (...) | (...);
                          continent?: (...) | (...);
                          country?: (...) | (...);
                          latitude?: (...) | (...);
                          longitude?: (...) | (...);
                          postalCode?: (...) | (...);
                          subdivisions?: (...) | (...);
                          timezone?: (...) | (...);
                      };
                  };
                  v6?: {
                      address: string;
                      asn?: {
                          asn: ...;
                          name?: ...;
                          network: ...;
                      };
                      datacenter?: {
                          name?: ...;
                          result: ...;
                      };
                      geolocation: {
                          accuracyRadius?: (...) | (...);
                          city?: (...) | (...);
                          continent?: (...) | (...);
                          country?: (...) | (...);
                          latitude?: (...) | (...);
                          longitude?: (...) | (...);
                          postalCode?: (...) | (...);
                          subdivisions?: (...) | (...);
                          timezone?: (...) | (...);
                      };
                  };
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          jailbroken?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          locationSpoofing?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          privacySettings?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          proxy?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          rawDeviceAttributes?: {
              data?: {
                  [key: string]: {
                      error?: {
                          message: string;
                          name: string;
                      };
                      value?: unknown;
                  };
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          remoteControl?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          rootApps?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          suspectScore?: {
              data?: {
                  result: number;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          tampering?: {
              data?: {
                  anomalyScore: number;
                  result: boolean;
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          tor?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          velocity?: {
              data?: {
                  distinctCountry: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
                  distinctIp: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
                  distinctLinkedId: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
                  events: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          virtualMachine?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          vpn?: {
              data?: {
                  methods: {
                      auxiliaryMobile: boolean;
                      osMismatch: boolean;
                      publicVPN: boolean;
                      timezoneMismatch: boolean;
                  };
                  originCountry?: string;
                  originTimezone: string;
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
      };
  }>

• Retrieves a specific identification event with the information from each activated product — Identification and all active Smart signals.

  Parameters

  • requestId: string

    identifier of the event

  Returns Promise<{
      error?: {
          code: "Failed" | "TooManyRequests";
          message: string;
      };
      products: {
          botd?: {
              data?: {
                  bot: {
                      result: "notDetected" | "good" | "bad";
                      type?: string;
                  };
                  ip: string;
                  linkedId?: string;
                  requestId: string;
                  time: string;
                  url: string;
                  userAgent: string;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          clonedApp?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          developerTools?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          emulator?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          factoryReset?: {
              data?: {
                  time: string;
                  timestamp: number;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          frida?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          highActivity?: {
              data?: {
                  dailyRequests?: number;
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          identification?: {
              data?: {
                  browserDetails: {
                      botProbability?: number;
                      browserFullVersion: string;
                      browserMajorVersion: string;
                      browserName: string;
                      device: string;
                      os: string;
                      osVersion: string;
                      userAgent: string;
                  };
                  confidence?: {
                      revision?: string;
                      score: number;
                  };
                  firstSeenAt: {
                      global: null | string;
                      subscription: null | string;
                  };
                  incognito: boolean;
                  ip: string;
                  ipLocation?: {
                      accuracyRadius?: number;
                      city?: {
                          name?: ...;
                      };
                      continent?: {
                          code: ...;
                          name: ...;
                      };
                      country?: {
                          code: ...;
                          name: ...;
                      };
                      latitude?: number;
                      longitude?: number;
                      postalCode?: string;
                      subdivisions?: (...)[];
                      timezone?: string;
                  };
                  lastSeenAt: {
                      global: null | string;
                      subscription: null | string;
                  };
                  linkedId?: string;
                  requestId: string;
                  tag: {
                      [key: string]: unknown;
                  };
                  time: string;
                  timestamp: number;
                  url: string;
                  visitorFound: boolean;
                  visitorId: string;
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          incognito?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          ipBlocklist?: {
              data?: {
                  details: {
                      attackSource: boolean;
                      emailSpam: boolean;
                  };
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          ipInfo?: {
              data?: {
                  v4?: {
                      address: string;
                      asn?: {
                          asn: ...;
                          name?: ...;
                          network: ...;
                      };
                      datacenter?: {
                          name?: ...;
                          result: ...;
                      };
                      geolocation: {
                          accuracyRadius?: (...) | (...);
                          city?: (...) | (...);
                          continent?: (...) | (...);
                          country?: (...) | (...);
                          latitude?: (...) | (...);
                          longitude?: (...) | (...);
                          postalCode?: (...) | (...);
                          subdivisions?: (...) | (...);
                          timezone?: (...) | (...);
                      };
                  };
                  v6?: {
                      address: string;
                      asn?: {
                          asn: ...;
                          name?: ...;
                          network: ...;
                      };
                      datacenter?: {
                          name?: ...;
                          result: ...;
                      };
                      geolocation: {
                          accuracyRadius?: (...) | (...);
                          city?: (...) | (...);
                          continent?: (...) | (...);
                          country?: (...) | (...);
                          latitude?: (...) | (...);
                          longitude?: (...) | (...);
                          postalCode?: (...) | (...);
                          subdivisions?: (...) | (...);
                          timezone?: (...) | (...);
                      };
                  };
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          jailbroken?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          locationSpoofing?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          privacySettings?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          proxy?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          rawDeviceAttributes?: {
              data?: {
                  [key: string]: {
                      error?: {
                          message: string;
                          name: string;
                      };
                      value?: unknown;
                  };
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          remoteControl?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          rootApps?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          suspectScore?: {
              data?: {
                  result: number;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          tampering?: {
              data?: {
                  anomalyScore: number;
                  result: boolean;
              };
              error?: {
                  code: "429 Too Many Requests" | "Failed";
                  message: string;
              };
          };
          tor?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          velocity?: {
              data?: {
                  distinctCountry: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
                  distinctIp: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
                  distinctLinkedId: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
                  events: {
                      intervals?: {
                          1h: number;
                          24h?: (...) | (...);
                          5m: number;
                      };
                  };
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          virtualMachine?: {
              data?: {
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
          vpn?: {
              data?: {
                  methods: {
                      auxiliaryMobile: boolean;
                      osMismatch: boolean;
                      publicVPN: boolean;
                      timezoneMismatch: boolean;
                  };
                  originCountry?: string;
                  originTimezone: string;
                  result: boolean;
              };
              error?: {
                  code: "Failed" | "TooManyRequests";
                  message: string;
              };
          };
      };
  }>

  • promise with event response. For more information, see the Server API documentation.

  Example

  client
   .getEvent('<requestId>')
   .then((result) => console.log(result))
   .catch((err) => {
     if (isEventError(err)) {
       // You can also access the raw response
       console.log(err.response)
       console.log(`error ${err.statusCode}: `, err.message)
     } else {
       console.log('unknown error: ', err)
     }
   })
  Copy

getVisitorHistory

• getVisitorHistory(visitorId, filter?): Promise<{
      lastTimestamp?: number;
      paginationKey?: string;
      visitorId: string;
      visits: {
          browserDetails: {
              botProbability?: number;
              browserFullVersion: string;
              browserMajorVersion: string;
              browserName: string;
              device: string;
              os: string;
              osVersion: string;
              userAgent: string;
          };
          confidence?: {
              revision?: string;
              score: number;
          };
          firstSeenAt: {
              global: null | string;
              subscription: null | string;
          };
          incognito: boolean;
          ip: string;
          ipLocation?: {
              accuracyRadius?: number;
              city?: {
                  name?: string;
              };
              continent?: {
                  code: string;
                  name: string;
              };
              country?: {
                  code: string;
                  name: string;
              };
              latitude?: number;
              longitude?: number;
              postalCode?: string;
              subdivisions?: {
                  isoCode?: string;
                  name?: string;
              }[];
              timezone?: string;
          };
          lastSeenAt: {
              global: null | string;
              subscription: null | string;
          };
          linkedId?: string;
          requestId: string;
          tag: {
              [key: string]: unknown;
          };
          time: string;
          timestamp: number;
          url: string;
          visitorFound: boolean;
      }[];
  }>

• Retrieves event history for the specific visitor using the given filter, returns a promise with visitor history response.

  Parameters

  • visitorId: string

    Identifier of the visitor
  • Optional filter: {
        before?: number;
        limit?: number;
        linked_id?: string;
        paginationKey?: string;
        request_id?: string;
    }

    Visitor history filter

    • Optional before?: number

      Description

      ⚠️ Deprecated pagination method, please use paginationKey instead. Timestamp (in milliseconds since epoch) used to paginate results.

    • Optional limit?: number

      Description

      Limit scanned results.

      For performance reasons, the API first scans some number of events before filtering them. Use limit to specify how many events are scanned before they are filtered by requestId or linkedId. Results are always returned sorted by the timestamp (most recent first). By default, the most recent 100 visits are scanned, the maximum is 500.

    • Optional linked_id?: string

      Description

      Filter visits by your custom identifier.

      You can use linkedId to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use this linked_id parameter to retrieve all events associated with your custom identifier.

    • Optional paginationKey?: string

      Description

      Use paginationKey to get the next page of results.

      When more results are available (e.g., you requested 200 results using limit parameter, but a total of 600 results are available), the paginationKey top-level attribute is added to the response. The key corresponds to the requestId of the last returned event. In the following request, use that value in the paginationKey parameter to get the next page of results:

      1. First request, returning most recent 200 events: GET api-base-url/visitors/:visitorId?limit=200
      2. Use response.paginationKey to get the next page of results: GET api-base-url/visitors/:visitorId?limit=200&paginationKey=1683900801733.Ogvu1j

      Pagination happens during scanning and before filtering, so you can get less visits than the limit you specified with more available on the next page. When there are no more results available for scanning, the paginationKey attribute is not returned.

    • Optional request_id?: string

      Description

      Filter visits by requestId.

      Every identification request has a unique identifier associated with it called requestId. This identifier is returned to the client in the identification result. When you filter visits by requestId, only one visit will be returned.

  Returns Promise<{
      lastTimestamp?: number;
      paginationKey?: string;
      visitorId: string;
      visits: {
          browserDetails: {
              botProbability?: number;
              browserFullVersion: string;
              browserMajorVersion: string;
              browserName: string;
              device: string;
              os: string;
              osVersion: string;
              userAgent: string;
          };
          confidence?: {
              revision?: string;
              score: number;
          };
          firstSeenAt: {
              global: null | string;
              subscription: null | string;
          };
          incognito: boolean;
          ip: string;
          ipLocation?: {
              accuracyRadius?: number;
              city?: {
                  name?: string;
              };
              continent?: {
                  code: string;
                  name: string;
              };
              country?: {
                  code: string;
                  name: string;
              };
              latitude?: number;
              longitude?: number;
              postalCode?: string;
              subdivisions?: {
                  isoCode?: string;
                  name?: string;
              }[];
              timezone?: string;
          };
          lastSeenAt: {
              global: null | string;
              subscription: null | string;
          };
          linkedId?: string;
          requestId: string;
          tag: {
              [key: string]: unknown;
          };
          time: string;
          timestamp: number;
          url: string;
          visitorFound: boolean;
      }[];
  }>

  Example

  client
    .getVisitorHistory('<visitorId>', { limit: 1 })
    .then((visitorHistory) => {
      console.log(visitorHistory)
    })
    .catch((error) => {
      if (isVisitorsError(error)) {
        console.log(error.statusCode, error.message)
        if (error.status === 429) {
          retryLater(error.retryAfter) // Needs to be implemented on your side
        }
      }
    })
  Copy

updateEvent

• updateEvent(body, requestId): Promise<void>

• Update an event with a given request ID

  Parameters

  • body: {
        linkedId?: string;
        suspect?: boolean;
        tag?: Record<string, never>;
    }

    Data to update the event with.

    • Optional linkedId?: string

      Description

      LinkedID value to assign to the existing event

    • Optional suspect?: boolean

      Description

      Suspect flag indicating observed suspicious or fraudulent event

    • Optional tag?: Record<string, never>

      Description

      Full tag value to be set to the existing event. Replaces any existing tag payload completely.

  • requestId: string

    The unique event identifier.

  Returns Promise<void>

  Description

  Change information in existing events specified by requestId or flag suspicious events.

  When an event is created, it is assigned linkedId and tag submitted through the JS agent parameters. This information might not be available on the client so the Server API allows for updating the attributes after the fact.

  Warning It's not possible to update events older than 10 days.

  Example

  const body = {
   linkedId: 'linked_id',
   suspect: false,
  }
  
  client
    .updateEvent(body, '<requestId>')
    .then(() => {
      // Event was successfully updated
    })
    .catch((error) => {
      if (isUpdateEventError(error)) {
        console.log(error.statusCode, error.message)
      }
    })
  Copy