List All Persons

Endpoint

GET https://api.verifik.co/v2/face-recognition/persons

Returns persons stored in Verifik for your project. Supports pagination, filters, and optional population of related collections or client data.

Headers

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

Params

Name	Type	Required	Description
page	number	No	Page number (default: 1).
limit	number	No	Page size (default: 10, max: 100).
collection	string	No	Filter by collection ID.
status	string	No	One of active, inactive, pending.
populates[]	string[]	No	Related data to include: collections, client. Repeat the query key or pass an array per your HTTP client.

Request

Node.js

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

async function run() {
  const params = new URLSearchParams({ page: "1", limit: "10", status: "active" });
  params.append("populates[]", "collections");

  const res = await fetch(`https://api.verifik.co/v2/face-recognition/persons?${params}`, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
  });
  console.log(await res.json());
}

run();

PHP

<?php
$base = http_build_query([
    "page" => 1,
    "limit" => 10,
    "status" => "active",
]);
$url = "https://api.verifik.co/v2/face-recognition/persons?" . $base . "&populates[]=collections";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN"),
]);
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/persons"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}",
}
params = {"page": 1, "limit": 10, "status": "active", "populates[]": "collections"}
r = requests.get(url, headers=headers, params=params)
print(r.json())

Go

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    url := "https://api.verifik.co/v2/face-recognition/persons?page=1&limit=10&status=active&populates[]=collections"
    req, _ := http.NewRequest("GET", url, nil)
    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()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Response

200

{
  "id": "…",
  "data": [
    {
      "_id": "person_123456789",
      "name": "John Doe",
      "gender": "M",
      "date_of_birth": { "year": 1990, "month": 1, "day": 15 },
      "nationality": "US",
      "images": ["<base64>", "<base64>"],
      "collections": [
        {
          "_id": "collection_123456789",
          "name": "VIP Customers",
          "description": "High-value customers"
        }
      ],
      "notes": "VIP customer",
      "client": "client_123456789",
      "status": "active",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "pages": 1
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "…"
  }
}

401/403

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

or

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

409

{
  "message": "Invalid query parameters",
  "code": "INVALID_PARAMETERS"
}

500

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

Notes

• Typical responses use the Verifik envelope (id, data, signature); list payloads may also include pagination at the top level—confirm the exact shape in your environment.
• limit is capped at 100; use page to walk large result sets.
• Use populates[] when you need embedded collections or client instead of raw IDs only.
• Each item in data follows The Person Object (fields may vary with population and API version).