Skip to content

Facephi Finger Service

Fingerprint REST API for template extraction and 1:1 authentication.

Important Compatibility Notice

IMPORTANT - BREAKING CHANGE (2.0.0)

From version 2.0.0 onward, the fingerprint operation endpoints are not backward compatible with 1.x.x:

  • POST /api/v1/finger/extract
  • POST /api/v1/finger/authenticate

Legacy public routes POST /api/v1/finger/create-template and POST /api/v1/finger/verify are not available in 2.0.0.

Request and response payload formats changed. Integrations built for 1.x.x must migrate to the 2.0.0 public contract before upgrading.

Overview

Facephi Finger Service exposes a public API under /api/v1/finger/ with fingerprint-oriented field names such as image, position, fingerTemplate, authStatus, and similarity.

For requests that provide fingerprint images (image, image1, image2), supported formats are wsq, bmp, png, jpg, and jp2.

The service provides:

  • Fingerprint template extraction
  • 1:1 fingerprint authentication
  • Usage counters through GET /api/v1/finger/metrics
  • Health, version, and runtime configuration endpoints

Public Contract

Extract

Supported image formats for image: wsq, bmp, png, jpg, jp2.

Request:

{
  "image": "<base64_fingerprint_image>",
  "position": "RightIndex",
  "options": {
    "dpi": 500,
    "scanType": "Plain",
    "includeQuality": true
  }
}

Response:

{
  "fingerTemplate": "<base64_generated_template>",
  "position": "RightIndex",
  "scanType": "Plain",
  "quality": 88,
  "qualityDetails": {
    "nfiq2": 79.0,
    "nfiq": 1.0,
    "score": 88.0
  },
  "sdkDuration": 123,
  "queueDuration": 2
}

Metrics

Response:

{
  "usageCountersEnabled": true,
  "extractCount": 12,
  "authenticateCount": 7,
  "totalCount": 19
}

Notes:

  • usageCountersEnabled depends on license metadata key ActivateUsageCounters.
  • extractCount and authenticateCount are mapped to license meter attributes FingerExtractCounter and FingerAuthenticateCounter.
  • totalCount is computed as extractCount + authenticateCount.

Authenticate

Supported image formats for image1 and image2: wsq, bmp, png, jpg, jp2.

Request using templates:

{
  "fingerTemplate1": "<base64_probe_template>",
  "fingerTemplate2": "<base64_gallery_template>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}

Request using images:

{
  "image1": "<base64_probe_image>",
  "image2": "<base64_gallery_image>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}

Response:

{
  "authStatus": "Positive",
  "similarity": 84.65,
  "sdkDuration": 131,
  "queueDuration": 1
}

API Endpoints

Endpoint Method Purpose
/api/v1/finger/extract POST Extract a fingerprint template from a public payload
/api/v1/finger/authenticate POST Execute public 1:1 fingerprint authentication
/api/v1/finger/metrics GET Retrieve usage counter report
/api/v1/finger/version GET Service version and license status
/api/v1/finger/health GET Service health and readiness check
/api/v1/finger/config GET/POST Retrieve or update runtime configuration

Quick Start

Requirements

Component Requirement
OS Linux x86_64
Runtime Docker recommended
License Valid Facephi license file

Deploy with Docker

docker run -d \
  -p 6982:6982 \
  -v /path/to/license:/app/license \
  -v /path/to/config:/app/config \
  --name finger-service \
  facephicorp.jfrog.io/docker-core-pro-fphi/facephi-finger-service:2.1.0

Verify Deployment

curl http://localhost:6982/api/v1/finger/health
curl http://localhost:6982/api/v1/finger/version

Typical responses:

{ "message": "Healthy" }

{ "message": "2.1.0 Copyright (c) 2026 FacePhi Biometria. All rights reserved." }

Configuration

Create /app/config/config.json:

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}

Documentation

Vendor Abstraction Note

Public documentation and payloads intentionally keep the processing runtime abstracted. Integrations must rely only on the documented Facephi API contract.

Support

For licensing and technical support, contact your Facephi representative.