Face Validation

Introduction

Incode performs two validations related to a face (or selfie image):

Liveness validation: Performed as soon as you add a selfie image to a session via the endpoint /omni/add/face/third-party?imageType=selfie. It protects you against someone uploading a pre-existing photo and claiming it's a selfie.
Face Match validation: Compares the selfie image against the face that appears on an ID uploaded as part of the same session. This check is performed when you call the endpoint /omni/process/face?imageType=selfie. It will not work if you have not already uploaded an ID, so it's important to perform these steps in the order we've discussed them (see previous step).

Face validation requires these two endpoint calls and you must perform them in the order shown:

Header requirements

Both endpoints require these header values:

Header	Value
`x-api-key`	The API key provided to you by Incode.
`api-version`	"1.0"
`X-Incode-Hardware-Id`	The Session Token obtained when you started the onboarding session.

Body/image requirements

Images must be provided in the request body as a base64 encoded string. They must meet these requirements:

Minimum of 1000 pixels on one dimension, either width or height.
Cannot exceed 10 MB as mentioned in the limitations of the API documentation.

Sample Code

Add face

curl --location 'https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=selfie' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'x-api-key: <your_api_key>' \
--header 'X-Incode-Hardware-Id: <your_session_token>' \
--data '{
    "base64Image": ""
}'

const axios = require('axios');
const fs = require('fs');

// Read your image file and encode as base64
const imageFilePath = 'path/to/your/image.jpg';
const base64 = fs.readFileSync(imageFilePath, { encoding: 'base64' });

const data = JSON.stringify({
  base64Image: base64
});

const config = {
  method: 'post',
  url: 'https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=selfie',
  headers: { 
    'Content-Type': 'application/json', 
    'api-version': '1.0', 
    'x-api-key': '<your_api_key>',
    'X-Incode-Hardware-Id': '<your_session_token>'
  },
  data : data
};

axios(config).then(function (response) {
  console.log(response.data);
});

var client = HttpClient.newHttpClient();

// Read your image file and encode as base64
Path imagePath = Path.of("path/to/your/image.jpg");
String base64 = Base64.getEncoder().encodeToString(Files.readAllBytes(imagePath));

var request = HttpRequest.newBuilder()
  .uri(URI.create("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=selfie"))
  .header("Content-Type", "application/json")
  .header("api-version", "1.0")
  .header("x-api-key", "<your_api_key>")
  .header("X-Incode-Hardware-Id", "<your_session_token>")
  .POST(BodyPublishers.ofString("{\"base64Image\":\"" + base64 + "\"}"))
  .build();

var response = client.send(request, BodyHandlers.ofString());
System.out.println(response.body());

using var client = new HttpClient();

// Read your image file and encode as base64
var imageFilePath = "path/to/your/image.jpg";
var base64 = Convert.ToBase64String(File.ReadAllBytes(imageFilePath));

var json = "{\"base64Image\":\"" + base64 + "\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
client.DefaultRequestHeaders.Add("api-version", "1.0");
client.DefaultRequestHeaders.Add("x-api-key", "<your_api_key>");
client.DefaultRequestHeaders.Add("X-Incode-Hardware-Id", "<your_session_token>");

var response = await client.PostAsync("https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=selfie", content);
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);

import requests
import base64

# Read your image file and encode as base64
image_file_path = 'path/to/your/image.jpg'
with open(image_file_path, "rb") as image_file:
    base64 = base64.b64encode(image_file.read()).decode('utf-8')

url = "https://demo-api.incodesmile.com/omni/add/face/third-party?imageType=selfie"

payload = {
    "base64Image": base64
}
headers = {
    'Content-Type': 'application/json',
    'api-version': '1.0',
    'x-api-key': '<your_api_key>',
    'X-Incode-Hardware-Id': '<your_session_token>'
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

After a face has been added successfully, you can see the liveness score by going to Dashboard > Sessions, then locating and selecting the session. To learn more the request / response for this endpoint, see the Add face/Selfie image API endpoint documentation.

Process face

curl --location 'https://demo-api.incodesmile.com/omni/process/face?imageType=selfie' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'x-api-key: <your_api_key>' \
--header 'X-Incode-Hardware-Id: <your_session_token>' \
--data '{}'

const axios = require('axios');
const data = JSON.stringify({});

const config = {
  method: 'post',
  url: 'https://demo-api.incodesmile.com/omni/process/face?imageType=selfie',
  headers: { 
    'Content-Type': 'application/json', 
    'api-version': '1.0', 
    'x-api-key': '<your_api_key>',
    'X-Incode-Hardware-Id': '<your_session_token>'
  },
  data : data
};

axios(config).then(function (response) {
  console.log(response.data);
});

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
  .uri(URI.create("https://demo-api.incodesmile.com/omni/process/face?imageType=selfie"))
  .header("Content-Type", "application/json")
  .header("api-version", "1.0")
  .header("x-api-key", "<your_api_key>")
  .header("X-Incode-Hardware-Id", "<your_session_token>")
  .POST(BodyPublishers.ofString("{}"))
  .build();

var response = client.send(request, BodyHandlers.ofString());
System.out.println(response.body());

using var client = new HttpClient();

var json = "{}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
client.DefaultRequestHeaders.Add("api-version", "1.0");
client.DefaultRequestHeaders.Add("x-api-key", "<your_api_key>");
client.DefaultRequestHeaders.Add("X-Incode-Hardware-Id", "<your_session_token>");

var response = await client.PostAsync("https://demo-api.incodesmile.com/omni/process/face?imageType=selfie", content);
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);

import requests

url = "https://demo-api.incodesmile.com/omni/process/face?imageType=selfie"

payload = {}
headers = {
    'Content-Type': 'application/json',
    'api-version': '1.0',
    'x-api-key': '<your_api_key>',
    'X-Incode-Hardware-Id': '<your_session_token>'
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

After a face has been processed successfully, you can see the face-match score by going to Dashboard > Sessions, then locating and selecting the session. To learn more the request / response for this endpoint, see the Process face API endpoint documentation.