Crear una Persona con Detección de Vida

Endpoint

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

Crea o actualiza una persona después de comprobar liveness en la(s) imagen(es) enviadas, ejecutar una búsqueda por similitud (min_score, search_mode) y la deduplicación asociada al collection_id. En producción, si ya existe un duplicado en esa colección, la API puede responder 409:duplicated_person.

Encabezados

Nombre	Valor
Content-Type	application/json
Authorization	Bearer <token>

Parámetros (cuerpo JSON)

Nombre	Tipo	Requerido	Descripción
name	string	Sí	Nombre completo (el servidor elimina dígitos del nombre)
images	string[]	Sí	Imágenes faciales en Base64 (sin prefijo data:)
gender	string	Sí	M o F
date_of_birth	string	Sí	Fecha de nacimiento según validación OpenCV (típicamente YYYY-MM-DD)
nationality	string	No	Nacionalidad opcional
collection_id	string	Sí	_id único de la colección de destino (y ámbito de duplicados)
liveness_min_score	number	Sí	Puntuación mínima de liveness entre 0.5 y 1
min_score	number	Sí	Puntuación mínima para la búsqueda interna, entre 0.5 y 1
search_mode	string	Sí	FAST o ACCURATE

Solicitud

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)
}

Respuesta

200

{
  "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": "…"
}

401/403

{
  "message": "Access forbidden",
  "code": "Forbidden"
}

409

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

400

{
  "error": "Invalid request"
}

Notas

• No uses POST .../persons/liveness: la ruta correcta es search-live-face bajo persons.
• collection_id: un solo _id de colección (este flujo no acepta un arreglo collections en el cuerpo).
• Fallo de liveness: puede devolverse 409 con mensaje que contiene liveness_failed.
• Firma: las respuestas correctas pueden incluir signature según la configuración del middleware.