Face Enrollment
In FACIA, face enrollment goes beyond a mere process – it's a personalized journey of capturing and preserving distinctive facial features to craft a unique biometric template. This template serves as the key to seamless identity verification through our advanced facial recognition algorithms, providing a secure and user-friendly authentication method.
Create Face Enrollment Transaction
This endpoint enables users to enroll one or more faces using the POST method:
Endpoint
POSThttps://api.facia.ai/enroll-face
Authorization:
Token Type: BearerDescription:
This API utilizes Access token or Client-Secret key in header for authentication.
You can use your client_id and client_secret key when using the "/request-access-token" endpoint to obtain a Bearer token for authorization while connecting to this API. For additional details on Authorization, click Here
Request Body Samples:
- HTTP
- Javascript
- Curl
- PHP
- Python
- Ruby
- Java
- C#
- Go
//POST /enroll-face HTTP/1.1
//HOST : https://api.facia.ai/
//Content-Type: application/json
//Authorization: Bearer <access-token-here>
{
"file_list": [
"file",
"file"
],
"client_reference": "your_client_reference_here",
"allow_override": 0
}
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
var formdata = new FormData();
formdata.append("file_list[0]", fileInput.files[0], "file_example_IMAGE_640_3MG.jpg");
formdata.append("file_list[1]", fileInput.files[0], "file_example_IMAGE_640_3MG.jpg");
formdata.append("client_reference", "your_client_reference_here");
formdata.append("allow_override", false);
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: formdata,
redirect: 'follow'
};
fetch("/enroll-face", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
curl --location 'https://api.facia.ai/enroll-face' \
--header 'Content-Type: application/json' \
--data '{
{
"file_list[0]": file,
"file_list[1]": file,
"client_reference":"your_client_reference_here",
"allow_override":false
}
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '/enroll-face',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array('client_reference' => 'your_client_reference_here','allow_override'=> false, 'file_list[0]'=> new CURLFILE('file_example_IMAGE_640_3MG.jpg'), 'file_list[1]'=> new CURLFILE('file_example_IMAGE_640_3MG.jpeg')),
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer token'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests
url = "/enroll-face"
payload={'client_reference': 'your_client_reference_here', 'allow_override'=> false}
files=[
('file_list[0]',('file_example_IMAGE_640_3MG.jpg',open('/file_example_IMAGE_640_3MG.jpg','rb'),'image/jpeg')),
('file_list[1]',('file_example_IMAGE_640_3MG.jpg',open('/file_example_IMAGE_640_3MG.jpg','rb'),'image/jpeg')) ]
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
require 'net/http'
require 'uri'
require 'json'
url = URI.parse('/enroll-face')
token = 'your_token'
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path)
request['Authorization'] = "Bearer #{token}"
boundary = '*****'
request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
body = []
file1 = File.new('file_example_IMAGE_640_3MG.jpg')
file2 = File.new('file_example_IMAGE_640_3MG.jpg')
body << "--#{boundary}\r\n"
body << "Content-Disposition: form-data; name=\"file_list[0]\"; filename=\"#{file1.path}\"\r\n"
body << "Content-Type: #{file1.content_type}\r\n\r\n"
body << file1.read
body << "\r\n"
body << "--#{boundary}\r\n"
body << "Content-Disposition: form-data; name=\"file_list[1]\"; filename=\"#{file2.path}\"\r\n"
body << "Content-Type: #{file2.content_type}\r\n\r\n"
body << file2.read
body << "\r\n"
body << "--#{boundary}\r\n"
body << "Content-Disposition: form-data; name=\"client_reference\"\r\n\r\nyour_client_reference_here\r\n"
body << "--#{boundary}\r\n"
body << "Content-Disposition: form-data; name=\"allow_override\"\r\n\r\nfalse\r\n"
body << "--#{boundary}--\r\n"
request.body = body.join
response = http.request(request)
puts "Response Code: #{response.code}"
puts "Response Body: #{response.body}"
import java.io.File;
import java.io.FileInputStream;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
public class FaceEnrollExample {
public static void main(String[] args) {
try {
String endpoint = "/enroll-face";
String token = "your_token";
URL url = new URL(endpoint);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Authorization", "Bearer " + token);
connection.setDoInput(true);
connection.setDoOutput(true);
String boundary = "*****";
connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
OutputStream outputStream = connection.getOutputStream();
File file1 = new File("file_example_IMAGE_640_3MG.jpg");
File file2 = new File("file_example_IMAGE_640_3MG.jpg");
appendFileToFormData(outputStream, boundary, "file_list[0]", file1);
appendFileToFormData(outputStream, boundary, "file_list[1]", file2);
appendFormField(outputStream, boundary, "client_reference", "your_client_reference_here");
appendFormField(outputStream, boundary, "allow_override", "false");
outputStream.write(("--" + boundary + "--\r\n").getBytes());
int responseCode = connection.getResponseCode();
System.out.println("Response Code: " + responseCode);
connection.disconnect();
} catch (Exception e) {
e.printStackTrace();
}
}
private static void appendFileToFormData(OutputStream outputStream, String boundary, String fieldName, File file) throws Exception {
outputStream.write(("--" + boundary + "\r\n").getBytes());
outputStream.write(("Content-Disposition: form-data; name=\"" + fieldName + "\"; filename=\"" + file.getName() + "\"\r\n").getBytes());
outputStream.write(("Content-Type: " + HttpURLConnection.guessContentTypeFromName(file.getName()) + "\r\n\r\n").getBytes());
FileInputStream fileInputStream = new FileInputStream(file);
byte[] buffer = new byte[4096];
int bytesRead;
while ((bytesRead = fileInputStream.read(buffer)) != -1) {
outputStream.write(buffer, 0, bytesRead);
}
outputStream.write("\r\n".getBytes());
fileInputStream.close();
}
private static void appendFormField(OutputStream outputStream, String boundary, String fieldName, String fieldValue) throws Exception {
outputStream.write(("--" + boundary + "\r\n").getBytes());
outputStream.write(("Content-Disposition: form-data; name=\"" + fieldName + "\"\r\n\r\n" + fieldValue + "\r\n").getBytes());
}
}
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string endpoint = "https://api.facia.ai/enroll-face";
string token = "your_token";
using (var httpClient = new HttpClient())
using (var form = new MultipartFormDataContent())
{
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
var file1 = new FileStream("file_example_IMAGE_640_3MG.jpg", FileMode.Open);
var file2 = new FileStream("file_example_IMAGE_640_3MG.jpg", FileMode.Open);
form.Add(new StreamContent(file1), "file_list[0]", "file_example_IMAGE_640_3MG.jpg");
form.Add(new StreamContent(file2), "file_list[1]", "file_example_IMAGE_640_3MG.jpg");
form.Add(new StringContent("your_client_reference_here"), "client_reference");
form.Add(new StringContent("false"), "allow_override");
using (var response = await httpClient.PostAsync(endpoint, form))
{
Console.WriteLine($"Response Code: {response.StatusCode}");
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Response Body: {result}");
}
}
}
}
package main
import (
"bytes"
"fmt"
"mime/multipart"
"net/http"
"os"
)
func main() {
endpoint := "/enroll-face"
token := "your_token"
client := &http.Client{}
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
headers := map[string]string{
"Authorization": "Bearer " + token,
}
fileNames := []string{"file_example_IMAGE_640_3MG.jpg", "file_example_IMAGE_640_3MG.jpg"}
for _, fileName := range fileNames {
file, err := os.Open(fileName)
if err != nil {
fmt.Println("Error opening file:", err)
return
}
defer file.Close()
part, err := writer.CreateFormFile("file_list[]", fileName)
if err != nil {
fmt.Println("Error creating form file:", err)
return
}
_, err = io.Copy(part, file)
if err != nil {
fmt.Println("Error copying file to form:", err)
return
}
}
formFields := map[string]string{
"client_reference": "your_client_reference_here",
"allow_override": "false",
}
for fieldName, value := range formFields {
_ = writer.WriteField(fieldName, value)
}
writer.Close()
req, err := http.NewRequest("POST", endpoint, body)
if err != nil {
fmt.Println("Error creating request:", err)
return
}
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", writer.FormDataContentType())
response, err := client.Do(req)
if err != nil {
fmt.Println("Error making request:", err)
return
}
defer response.Body.Close()
fmt.Println("Response Code:", response.Status)
responseBody, err := ioutil.ReadAll(response.Body)
if err != nil {
fmt.Println("Error reading response body:", err)
return
}
fmt.Println("Response Body:", string(responseBody))
}
Request Parameter
| Parameters | Description |
|---|---|
| file_list[0] | Required: Yes Type: file or string multipart/form-data: send each image file (.jpg, .jpeg, .png) as file_list[0], file_list[1].application/json: send file_list as an array of Base64 data URIs including the prefix, e.g. "file_list": ["data:image/jpeg;base64,/9j/4AAQ..."]. Plain Base64 without the data:image/...;base64, prefix is rejected. |
| file_list[1] | Required: No Type: file or string Optional second image, sent the same way as file_list[0]. |
| client_reference | Required: No Type: string Minimum: 5 characters Maximum: 255 characters Example: client_reference="your_client_reference_here" Required if allow_override field set to 1. |
| allow_override | Required: No Type: boolean Default value: 0 Accepted values: 0,1 The client reference is mandatory if the value of the override key is set as 1. The override key allow the system to replace the latest previous image with the new one against the specified reference number of the client’s reference. |
Response Sample
{
"status": true,
"message": "Success",
"result": {
"data": {
"client_reference": "your_client_reference_here"
"reference_id": [
"your_reference_id_1_here",
"your_reference_id_2_here"
]
}
}
}
Response Parameter
| Parameters | Description |
|---|---|
| client_reference | Type: string Example: client_reference:your_client_reference_here Contains the unique ID defined for the end user. |
| reference_id | Type: array Example: reference_id:["your_reference_id_1_here","your_reference_id_2_here"] These are the references of provided proofs that were to be enrolled. |
Get Enrolled Faces
This endpoint facilitates the retrieval of all enrolled faces using the POST method. The pagination parameter (records per page) is required in every request; page and is_pagination are optional. See Request Parameter for details.
Endpoint
POSThttps://api.facia.ai/enrolled-faces
Authorization:
Token Type: BearerDescription:
This API utilizes Access token or Client-Secret key in header for authentication.
You can use your client_id and client_secret key when using the "/request-access-token" endpoint to obtain a Bearer token for authorization while connecting to this API. For additional details on Authorization, click Here
Request Body Samples:
- HTTP
- Javascript
- Curl
- PHP
- Python
- Ruby
- Java
- C#
- Go
//POST /enrolled-faces HTTP/1.1
//Host: https://api.facia.ai/
//Content-Type: application/json
//client-secret: <your client_secret key>
{
"pagination": 10,
"page": 1,
"is_pagination": 1
}
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({
"pagination": 10,
"page": 1,
"is_pagination": 1
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("/enrolled-faces", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
curl --location 'https://api.facia.ai/enrolled-faces' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"pagination": 10,
"page": 1,
"is_pagination": 1
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => '/enrolled-faces',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode(array(
'pagination' => 10,
'page' => 1,
'is_pagination' => 1
)),
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer token',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import requests
url = "/enrolled-faces"
payload = {
"pagination": 10,
"page": 1,
"is_pagination": 1
}
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)
require 'net/http'
require 'uri'
require 'json'
url = URI.parse('/enrolled-faces')
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path)
request['Authorization'] = 'Bearer token'
request['Content-Type'] = 'application/json'
request.body = { pagination: 10, page: 1, is_pagination: 1 }.to_json
response = http.request(request)
puts "Response Code: #{response.code}"
puts "Response Body: #{response.body}"
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
public class EnrolledFacesRequest {
public static void main(String[] args) {
try {
URL url = new URL("/enrolled-faces");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Authorization", "Bearer token");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
String payload = "{\"pagination\": 10, \"page\": 1, \"is_pagination\": 1}";
try (OutputStream os = connection.getOutputStream()) {
os.write(payload.getBytes(StandardCharsets.UTF_8));
}
int responseCode = connection.getResponseCode();
BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
StringBuilder response = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) {
response.append(line);
}
reader.close();
System.out.println("Response Code: " + responseCode);
System.out.println("Response Body: " + response.toString());
connection.disconnect();
} catch (Exception e) {
e.printStackTrace();
}
}
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string apiUrl = "/enrolled-faces";
string authToken = "Bearer token";
string payload = "{\"pagination\": 10, \"page\": 1, \"is_pagination\": 1}";
using (HttpClient httpClient = new HttpClient())
{
httpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", authToken);
var content = new StringContent(payload, Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.PostAsync(apiUrl, content);
Console.WriteLine($"Response Code: {response.StatusCode}");
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Response Body: {responseBody}");
}
}
}
package main
import (
"bytes"
"fmt"
"io/ioutil"
"net/http"
)
func main() {
apiURL := "/enrolled-faces"
authToken := "Bearer token"
payload := []byte(`{"pagination": 10, "page": 1, "is_pagination": 1}`)
client := &http.Client{}
req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(payload))
if err != nil {
fmt.Println("Error creating request:", err)
return
}
req.Header.Set("Authorization", authToken)
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error making request:", err)
return
}
defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response body:", err)
return
}
fmt.Println("Response Code:", resp.Status)
fmt.Println("Response Body:", string(body))
}
Request Parameter
| Parameters | Description |
|---|---|
| pagination | Required: Yes Type: integer Example: pagination=10 Min: 1 Max: 100 Number of records to return per page. Requests sent without this parameter are rejected with a validation error. |
| page | Required: No Type: integer Default: 1 Min: 1 Example: page=1 The page number to return. |
| is_pagination | Required: No Type: boolean / integer Example: is_pagination=1 If set to a truthy value (e.g. 1 or true), result.data is returned as a paginated object with page details (current_page, last_page, total, etc.) and the records inside result.data.data. If omitted, result.data is returned as a plain list of records, still limited to pagination records. |
pagination is mandatory for this endpoint. Always send it in the request body, even if you only need the first page of results.Response Sample
With is_pagination set to 1
{
"status": true,
"message": "Success",
"result": {
"data": {
"current_page": 1,
"data": [
{
"reference_id": "your_reference_id_here",
"created_at": "2026-09-25T11:42:04.000000Z",
"client_reference": "your_client_reference_here",
"url": "https://api.facia.ai/get-proof/d2p4Z04wTWxUN3Q0WjhPYmJhc283bWVWOUh2clpHTnQ6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGI7",
"thumbnail_url": "https://api.facia.ai/get-proof/TFhaYThwdzdVNldFOGlERm80QWtNaVgzMUVzVUZsV1Q6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGJ2"
}
],
"first_page_url": "https://api.facia.ai/enrolled-faces?page=1",
"from": 1,
"last_page": 3,
"last_page_url": "https://api.facia.ai/enrolled-faces?page=47",
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=1",
"label": "1",
"active": true
},
{
"url": "https://api.facia.ai/enrolled-faces?page=2",
"label": "2",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=3",
"label": "3",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=4",
"label": "4",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=5",
"label": "5",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=6",
"label": "6",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=7",
"label": "7",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=8",
"label": "8",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=9",
"label": "9",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=10",
"label": "10",
"active": false
},
{
"url": null,
"label": "...",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=46",
"label": "46",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=47",
"label": "47",
"active": false
},
{
"url": "https://api.facia.ai/enrolled-faces?page=2",
"label": "Next »",
"active": false
}
],
"next_page_url": "https://api.facia.ai/enrolled-faces?page=2",
"path": "https://api.facia.ai/enrolled-faces",
"per_page": 10,
"prev_page_url": null,
"to": 10,
"total": 468
}
}
}
Without is_pagination
The records are returned directly in result.data, without page details. The list is still limited to pagination records.
{
"status": true,
"message": "Success",
"result": {
"data": [
{
"reference_id": "your_reference_id_here",
"created_at": "2026-09-25T11:42:04.000000Z",
"client_reference": "your_client_reference_here",
"url": "https://api.facia.ai/get-proof/d2p4Z04wTWxUN3Q0WjhPYmJhc283bWVWOUh2clpHTnQ6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGI7",
"thumbnail_url": "https://api.facia.ai/get-proof/TFhaYThwdzdVNldFOGlERm80QWtNaVgzMUVzVUZsV1Q6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGJ2"
}
]
}
}
Response Parameter
| Parameters | Description |
|---|---|
| data | Type: array This includes the enrolled images. When is_pagination is set, the records are in result.data.data; otherwise result.data is the list itself. |
| reference_id | Type: string Example: reference_id="your_reference_id_here" The unique identifier of the enrollment transaction. |
| created_at | Type: string Example: created_at="2026-09-25T11:42:04.000000Z" Date and time (UTC) when the face was enrolled. |
| client_reference | Type: string or null Example: client_reference="your_client_reference_here" Contains the unique ID defined for the end user. null if no client reference was provided at enrollment. |
| url | Type: string URL of the proof with the expiry of 15 minutes. |
| thumbnail_url | Type: string URL of the thumbnail of the proof with the expiry of 15 minutes. |
| current_page | Type: integer The page number returned. Only present when is_pagination is set. |
| from / to | Type: integer or null Position of the first and last record on this page within the full result set. Only present when is_pagination is set. |
| per_page | Type: integer Number of records per page, as sent in pagination. Only present when is_pagination is set. |
| total | Type: integer Total number of enrolled faces. Only present when is_pagination is set. |
| last_page | Type: integer The last available page number. Only present when is_pagination is set. |
| first_page_url / last_page_url | Type: string URLs of the first and last pages. Only present when is_pagination is set. |
| next_page_url / prev_page_url | Type: string or null URLs of the next and previous pages, or null if there is none. Only present when is_pagination is set. |
| path | Type: string Base URL of the endpoint. Only present when is_pagination is set. |
| links | Type: array Page navigation links, each with url, label and active. Only present when is_pagination is set. |
urlandthumbnail_urlare signed on every request, so the same record returns a different URL each time. Each URL expires after 15 minutes.- For video (detail liveness) enrollments,
urlandthumbnail_urlpoint to the same frame.