Face Search 1:N (Crops)

Endpoint

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

Performs 1:N face search using cropped face images instead of full frames. Use this when you only have tight face crops (for example after detection or from a low-resolution pipeline). Validation requires a higher minimum score than the standard Face Search endpoint (min_score 0.5–1 here vs 0.2–1 on /search).

Headers

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

Params

Name	Type	Required	Description
images	string[]	Yes	Base64 face crops and/or HTTPS image URLs (same subject; small crops work best).
collection_id	string	No	Restrict search to this collection.
max_results	number	No	Maximum results to return.
min_score	number	Yes	Match threshold 0.5–1.
search_mode	string	Yes	One of FAST or ACCURATE.

Request

Node.js

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

async function run() {
  const res = await fetch("https://api.verifik.co/v2/face-recognition/search/crops", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      images: ["<base64-small>"],
      collection_id: "<collection_id>",
      min_score: 0.7,
      search_mode: "FAST",
      max_results: 10,
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/face-recognition/search/crops");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "images" => ["<base64-small>"],
    "collection_id" => "<collection_id>",
    "min_score" => 0.7,
    "search_mode" => "ACCURATE",
    "max_results" => 10
]);
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/search/crops"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}"
}
payload = {
    "images": ["<base64-small>"],
    "collection_id": "<collection_id>",
    "min_score": 0.7,
    "search_mode": "FAST",
    "max_results": 10
}
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{}{
        "images":          []string{"<base64-small>"},
        "collection_id":   "<collection_id>",
        "min_score":       0.7,
        "search_mode":     "ACCURATE",
        "max_results":     10,
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/face-recognition/search/crops", 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

Shape matches Face Search (1:N): data is an array of candidate persons ranked by similarity.

200

{
  "id": "SC01",
  "data": [
    {
      "id": "person_id",
      "name": "John Doe",
      "score": 0.91,
      "thumbnails": [{ "id": "thumb_id", "thumbnail": "<base64>" }]
    }
  ],
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "January 16, 2024 3:44 PM"
  }
}

401

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

403

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

409

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

500

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

Notes

• Prefer tight face crops; this path is tuned for small regions (often around 120×120 or similar). Very large full-frame images are a better fit for /v2/face-recognition/search.
• Each string in images may be raw base64 or an HTTPS URL to an image; URLs are fetched and converted server-side.
• Use ACCURATE when you need higher precision; use FAST for lower latency.

Related documentation

1. Face Search (1:N) — Standard gallery search with full face images; min_score allows 0.2–1.
2. Face Search 1:N (Live) — Liveness on the probe image, then 1:N search.
3. Face Search 1:N (Active User) — 1:N search for active-session flows without liveness on the probe.
4. Verify Face (1:1) — Match crops or images against a known enrolled person id.
5. Face Detection — Detect faces in an image to obtain crops before calling search.
6. List all persons — Inspect enrolled persons and metadata for your client.