Fingerprint Server Python SDK

Fingerprint is a device intelligence platform offering industry-leading accuracy. The Fingerprint Server Python SDK is an easy way to interact with the Fingerprint Server API from your Python application. You can retrieve visitor history or individual identification events.

This Python package is automatically generated by the OpenAPI Generator project:

• API version: 4
• Package version: 9.9.0-rc.0
• Generator version: 7.19.0
• Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements

The following Python versions are supported:

• Python 3.9+

Installation & Usage

pip install

You can install the package directly from GitHub

pip install git+https://github.com/fingerprintjs/python-sdk.git

Or from the PyPI

pip install fingerprint_server_sdk

Then import the package:

import fingerprint_server_sdk

Getting Started

Please follow the installation procedure and then run the following:

import os

import fingerprint_server_sdk
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
# create an instance of the API class
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

Examples

Delete visitor data using visitorId:

import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

visitor_id = 'visitor_id_example'

try:
    api_instance.delete_visitor_data(visitor_id)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->delete_visitor_data: {e}'
    print(message)

To learn more, refer to example located in examples/delete_visitor_example.py.

Fetching event details for eventId:

import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

event_id = 'event_id_example'

try:
    events_response = api_instance.get_event(event_id)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->get_event: {e}'
    print(message)

To learn more, refer to example located in examples/get_event_example.py.

Search events with custom filters:

import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, SearchEventsBot, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

limit = 20
pagination_key = 'key_example'
visitor_id = 'VISITOR_ID'
bot = SearchEventsBot.GOOD
ip_address = '192.168.0.1/32'
linked_id = 'linked_id_example'
start = 1738687200000
end = 1738773600000
reverse = True
suspect = False

try:
    # Get events via search
    api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
    print(api_response)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->get_event: {e}'
    print(message)

To learn more, refer to example located in examples/search_events_example.py.

Update event for eventId:

import os

import fingerprint_server_sdk
from fingerprint_server_sdk import ApiException, EventUpdate, ErrorResponse
from fingerprint_server_sdk.configuration import Region

# Configure API key authorization and region
configuration = fingerprint_server_sdk.Configuration(
    api_key = os.environ["SECRET_API_KEY"],
    region = Region.US
)
api_instance = fingerprint_server_sdk.FingerprintApi(configuration)

event_id = 'event_id_example'
body = EventUpdate(linked_id='foo')
# body = EventUpdate(tags={'bar': 123})
# body = EventUpdate(suspect=True)
# body = EventUpdate(linked_id='foo', tags={'bar': 123}, suspect=False)

try:
    api_instance.update_event(event_id, body)
except ApiException as e:
    if e.body is not None:
        error_response = ErrorResponse.from_json(e.body)
        if error_response is not None:
            message = f"API request failed: {error_response.error.code} {error_response.error.message}"
        else:
            message = f"API request failed with unexpected error format: {e}"
    else:
        message = f'Exception when calling FingerprintApi->update_event: {e}'
    print(message)

To learn more, refer to example located in examples/update_event_example.py.

Sealed results

This SDK provides utility methods for decoding sealed results.

import base64
import os

from dotenv import load_dotenv

from fingerprint_server_sdk import unseal_event_response, DecryptionKey, DecryptionAlgorithm

load_dotenv()

sealed_result = base64.b64decode(os.environ["BASE64_SEALED_RESULT"])
key = base64.b64decode(os.environ["BASE64_KEY"])

try:
    event_response = unseal_event_response(sealed_result, [DecryptionKey(key, DecryptionAlgorithm['Aes256Gcm'])])
    print("\n\n\nEvent response: \n", event_response)
except Exception as e:
    print(f'Exception when calling unsealing events response: {e}\n')
    exit(1)

print("Unseal successful!")

exit(0)

To learn more, refer to example located in examples/sealed_results_example.py.

Webhook signature validation

This SDK provides utility method for verifying the HMAC signature of the incoming webhook request.

import os
from flask import Flask, request, jsonify
from fingerprint_server_sdk import WebhookValidation

app = Flask(__name__)

@app.route('/api/webhook', methods=['POST'])
def webhook_handler():
    try:
        # Retrieve the secret key from environment variables
        secret = os.getenv("WEBHOOK_SIGNATURE_SECRET")
        if not secret:
            return jsonify({"message": "Secret key is not configured."}), 400

        # Get the "fpjs-event-signature" header from the incoming request
        header = request.headers.get('fpjs-event-signature')
        if not header:
            return jsonify({"message": "Missing fpjs-event-signature header."}), 400

        # Read the raw body of the incoming request
        data = request.get_data()

        # Validate the webhook signature
        is_valid = WebhookValidation.is_valid_webhook_signature(header, data, secret)
        if not is_valid:
            return jsonify({"message": "Webhook signature is invalid."}), 403

        # Process the webhook data here
        return jsonify({"message": "Webhook received."}), 200

    except Exception as e:
        # Handle any unexpected errors
        return jsonify({"error": str(e)}), 500

if __name__ == '__main__':
    # Start the Flask application on the specified host and port
    app.run(host='0.0.0.0', port=5000)

To learn more, refer to example located in examples/webhook_signature_example.py.

Documentation for API Endpoints

All URIs are relative to https://api.fpjs.io/v4

Documentation For Models

• BotInfo
• BotInfoCategory
• BotInfoConfidence
• BotInfoIdentity
• BotResult
• BrowserDetails
• Canvas
• DeviceDetails
• Emoji
• Error
• ErrorCode
• ErrorResponse
• Event
• EventRuleAction
• EventRuleActionAllow
• EventRuleActionBlock
• EventSearch
• EventSource
• EventUpdate
• FontPreferences
• Geolocation
• GeolocationSubdivisionsInner
• IPBlockList
• IPInfo
• IPInfoV4
• IPInfoV6
• Identification
• IdentificationConfidence
• IncrementalIdentificationStatus
• Integration
• IntegrationSubintegration
• LabelsInner
• PluginsInner
• PluginsInnerMimeTypesInner
• Proximity
• ProxyConfidence
• ProxyDetails
• RareDevicePercentileBucket
• RawDeviceAttributes
• RequestHeaderModifications
• RuleActionHeaderField
• RuleActionType
• SDK
• SearchEventsBot
• SearchEventsBotInfo
• SearchEventsEndParameter
• SearchEventsIncrementalIdentificationStatus
• SearchEventsRareDevicePercentileBucket
• SearchEventsSdkPlatform
• SearchEventsSource
• SearchEventsStartParameter
• SearchEventsVpnConfidence
• SupplementaryIDHighRecall
• TamperingConfidence
• TamperingDetails
• TouchSupport
• Velocity
• VelocityData
• VpnConfidence
• VpnMethods
• WebGlBasics
• WebGlExtensions

Documentation for sealed results

• SealedResults
• DecryptionKey

Support

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.

License

This project is licensed under the MIT License.