> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Server SDK

> The [Fingerprint Server Node SDK](https://github.com/fingerprintjs/node-sdk) is an easy way to interact with our Server API from your Node application. You can retrieve visitor history or individual identification events. View our [Node Server SDK quickstart](/docs/node-server-quickstart) for a step-by-step guide to get started.

## How to install

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

<CodeGroup>
  ```bash npm theme={"theme":"github-dark-dimmed"}
  npm install @fingerprint/node-sdk
  ```

  ```bash yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprint/node-sdk
  ```

  ```bash pnpm theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprint/node-sdk
  ```
</CodeGroup>

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
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`.

<CodeGroup>
  ```bash npm theme={"theme":"github-dark-dimmed"}
  npm install @fingerprintjs/fingerprintjs-pro-server-api # [!code --]
  npm install @fingerprint/node-sdk # [!code ++]
  ```

  ```bash yarn theme={"theme":"github-dark-dimmed"}
  yarn add @fingerprintjs/fingerprintjs-pro-server-api # [!code --]
  yarn add @fingerprint/node-sdk # [!code ++]
  ```

  ```bash pnpm theme={"theme":"github-dark-dimmed"}
  pnpm add @fingerprintjs/fingerprintjs-pro-server-api # [!code --]
  pnpm add @fingerprint/node-sdk # [!code ++]
  ```
</CodeGroup>

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
import { FingerprintJsServerApiClient } from "@fingerprintjs/fingerprintjs-pro-server-api"; // [!code --]
import { FingerprintServerApiClient } from "@fingerprint/node-sdk"; // [!code ++]
```

### Client construction

The client class was renamed from `FingerprintJsServerApiClient` to `FingerprintServerApiClient`, and the `authenticationMode` option was removed.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
const client = new FingerprintJsServerApiClient({ // [!code --]
const client = new FingerprintServerApiClient({ // [!code ++]
  apiKey: "SECRET_API_KEY",
  region: Region.Global,
  authenticationMode: AuthenticationMode.AuthHeader, // [!code --]
});
```

### 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 TypeScript theme={"theme":"github-dark-dimmed"}
const event = await client.getEvent("EVENT_ID");
console.log(event.products.identification.data.visitorId); // [!code --]
console.log(event.identification.visitor_id); // [!code ++]
```

### `getVisits` replaced by `searchEvents`

`getVisits()` and `getRelatedVisitors()` have been removed. Use `searchEvents` with `visitor_id` to get the events for a visitor.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
const history = await client.getVisits("VISITOR_ID", { limit: 10 }); // [!code --]
const history = await client.searchEvents({ visitor_id: "VISITOR_ID", limit: 10 }); // [!code ++]
```

### Update an event

The `updateEvent` parameter order changed from `(body, eventId)` to `(eventId, body)`, and the `tag` field was renamed to `tags`.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
await client.updateEvent( // [!code --]
  { // [!code --]
    tag: { key: "value" }, // [!code --]
    linkedId: "new_linked_id", // [!code --]
    suspect: false, // [!code --]
  }, // [!code --]
  "EVENT_ID" // [!code --]
); // [!code --]
await client.updateEvent("EVENT_ID", { // [!code ++]
  tags: { key: "value" }, // [!code ++]
  linked_id: "new_linked_id", // [!code ++]
  suspect: false, // [!code ++]
}); // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

Node SDK v7 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) 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](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Both `unsealEventsResponse` and `client.getEvent` return an `Event`, so the fallback returns the same type.

```typescript TypeScript theme={"theme":"github-dark-dimmed"}
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](https://github.com/fingerprintjs/node-sdk).