Online Face Verification API

Compare two face images from your backend and receive the documented dist, sim, and same_person signals. Your application decides how to use the result. For a user-facing browser flow with live capture, see online face verification.

OPEN FACEIO Console

Connect to the FACEIO Console to create applications, manage APIs, and configure webhooks for enrollment, authentication, and Facial ID events.

How Verification Fits Into Your Flow

Choose the integration path that matches your architecture and user interaction model.

FACEIO offers two paths to face verification depending on where the check needs to happen in your system. The browser flow uses fio.js for camera interaction and live capture. The REST API is for backend services that already have two face images to compare. For a browser popup that combines ID document capture with a live selfie, see FACEIO ID Match. For conceptual context, compare with online face verification workflows.

Browser-Based SDK

Appropriate when verification happens at an interaction point where the user is physically present.

fio.js handles camera UI and live capture
Ideal for KYC onboarding and account recovery
Backend verifies the payload and decides

Direct REST API

Appropriate for backend-only workflows where images are already available to your server.

Direct /faceverify endpoint calls
Useful for backend image comparison and ID checks
No live browser session required

API Inputs & Verification Signals

The faceverify endpoint accepts a POST request with your API key and two images, either Base64 data URIs or publicly accessible URLs. Each image must contain a single face. If your input contains multiple faces, extract the target face before sending the request.

Request Inputs

Parameter	Description
`key`	Your application's REST API key. Send this value from your backend only; do not expose it in client-side code.
`src`	The source image as a Base64 data URI or publicly accessible URL. Typically an ID document photograph or a previously verified selfie.
`target`	The target image to compare against the source, as a Base64 data URI or publicly accessible URL.

Response Outputs

Field	Type	Description
`status`	Integer	HTTP status code; `200` indicates the request was processed successfully.
`same_person`	Boolean	`true` if the two images match, `false` if they do not.
`dist`	Float	Distance metric between 0 and 1. A higher value indicates a stronger match.
`sim`	Float	Cosine similarity score between the two facial feature vectors.

Implementation Tip: For sensitive workflows, use the dist and sim values together to calibrate your match threshold in your decision logic, rather than relying solely on the binary same_person boolean. Align thresholds with your documented policy and review Security Best Practices.

Implementation Patterns

1. Web Onboarding with Browser Capture (KYC)

In a KYC-style flow, the user completes a live facial capture in the browser during signup. Your backend supplies that capture and a reference image from an earlier ID document scan, then calls faceverify to compare the two. The response is one technical input to your customer-controlled onboarding, retry, or manual-review policy; it does not authenticate the document or complete KYC or AML checks.

                         backend_verify.py 
                      

                        # Python - backend verification call
import requests, base64

def encode_image(path):
    with open(path, 'rb') as f:
        return 'data:image/jpeg;base64,' + base64.b64encode(f.read()).decode()

payload = {
    'key': 'YOUR_API_KEY',
    'src': encode_image('id_document.jpg'),   # reference
    'target': encode_image('live_selfie.jpg') # live capture
}

result = requests.post('https://api.faceio.net/faceverify', json=payload).json()

# Example Response
# {
#     "status": 200,
#     "same_person": true,
#     "dist": 0.97,
#     "sim": 0.94
# }
                      

2. Backend Decisioning with Confidence Thresholds

Your backend can read the documented response fields and route the request according to thresholds and review rules defined for your use case. Test those rules with your own data and requirements rather than treating a sample threshold as universal. This pattern can contribute to fintech and eKYC controls.

High Confidence

Apply the continuation policy defined and tested by your organization.

Borderline Confidence

Route low-confidence results to a manual review queue instead of auto-rejecting.

Low Confidence

Retry, request another factor, or route to review according to your policy.

3. Account Recovery Without Credentials

The user requests access to an account and submits a fresh selfie through a recovery page. Your backend compares it with the reference image retained for that account.

Treat the face-match result as one recovery signal. Your backend should also apply the account, device, session, retry, and support controls required before restoring access.

Security & Privacy Best Practices

The face verification API processes sensitive face images transiently for each comparison. Your application remains responsible for notices, consent, input validation, its own retention policy, and final account decisions. Use the following practices for every integration:

Keep your API key private.
The faceverify endpoint must be called from your backend only. Your API key authenticates the request and must not appear in browser-side code, mobile bundles, public repositories, analytics, or logs.
Always route through your backend.
Verification requests made directly from the browser bypass your server-side validation layer and cannot be trusted.
Minimize image retention.
FACEIO processes both images in memory and discards them after the result is generated. Your application should keep face images only when your workflow, policy, and legal basis require it.
Log verification outcomes for your audit trail.
If you need an audit trail, your backend should record the outcome, timestamp, request context, and relevant internal identifiers when the response is received. Avoid logging raw images or API keys.
Provide notices and obtain consent where required.
Your onboarding or recovery flow should explain why face verification is used, what data is processed, and how users can request deletion or fallback access. Review Privacy Best Practices and the Trust Center.

Conclusion

The FACEIO Face Verification API gives your backend a clean, callable way to compare two face images. You provide the images and decision threshold; the API returns the verification signals, and your application logic controls the final decision. For a live browser capture flow with liveness checks, use online face verification. For document scan and selfie matching in one widget, use ID Match. Next steps: review Developer Guides, the FACEVERIFY endpoint, and Security Best Practices.

Related Guides

Connect the Face Verification API

Create a FACEIO app, keep the REST API key on your backend, and use the official endpoint reference to compare source and target images from your identity workflow.

Open FACEIO Console REST API Reference

Backend-Only API Key

Transient Processing

Policy-Led Integration