get function

This page contains the API reference for the JavaScript agent get() function or its equivalent in your frontend library. The function is not exported directly from the @fingerprint/agent NPM package. Instead, it is a method on the agent instance returned by the start() 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:

• Install the JavaScript agent
• Identify visitors

get() options

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.

Add a custom identifier to an analysis event

// 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:

JavaScript

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:

JSON

{
  "visitor_id": "nTxJ28Gt4CegeAwdWELL",
  "tag": { "tag": 123 },
  // ...
}

{
  "visitor_id": "nTxJ28Gt4CegeAwdWELL",
  "tag": { "tag": "signup" },
  // ...
}

{
  "visitor_id": "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:

JavaScript

// 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.code === '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 a result object. Only event_id and sealed_result are always present. Every other field is conditional on either workspace configuration or the options passed to start() (see the field reference below). The format summary:

JavaScript

const result = await fp.get()
// response (fully-populated shape):
{
  event_id: "8nbmT18x79m54PQ0GvPq",        // always present
  visitor_id: "2JGu1Z4d2J4IqiyzO3i4",      // absent when Zero Trust mode is enabled
  suspect_score: 10,                        // present only when Smart Signals are enabled
  sealed_result: null,                      // BinaryOutput when Sealed Client Results are enabled, else null
  cache_hit: false                          // present only when `cache` was configured in start()
}

// Serialize the sealed_result before transport if needed:
const sealedResultBase64 = result.sealed_result?.base64()

Three fields may be undefined and need explicit guards before use:

• visitor_id and suspect_score depend on workspace configuration (Zero Trust mode and Smart Signals respectively).
• cache_hit depends on the start() configuration (the cache option), not workspace settings.

Use optional chaining (result.visitor_id?.startsWith(...)) or explicit if checks before relying on any of them.

get() response fields

event_id

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.

visitor_id

Required: no Type: string

The browser identifier (or device identifier for mobile platforms).

In most configurations the field is always present. It contains 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.

The field is omitted from the response (undefined) when the workspace has Zero Trust mode enabled. In that case the backend does not return a visitor identifier to the client and you should retrieve it from the Server API using event_id.

sealed_result

Required: yes Type: BinaryOutput | null

The field is always present in the response. It carries a BinaryOutput wrapper around the sealed payload when Sealed Client Results are enabled for the workspace, and null otherwise. See the Sealed Client Results guide for setup details.

BinaryOutput has three serialization methods:

• base64(): string
• byteArray(): Uint8Array
• blob(): Blob

The BinaryOutput interface is referenced inside the public GetResult type but is not exported as a top-level name from the package. If you need it for typing your own code, access it via NonNullable<GetResult['sealed_result']> (since GetResult['sealed_result'] itself is BinaryOutput | null).

cache_hit

Required: no Type: boolean

The value is included if the cache configuration was used during the start() call and is:

• true if the get() response was retrieved from the cache.
• false if the get() response came directly from the Fingerprint backend.

The field is undefined when the cache option was not set in start().

suspect_score

Required: no Type: number

Shows the Suspect Score value of the event when the workspace has Smart Signals enabled. The field is undefined otherwise.