This page contains the API Reference for the JavaScript agent's get() function or its equivalent in your frontend library. The function is NOT exported directly from the @fingerprintjs/fingerprintjs-pro NPM package. Instead, it is a method on the agent instance returned by the load() function.

Call the get() function to send identification requests to Fingerprint and get the browser's visitor ID.

If you are just getting started with Fingerprint, we recommend reading the following guides first:

If you encountered errors using the JavaScript agent, see the Error handling reference.

get() options

extendedResult

Required: no
Default: false
Type: boolean

Two types of responses are supported: default and extended. You don't need to pass any parameters to get the default response. Extended result format includes geolocation, incognito mode, and other information. It can be requested by setting the extendedResult parameter to true. See more details about the responses, see get() response.

products

Required: no
Default: (depends on the API key)
Type: string[]
Since: v3.7.0

As of JS Agent version 3.9.3, this option has been deprecated and will likely be removed in the next major version.

You can enable or disable Fingerprint products that will handle this request. Using this option does not affect billing in any way.

linkedId

Required: no
Default: undefined
Type: string
Constraint: the number of characters must not exceed 256

linkedId is a way of linking the current analysis event with a custom identifier. This will allow you to filter visit information when using the Server API.

// Making an API call
var orderId = 3936532456
fp.get({ linkedId: orderId })
// linkedId will be saved with this event and will be available to be queried later.

If the information stored in linkedId is not available on the client when the event happens, it is possible to set it through our Update Event Server API.

To learn more about tag and linkedId use cases, see Linking and tagging information.

tag

Required: no
Default: undefined
Type: any simple value or an object (not arrays)
Constraint: the size must not exceed 16KB

tag is a customer-provided value or an object that is saved with the identification event and returned back to you in a webhook message or Server API response. You can use tag to associate the visit event with other information you have about the visitor.

You can use any simple value (string, number, boolean) or an object. An object is saved as provided. A simple value (for example 123) is returned wrapped in an object like this: { "tag": 123 }.

Examples of using the tag option:

fp.get({ tag: 123 });
fp.get({ tag: "signup" });
fp.get({ tag: { id: "456", location: { city: "Atlanta", country: "US" }});

What comes back in a webhook or Server API response:

{
  "visitorId": "nTxJ28Gt4CegeAwdWELL",
  "tag": { "tag": 123 },
  // ...
},
{
  "visitorId": "nTxJ28Gt4CegeAwdWELL",
  "tag": { "tag": "signup" },
  // ...
},
{
  "visitorId": "nTxJ28Gt4CegeAwdWELL",
  "tag": {
    "id": "456",
    "location": {
      "city": "Atlanta",
      "country": "US"
    }
  }
  // ...
}

If the information stored in tag is not available on the client when the event happens, it is possible to set it through our Update Event Server API.

To learn more about tag and linkedId use cases, see Linking and tagging information.

timeout

Required: no
Default: 10000
Type: number

Client timeout controls the total time (both client-side and server-side) that any analysis event can run. It doesn't include the time when the page is in the background (not visible) because the browser may suspend the analysis process during that time. By default, it's 10 seconds. You can set the client-side timeout in milliseconds using the timeout option. Example usage:

// A timeout of 20 seconds
// An example of the client-side timeout handling
try {
  const result = await fp.get({ timeout: 20000 })
  // ...
} catch (error) {
  if (error.message === FingerprintJS.ERROR_CLIENT_TIMEOUT) {
    console.log("A timeout of 20 seconds exceeded")
  }
}

🚧

Note that setting a low timeout (less than 2000ms) could increase identification failures on weaker devices with slower internet connections.

get() response

fp.get() returns a promise that resolves to an object. The object format depends on the extendedResult option. The format summary:

await fp.get()
// response:
{
  "requestId": "8nbmT18x79m54PQ0GvPq",
  "visitorId": "2JGu1Z4d2J4IqiyzO3i4",
  "visitorFound": true,
  "confidence": { "score": 0.995 }
}
await fp.get({ extendedResult: true })
// response:
{
  "requestId": "8nbmT18x79m54PQ0GvPq",
  "visitorId": "2JGu1Z4d2J4IqiyzO3i4",
  "visitorFound": true,
  "confidence": { "score": 0.995 },
  "ip": "185.230.125.20",
  // ipLocation: This field is deprecated and will not return a result for applications created after January 23rd, 2024. 
  // See IP Geolocation (https://dev.fingerprint.com/docs/smart-signals-overview#ip-geolocation) for a replacement 
  // available in our Smart Signals product.
  "ipLocation": { 
    "accuracyRadius": 10,
    "latitude": 47.3925,
    "longitude": 8.4546,
    "postalCode": "8010",
    "timezone": "Europe/Zurich",
    "city": {
      "name": "Zurich"
    },
    "continent": {
      "code": "EU",
      "name": "Europe"
    },
    "country": {
      "code": "CH",
      "name": "Switzerland"
    },
    "subdivisions": [
      {
        "isoCode": "ZH",
        "name": "Zurich"
      }
    ]
  },
  "browserName": "Chrome",
  "browserVersion": "75.0.3770",
  "os": "Mac OS X",
  "osVersion": "10.14.5",
  "device": "Other",
  "incognito": false,
  "firstSeenAt": {
    "global": "2022-03-16T11:26:45.362Z",
    "subscription": "2022-03-16T11:31:01.101Z"
  },
  "lastSeenAt": {
    "global": "2022-03-16T11:28:34.023Z",
    "subscription": null
  }
}

When the identification product is disabled, all the fields except requestId are replaced with default values.

Response fields:

requestId

Required: yes
Type: string

The request identifier is unique for every request. Use it to request information about a specific identification request from the Server API.

visitorId

Required: yes
Type: string

The browser identifier (or device identifier for mobile platforms)

The field will contain an empty string if the visitor can't be identified, for example, a search bot. If the identification product is disabled, a dummy value is used.

visitorFound

Required: yes
Type: boolean

If true, it means this visitor has already appeared in and identified for your application.

If false, it means this is the first time the visitor has appeared in your application.

You can use firstSeenAt to get a precise timestamp of the browser's very first visit to your application. On the other hand, lastSeenAt represents this browser's most recent visit to your application.

If the identification product is disabled, a dummy value is used.

confidence

Required: yes
Type: { score: number, comment?: string }

A number between 0 and 1 that represents the probability of accurate identification. The higher the number, the higher the chance of the visitor identifier being true. To learn more about how Fingerprint calculates this value, see Understanding your confidence score.

sealedResult

Required: no
Type: string (base64-encoded binary data)

See more details in the Sealed Client Results guide. The field will miss if Sealed Client Results are disabled or unavailable for another reason.

zeroTrust

Required: no
Type: { hiddenFields: string[], comment?: string }

See more details in the Zero Trust Mode guide.

incognito

Only when extendedResult is true
Required: yes
Type: boolean

Whether the visitor is in incognito/private mode.

If the identification product is disabled, a dummy value is used.

browserName

Only when extendedResult is true
Required: yes
Type: string

Browser name. Examples: 'Safari', 'Chrome'.

If the identification product is disabled, a dummy value is used.

browserVersion

Only when extendedResult is true
Required: yes
Type: string

Browser version. Example: '78.0.3904'.

If the identification product is disabled, a dummy value is used.

device

Only when extendedResult is true
Required: yes
Type: string

Device. For desktop/laptop devices, the value will be "Other". Example: 'Samsung SM-J330F'.

If the identification product is disabled, a dummy value is used.

ip

Only when extendedResult is true
Required: yes
Type: string

IP address. Only IPv4 addresses are returned.

If the identification product is disabled, a dummy value is used.

ipLocation

Only when extendedResult is true
Required: no
Type: Object

This field is deprecated and will not return a result for applications created after January 23rd, 2024. See IP Geolocation for a replacement available in our Smart Signals product.

Can be empty for anonymous proxies. The value type:

{
  accuracyRadius?: number
  latitude?: number
  longitude?: number
  timezone?: string
  postalCode?: string
  city?: {
    name: string
  }
  subdivisions?: {
    isoCode: string
    name: string
  }[]
  country?: {
    code: string
    name: string
  }
  continent?: {
    code: string
    name: string
  }
}

If the identification product is disabled, the value is absent.

os

Only when extendedResult is true
Required: yes
Type: string

Operating system name. Examples: 'Mac OS X', 'Android'.

If the identification product is disabled, a dummy value is used.

osVersion

Only when extendedResult is true
Required: yes
Type: string

Operating system version. Examples: '10.13.6'.

firstSeenAt

Only when extendedResult is true
Required: yes
Type: { subscription: string | null, global: string | null }

The very first time a browser appeared in your application. See Visitor Footprint Timestamps for more information.

If the identification product is disabled, a dummy value is used.

lastSeenAt

Only when extendedResult is true
Required: yes
Type: { subscription: string | null, global: string | null }

The most recent instance (i.e. before this request) the browser visited your application. See Visitor Footprint Timestamps for more information.

If the identification product is disabled, a dummy value is used.