Liveness Score

Endpoint

POST https://api.verifik.co/v2/face-recognition/liveness-score

Returns a liveness score and pass/fail outcome for a single face image using Verifik’s presentation attack detection (PAD) stack. Use this when you need the score-focused liveness contract.

API stability: This is a production public endpoint. Request and response contracts follow Verifik’s standard API change and deprecation policy. Billing uses the same AppFeature as POST /v2/face-recognition/liveness.

vs /liveness

	POST .../liveness	POST .../liveness-score
Use	Standard liveness detection	Score-focused liveness response
Billing	Liveness AppFeature	Same liveness AppFeature (path rewritten for credits)
Body	os, image, optional collection_id, liveness_min_score	Same

Presentation attack detection (PAD)

Verifik’s face liveness (including this endpoint and /liveness) uses our biometric stack with presentation attack detection (PAD). Liveness is iBeta Level 2 certified and aligned with ISO 30107 Level 1 and Level 2. It is designed to detect common spoofing vectors such as printed photos, video replay, and 3D masks, using a single-image liveness check.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Params

Name	Type	Required	Description
os	string	Yes	Origin of capture. Suggested: DESKTOP, IOS, ANDROID.
image	string	Yes	Base64 image data (data URI or raw base64). If an https URL is provided, it will be downloaded and converted internally.
collection_id	string	No	Optional collection to associate with the liveness attempt.
liveness_min_score	number	No	Threshold for pass/fail. Default: 0.6.

Request

Node.js

const fetch = require("node-fetch");

async function run() {
  const res = await fetch("https://api.verifik.co/v2/face-recognition/liveness-score", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      os: "DESKTOP",
      image: "<base64 or https url>",
      liveness_min_score: 0.6,
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/face-recognition/liveness-score");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "os" => "DESKTOP",
    "image" => "<base64 or https url>",
    "liveness_min_score" => 0.6
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import os, requests

url = "https://api.verifik.co/v2/face-recognition/liveness-score"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}"
}
payload = {
    "os": "DESKTOP",
    "image": "<base64 or https url>",
    "liveness_min_score": 0.6
}
r = requests.post(url, json=payload, headers=headers)
print(r.json())

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload := map[string]interface{}{
        "os": "DESKTOP",
        "image": "<base64 or https url>",
        "liveness_min_score": 0.6,
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/face-recognition/liveness-score", bytes.NewBuffer(b))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+os.Getenv("VERIFIK_TOKEN"))
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    var out map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&out)
    fmt.Println(out)
}

Response

200

{
  "id": "JQ4RM",
  "data": {
    "passed": true,
    "min_score": 0.6,
    "liveness_score": 0.98
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "January 16, 2024 3:44 PM"
  }
}

401/403

{
  "message": "Authentication required",
  "code": "UNAUTHORIZED"
}

or

{
  "message": "token_expired",
  "code": "FORBIDDEN"
}

409

{
  "message": "\"os\" is required",
  "code": "MissingParameter"
}

500

{
  "message": "internal_error",
  "code": "ERROR"
}

Notes

• Ensure Authorization: Bearer <token> is present; otherwise you will receive 401/403.
• image may be base64 or an https URL. If URL, the service fetches and converts it internally.
• Pass/fail is determined by liveness_score > min_score (default min_score is 0.6, configurable via liveness_min_score).
• Credits are charged against the same feature as /liveness.
• Optional collection_id is validated for the authenticated client.