Create a Person with Liveness

Endpoint

POST https://api.verifik.co/v2/face-recognition/persons/search-live-face

Creates or updates a person after liveness checks on the submitted face image(s), a similarity search against your index (min_score, search_mode), and deduplication scoped to the target collection_id. If a duplicate is found in that collection (in production), the API may return 409:duplicated_person.

Headers

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

Params

Name	Type	Required	Description
name	string	Yes	Full name (digits are stripped server-side)
images	string[]	Yes	Base64 face images (raw base64, not data URLs)
gender	string	Yes	M or F
date_of_birth	string	Yes	Date of birth in the format required by OpenCV validation (typically YYYY-MM-DD)
nationality	string	No	Optional nationality
collection_id	string	Yes	Unique _id of the collection to enroll into (and to check for duplicates)
liveness_min_score	number	Yes	Minimum liveness score, between 0.5 and 1
min_score	number	Yes	Minimum face match score for the internal search, between 0.5 and 1
search_mode	string	Yes	FAST or ACCURATE

Request

Node.js

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

const collectionId = "65b9592267cc4f096dbe743d";

async function run() {
  const res = await fetch(
    "https://api.verifik.co/v2/face-recognition/persons/search-live-face",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
      },
      body: JSON.stringify({
        name: "Jane Doe",
        gender: "F",
        date_of_birth: "1990-01-15",
        nationality: "CO",
        collection_id: collectionId,
        liveness_min_score: 0.65,
        min_score: 0.8,
        search_mode: "FAST",
        images: ["<base64>", "<base64>"],
      }),
    }
  );
  console.log(await res.json());
}

run();

PHP

<?php
$collectionId = "65b9592267cc4f096dbe743d";
$ch = curl_init("https://api.verifik.co/v2/face-recognition/persons/search-live-face");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "name" => "Jane Doe",
    "gender" => "F",
    "date_of_birth" => "1990-01-15",
    "nationality" => "CO",
    "collection_id" => $collectionId,
    "liveness_min_score" => 0.65,
    "min_score" => 0.8,
    "search_mode" => "FAST",
    "images" => ["<base64>", "<base64>"],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import os, requests

collection_id = "65b9592267cc4f096dbe743d"
url = "https://api.verifik.co/v2/face-recognition/persons/search-live-face"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}",
}
payload = {
    "name": "Jane Doe",
    "gender": "F",
    "date_of_birth": "1990-01-15",
    "nationality": "CO",
    "collection_id": collection_id,
    "liveness_min_score": 0.65,
    "min_score": 0.8,
    "search_mode": "FAST",
    "images": ["<base64>", "<base64>"],
}
r = requests.post(url, json=payload, headers=headers)
print(r.json())

Go

package main

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

func main() {
    collectionId := "65b9592267cc4f096dbe743d"
    payload, _ := json.Marshal(map[string]interface{}{
        "name":                 "Jane Doe",
        "gender":               "F",
        "date_of_birth":        "1990-01-15",
        "nationality":          "CO",
        "collection_id":        collectionId,
        "liveness_min_score":   0.65,
        "min_score":            0.8,
        "search_mode":          "FAST",
        "images":               []string{"<base64>", "<base64>"},
    })
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/face-recognition/persons/search-live-face", bytes.NewReader(payload))
    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": "…",
  "data": {
    "_id": "65175da13e81e4fabc12345",
    "name": "Jane Doe",
    "gender": "F",
    "date_of_birth": "1990-01-15T00:00:00.000Z",
    "collections": ["65b9592267cc4f096dbe743d"],
    "deleted": false,
    "createdAt": "2024-01-30T20:16:34.841Z",
    "updatedAt": "2024-01-30T20:16:34.841Z"
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "…"
  }
}

401/403

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

or

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

409

{
  "message": "409:duplicated_person",
  "code": "ERROR"
}

or validation / liveness:

{
  "message": "liveness_failed (or other validation message)",
  "code": "ERROR"
}

412

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

500

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

Notes

• Not POST /v2/face-recognition/persons/liveness — the correct route is search-live-face under persons.
• collection_id: single collection _id (this flow does not accept a collections array in the request body).
• Liveness failure: sub-scores may surface as 409 with a message containing liveness_failed.
• liveness_min_score and min_score must stay between 0.5 and 1; search_mode must be FAST or ACCURATE.
• images must be raw base64 (no data: URL); undersized payloads may return 412 only_images_in_base64.