get function

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-reference#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 workspace.

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

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

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 workspaces 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 workspace. 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 workspace. See Visitor Footprint Timestamps for more information.

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

get() options

extendedResult

products

linkedId

tag

timeout

🚧

get() response

requestId

visitorId

visitorFound

confidence

sealedResult

zeroTrust

incognito

browserName

browserVersion

device

ip

ipLocation

os

osVersion

firstSeenAt

lastSeenAt

`get()` options

`extendedResult`

`products`

`linkedId`

`tag`

`timeout`

`get()` response

`requestId`

`visitorId`

`visitorFound`

`confidence`

`sealedResult`

`zeroTrust`

`incognito`

`browserName`

`browserVersion`

`device`

`ip`

`ipLocation`

`os`

`osVersion`

`firstSeenAt`

`lastSeenAt`