Fingerprint is a device intelligence platform offering 99.5% accurate visitor identification.
The Fingerprint Server Node SDK is an easy way to interact with the Fingerprint Server API from your Node application. You can retrieve visitor history or individual identification events.
TypeScript support:
- TypeScript 4.5.5 or higher
Supported runtimes:
-
Node.js 18 LTS or higher (we support all Node LTS releases before end-of-life).
-
Deno and Bun might work but are not actively tested.
-
"Edge" runtimes might work with some modifications but are not actively tested.
See "edge" runtimes compatibility This SDK can be made compatible with JavaScript "edge" runtimes that do not support all Node APIs, for example, Vercel Edge Runtime, or Cloudflare Workers.
To make it work, replace the SDK's built-in
fetch
function (which relies on Node APIs) with the runtime's nativefetch
function. Pass the function into the constructor with proper binding:const client = new FingerprintJsServerApiClient({ region: Region.EU, apiKey: apiKey, fetch: fetch.bind(globalThis), });
Install the package using your favorite package manager:
-
NPM:
npm i @fingerprintjs/fingerprintjs-pro-server-api
-
Yarn:
yarn add @fingerprintjs/fingerprintjs-pro-server-api
-
pnpm:
pnpm i @fingerprintjs/fingerprintjs-pro-server-api
Initialize the client instance and use it to make API requests. You need to specify your Fingerprint Secret API key and the region of your Fingerprint application.
import { FingerprintJsServerApiClient, Region } from '@fingerprintjs/fingerprintjs-pro-server-api';
const client = new FingerprintJsServerApiClient({
apiKey: '<SECRET_API_KEY>',
region: Region.Global,
});
// Get visit history of a specific visitor
client.getVisitorHistory('<visitorId>').then((visitorHistory) => {
console.log(visitorHistory);
});
// Get a specific identification event
client.getEvent('<requestId>').then((event) => {
console.log(event);
});
When handling Webhooks coming from Fingerprint, you can cast the payload as the built-in VisitWebhook
type:
const visit = visitWebhookBody as unknown as VisitWebhook;
The getEvent
and getVisitorHistory
methods can throw EventError
and VisitorsError
.
You can use the provided isVisitorsError
and isEventError
type guards to narrow down error types:
import { isVisitorsError, isEventError } from '@fingerprintjs/fingerprintjs-pro-server-api';
client
.getVisitorHistory('<visitorId>', filter)
.then((result) => console.log(result))
.catch((err) => {
if (isVisitorsError(err)) {
if (err.code === 429) {
// VisitorsError429 type
retryLater(err.retryAfter); // this function needs to be implemented on your side
} else {
console.log('error: ', err.error);
}
} else {
console.log('unknown error: ', err);
}
});
client
.getEvent('<requestId>')
.then((result) => console.log(result))
.catch((err) => {
if (isEventError(err)) {
console.log(`error ${err.code}: `, err.error.message);
} else {
console.log('unknown error: ', err);
}
});
This SDK provides utility methods for decoding sealed results. To learn more, refer to example located in example/sealedResults.js.
Creates an instance of the client.
const client = new FingerprintJsServerApiClient({ region: Region.EU, apiKey: '<api_key>' });
-
region: Region
- a region of the server, possible values:Region.EU
,Region.AP
, orRegion.Global
-
apiKey: string
- secret API key from the FingerprintJS dashboard -
fetch?: typeof fetch
- optional implementation offetch
function (defaults tonode-fetch
)
Retrieves a specific identification event with the information from each activated product — Identification and all active Smart signals.
client
.getEvent('<requestId>')
.then((eventInfo) => {
console.log(eventInfo);
})
.catch((error) => {
if (error.status === 403 || error.status === 404) {
console.log(error.code, error.message);
}
});
-
requestId: string
- identifier of the event
-
Promise<EventResponse>
- promise with event response
For more information, see the Server API documentation.
{
"products": {
"identification": {
"data": {
"visitorId": "Ibk1527CUFmcnjLwIs4A9",
"requestId": "0KSh65EnVoB85JBmloQK",
"incognito": true,
"linkedId": "somelinkedId",
"time": "2019-05-21T16:40:13Z",
"timestamp": 1582299576512,
"url": "https://www.example.com/login",
"ip": "61.127.217.15",
"ipLocation": {
"accuracyRadius": 10,
"latitude": 49.982,
"longitude": 36.2566,
"postalCode": "61202",
"timezone": "Europe/Dusseldorf",
"city": {
"name": "Dusseldorf"
},
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "DE",
"name": "Germany"
},
"subdivisions": [
{
"isoCode": "63",
"name": "North Rhine-Westphalia"
}
]
},
"browserDetails": {
"browserName": "Chrome",
"browserMajorVersion": "74",
"browserFullVersion": "74.0.3729",
"os": "Windows",
"osVersion": "7",
"device": "Other",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...."
},
"confidence": {
"score": 0.97
},
"visitorFound": true,
"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
}
}
},
"botd": {
"data": {
"bot": {
"result": "notDetected"
},
"url": "https://example.com/login",
"ip": "61.127.217.15",
"time": "2019-05-21T16:40:13Z"
}
}
}
}
Retrieves event history for the specific visitor using the given filter, returns a promise with visitor history response.
client
.getVisitorHistory('<visitorId>', filter)
.then((visitorHistory) => {
console.log(visitorHistory);
})
.catch((error) => {
if (error.status === 403) {
console.log(error.error);
} else if (error.status === 429) {
retryLater(error.retryAfter); // this function needs to be implemented on your side
}
});
-
visitorId: string
- identifier of the visitor -
filter?: VisitorHistoryFilter
- visitor history filter (details below)
Filter for querying the visitors Server API endpoint.
Usage:
const filter = {
request_id: '<request_id>',
linked_id: '<linked_id>',
limit: 5,
paginationKey: '<paginationKey>',
};
Properties:
-
request_id: string
- filter visits byrequestId
.Every identification request has a unique identifier associated with it called
requestId
. This identifier is returned to the client in the identification result. When you filter visits byrequestId
, only one visit will be returned. -
linked_id: string
- filter visits by your custom identifier.You can use
linkedId
to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use thislinked_id
parameter to retrieve all events associated with your custom identifier. -
limit: number
- limit scanned results.For performance reasons, the API first scans some number of events before filtering them. Use
limit
to specify how many events are scanned before they are filtered byrequestId
orlinkedId
. Results are always returned sorted by the timestamp (most recent first). By default, the most recent 100 visits are scanned, the maximum is 500. -
paginationKey: string
- usepaginationKey
to get the next page of results.When more results are available (e.g., you requested 200 results using
limit
parameter, but a total of 600 results are available), thepaginationKey
top-level attribute is added to the response. The key corresponds to therequestId
of the last returned event. In the following request, use that value in thepaginationKey
parameter to get the next page of results:- First request, returning most recent 200 events:
GET api-base-url/visitors/:visitorId?limit=200
- Use
response.paginationKey
to get the next page of results:GET api-base-url/visitors/:visitorId?limit=200&paginationKey=1683900801733.Ogvu1j
Pagination happens during scanning and before filtering, so you can get less visits than the
limit
you specified with more available on the next page. When there are no more results available for scanning, thepaginationKey
attribute is not returned. - First request, returning most recent 200 events:
-
Promise<VisitorsResponse>
- promise with the visitor history response
For more information, see the Server API documentation.
{
"visitorId": "Ibk1527CUFmcnjLwIs4A9",
"visits": [
{
"requestId": "0KSh65EnVoB85JBmloQK",
"incognito": true,
"linkedId": "somelinkedId",
"time": "2019-05-21T16:40:13Z",
// timestamp of the event with millisecond precision
"timestamp": 1582299576512,
"url": "https://www.example.com/login",
"ip": "61.127.217.15",
"ipLocation": {
"accuracyRadius": 10,
"latitude": 49.982,
"longitude": 36.2566,
"postalCode": "61202",
"timezone": "Europe/Dusseldorf",
"city": {
"name": "Dusseldorf"
},
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "DE",
"name": "Germany"
},
"subdivisions": [
{
"isoCode": "63",
"name": "North Rhine-Westphalia"
}
]
},
"browserDetails": {
"browserName": "Chrome",
"browserMajorVersion": "74",
"browserFullVersion": "74.0.3729",
"os": "Windows",
"osVersion": "7",
"device": "Other",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...."
},
"confidence": {
"score": 0.97
},
"visitorFound": true,
"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
}
}
],
// optional, if more results are available for pagination.
"lastTimestamp": 1582299576512
}
Decrypts the sealed events response with provided keys.
import { unsealEventsResponse, DecryptionAlgorithm } from '@fingerprintjs/fingerprintjs-pro-server-api';
unsealEventsResponse(sealedData, [
{
key: Buffer.from('p2PA7MGy5tx56cnyJaFZMr96BCFwZeHjZV2EqMvTq53=', 'base64'),
algorithm: DecryptionAlgorithm.Aes256Gcm,
},
]).then(result => {
console.log(result);
});
-
sealedData: Buffer
- sealed data to decrypt -
decryptionKeys: DecryptionKey[]
- array of decryption keys. The SDK will try to decrypt the result with each key until it succeeds.
const decryptionKey = {
key: Buffer.from('aW52YWxpZA==', 'base64'),
algorithm: DecryptionAlgorithm.Aes256Gcm,
}
Properties:
-
key: Buffer
- key generated in dashboard that will be used to decrypt sealed result -
algorithm: DecryptionAlgorithm
- algorithm to use for decryption. Currently onlyAes256Gcm
value is supported.
-
Promise<EventResponse>
- promise with the decrypted event response
To report problems, ask questions or provide feedback, please use Issues. If you need private support, you can email us at oss-support@fingerprint.com.
This project is licensed under the MIT license.