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	Base64-encoded face images (no data: URL prefix).
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

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

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.