Create a Person

Endpoint

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

Creates a new person in the facial recognition system. Provide at least a name and images (base64). You can set gender, date of birth, nationality, collections (Mongo _id or collection code strings, depending on your integration), and notes.

Headers

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

Params

Name	Type	Required	Description
name	string	Yes	Full name of the person.
images	string[]	Yes	1–3 raw base64 face images (no data: URL prefix). Sending more than one pose (front + slight profile + another light) makes enrollment more robust.
gender	string	No	M or F.
date_of_birth	string	No	ISO 8601 date (e.g. 1990-01-15).
nationality	string	No	Nationality or country code.
collections	string[]	No	Collection identifiers to associate the person with.
notes	string	No	Free-form notes.

Request

Node.js

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

async function run() {
  const res = await fetch("https://api.verifik.co/v2/face-recognition/persons", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      name: "John Doe",
      images: ["<base64>", "<base64>"],
      gender: "M",
      date_of_birth: "1990-01-15",
      nationality: "US",
      collections: ["<collection_id_or_code>"],
      notes: "VIP customer",
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/face-recognition/persons");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "name" => "John Doe",
    "images" => ["<base64>", "<base64>"],
    "gender" => "M",
    "date_of_birth" => "1990-01-15",
    "nationality" => "US",
    "collections" => ["<collection_id_or_code>"],
    "notes" => "VIP customer",
]);
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/persons"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}",
}
payload = {
    "name": "John Doe",
    "images": ["<base64>", "<base64>"],
    "gender": "M",
    "date_of_birth": "1990-01-15",
    "nationality": "US",
    "collections": ["<collection_id_or_code>"],
    "notes": "VIP customer",
}
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{}{
        "name":           "John Doe",
        "images":         []string{"<base64>", "<base64>"},
        "gender":         "M",
        "date_of_birth":  "1990-01-15",
        "nationality":    "US",
        "collections":    []string{"<collection_id_or_code>"},
        "notes":          "VIP customer",
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.verifik.co/v2/face-recognition/persons", 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": "…",
  "data": {
    "_id": "…",
    "name": "John Doe",
    "gender": "M",
    "date_of_birth": "1990-01-15",
    "nationality": "US",
    "thumbnails": [],
    "collections": ["…"],
    "notes": "VIP customer",
    "client": "…",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "signature": {
    "message": "Certified by Verifik.co",
    "dateTime": "…"
  }
}

401/403

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

or

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

409

{
  "message": "Validation message or missing field",
  "code": "MissingParameter"
}

412

Name and date of birth are already enrolled in the requested collection. data is the existing person so you can update or 1:1-verify instead of guessing via 1:N search.

{
  "message": "person_already_set",
  "code": "PreconditionFailed",
  "data": {
    "_id": "693c646dfd68b59e4e8d1d58",
    "name": "Maria Perez",
    "date_of_birth": "1994-02-07",
    "gender": "F",
    "collections": [
      {
        "_id": "6612a020a55c329bfb3f62e6",
        "code": "ed27d231-b437-42c5-94c5-a2130c447d1e",
        "name": "CholloApp"
      }
    ],
    "thumbnails": [
      {
        "id": "thumb-1",
        "thumbnail": "<base64>"
      }
    ]
  }
}

thumbnails are the enrolled face crops so you can show the existing person next to the photo you just tried to enroll. You can also find the same record with Lookup a Person by Name. Very short image payloads may still return 412 with "message": "only_images_in_base64".

500

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

Notes

• images must be raw base64 strings; very short payloads may be rejected (e.g. 412:only_images_in_base64).
• Successful responses typically include Verifik envelope fields id, data, and signature; the exact data shape matches your environment and The Person Object.
• collections is often required in practice so the person is enrolled in at least one face collection for search and verification.