Skip to main content

​
How to install

Add @fingerprint/node-sdk as a dependency to your application via npm, yarn, or pnpm. 
npm install @fingerprint/node-sdk

yarn add @fingerprint/node-sdk

pnpm add @fingerprint/node-sdk
Initialize the client instance and use it to make API requests. You need to specify your secret API key and region.
TypeScript
import { FingerprintServerApiClient, Region } from "@fingerprint/node-sdk";

const client = new FingerprintServerApiClient({
  apiKey: "SECRET_API_KEY",
  region: Region.Global,
});

// Search events for a specific visitor
client.searchEvents({ visitor_id: "VISITOR_ID" }).then((events) => {
  console.log(events);
});

// Get a specific identification event
client.getEvent("EVENT_ID").then((event) => {
  console.log(event);
});

​
Migration guide for Node SDK v7

Version 7 migrates the SDK from Server API v3 to v4. This is a breaking change. This section summarizes the most important changes from previous versions.

​
Package rename

The package changed from @fingerprintjs/fingerprintjs-pro-server-api to @fingerprint/node-sdk. 
npm install @fingerprintjs/fingerprintjs-pro-server-api
npm install @fingerprint/node-sdk

yarn add @fingerprintjs/fingerprintjs-pro-server-api
yarn add @fingerprint/node-sdk

pnpm add @fingerprintjs/fingerprintjs-pro-server-api
pnpm add @fingerprint/node-sdk
TypeScript
import { FingerprintJsServerApiClient } from "@fingerprintjs/fingerprintjs-pro-server-api"; 
import { FingerprintServerApiClient } from "@fingerprint/node-sdk";

​
Client construction

The client class was renamed from FingerprintJsServerApiClient to FingerprintServerApiClient, and the authenticationMode option was removed.
TypeScript
const client = new FingerprintJsServerApiClient({ 
const client = new FingerprintServerApiClient({ 
  apiKey: "SECRET_API_KEY",
  region: Region.Global,
  authenticationMode: AuthenticationMode.AuthHeader, 
});

​
Get an event

requestId is now called the event ID, and the event data structure is flatter. Response fields are now snake_case, and identification and Smart Signals data moved from products.<signal>.data to the top level.
TypeScript
const event = await client.getEvent("EVENT_ID");
console.log(event.products.identification.data.visitorId); 
console.log(event.identification.visitor_id);

​
getVisits replaced by searchEvents

getVisits() and getRelatedVisitors() have been removed. Use searchEvents with visitor_id to get the events for a visitor.
TypeScript
const history = await client.getVisits("VISITOR_ID", { limit: 10 }); 
const history = await client.searchEvents({ visitor_id: "VISITOR_ID", limit: 10 });

​
Update an event

The updateEvent parameter order changed from (body, eventId) to (eventId, body), and the tag field was renamed to tags.
TypeScript
await client.updateEvent( 
  { 
    tag: { key: "value" }, 
    linkedId: "new_linked_id", 
    suspect: false, 
  }, 
  "EVENT_ID"
); 
await client.updateEvent("EVENT_ID", { 
  tags: { key: "value" }, 
  linked_id: "new_linked_id", 
  suspect: false, 
});

​
Handling sealed client results from a v3 JavaScript agent

Node SDK v7 will fail to deserialize the decrypted payload of a sealed client result sent by a v3 JavaScript agent into an Event because the payload is an EventsGetResponse (i.e., the v3 event format), not an Event. To upgrade to Node SDK v7 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails. To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the sealed client results guide. Both unsealEventsResponse and client.getEvent return an Event, so the fallback returns the same type.
TypeScript
import { DecryptionKey, Event, FingerprintServerApiClient, UnsealAggregateError, unsealEventsResponse } from "@fingerprint/node-sdk";

async function getEvent(
  client: FingerprintServerApiClient,
  sealedResult: Buffer,
  eventId: string,
  keys: DecryptionKey[]
): Promise<Event> {
  try {
    // Try to unseal the payload locally first.
    return await unsealEventsResponse(sealedResult, keys);
  } catch (error) {
    if ( !(error instanceof UnsealAggregateError) ) {
      // Deserialization failed. Fall back to the Server API using
      // the event ID sent alongside the sealed client results.
      console.log("Could not unseal result, falling back to Server API:", error);
      return client.getEvent(eventId);
    }

    // Re-throw unsealing errors
    throw error;
  }
}

​
Documentation

You can find the full documentation in the official GitHub repository.