Face API

Welcome to Face API, an offering within Youverse Services.

This API allows you to perform any face processing (detection, analysis, template extraction) as well as performing verification (image to image matching) or identification (1 to many matching). All requests and responses are encoded in JSON and use a secure HTTPS channel.

The Face API was designed to bring face authentication to any application in a developer friendly fashion by exposing complex biometric functionalities via a simple REST API that can be integrated virtually in any programming language, in any environment.

Use cases

{primary} Face detection & analysis

Detect and count the number of faces. In addition, we provide a set of metrics describing each face, such as pose and liveness.

Liveness detection is available from our API but not available by default. If you're interested in using these capabilitites talk to our team.

{primary} ISO Quality check, ISO Token generation and Background Removal

Extensible face quality metric according to the latest ISO/IEC 29794-5 standard best pratices available as optional processing.

Additionally, we allow for background removal for complete portrait processing. We deliver state of the art performance even in challenging background segmentations.

These funcionalities are available from our API but not available by default. If you're interested in using these capabilitites talk to our team.

{primary} Face images verification

When you need to validate if two face images belong to the same person you can use this functionality.

For example, when integrating with a passport reader on a Kiosk, you can perform a face verification step between the chip image and the scan passport photo to check for data integrity and increase the security of your applications.

{primary} Face biometric template creation

In case you want to create a user base using their face, but you don't want to use images to comply with privacy-by-design at its best, you can convert the face of your user to a irreversible encrypted abstraction of the face image that you can reuse for authentication scenarios.

{primary} Face identification

We also enable the use of our state of the art algorithms in identification scenarios (1 against many matching). This process is managed by gallery management API.

Biometric Performance

Our face authentication algorithm is a NIST-certified technology based on proprietary research in state-of-the-art deep convolutional neural networks and proprietary loss function, being amongst the world's top-performing biometric algorithms.

False Match Operating (FMR)

The False Match Operating measures the likelihood that the biometric security system will incorrectly accept an access attempt by an unauthorized user. A system’s FMR typically is stated as the ratio of the number of false matches divided by the number of unauthorized verification attempts.

False Non Matches Rate(FNMR)

The False Non Matches Rate measures the likelihood that the biometric security system will incorrectly reject an access attempt by an authorized user. A system’s FNMR typically is stated as the ratio of the number of false non-matches divided by the number of authorized verification attempts.

Public Benchmarks

The two most commonly used verification datasets are the Labeled Faces in the Wild and the IJB-C. Both present captured in an uncontrolled environment, being IJB-C considerably more challenging offering subjects with total pose variation and occlusion. The IJB-C dataset presents images with an unconstrained pose, expression, lighting, and exposure, containing regular people, not easily recognizable celebrities. The MegaFace challenge aims to evaluate the performance of face recognition algorithms with up to a million distractors, i.e., up to a million people who are not in the probe set.

The table below shows the results for the three public benchmarks following the FMR vs FNMR trade-off curves.

Data set	Purpose	False Match Operating Point	False Non Matches Rate
LFW	Verification	1 in 100000	0.12%
IJBC	Verification	1 in 10000	2.0%
MegaFace	Identification	1 in 10000	0.4%

NIST Evaluation

The National Institute of Standards and Technology is a US government agency that evaluates advanced technologies for the benefit of the public market. The Facial Recognition Vendor Test (FRVT) is considered the most rigorous and challenging evaluation for facial recognition technology; clients often will not even consider a vendor unless NIST FRVT is certified. This evaluation measures the performance of an algorithm on different datasets of variable control and quality, such as Visa and Mugshots.

Visa - Border & Know Your Customer Applications

This dataset matches document (quality controlled) like images against unconstrained live images. Live images are acquired in uncontrolled illumination and face pose with large age difference between pictures (of up 45 degrees):

The graphic shows that for an FMR of 0.000001 (1 in 1000000), our algorithm has a 0.4% false non-match rate performance. This level of performance in practical terms means that for this level of strict security, only 4 out of 1000 people will not be able to use the system at the first attempt.

Mugshot

This dataset consists of matching pairs acquired with uncontrolled illumination and uncontrolled pose having subjects with more than 12 years difference between pictures.

The mugshot results shows that for an FMR of 0.000001 (1 in 1000000), our algorithm has less than 0.45% false non-match rate performance. This level of performance in practical terms means that for this level of strict security, less than 4.5 out of 1000 people will not be able to use the system at the first attempt.

Face endpoints

Process

Endpoint to perform the biometric processing. Provided an image in Base64 and a set of configurations, this will return the detected faces, with corresponding quality metrics and biometric template.

POST | {base_url}/face/process

Accepts: Process request

{success} Success

Status	Meaning	Schema
200	OK	Process response

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

Verify Templates

Endpoint that computes the similarity score between two biometric templates.

POST | {base_url}/face/verify

Accepts: Verify request

{success} Success

Status	Meaning	Schema
200	OK	Matching result

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

Verify Id

Endpoint to perform a one to one matching against a user enrolled in a gallery.

POST | {base_url}/face/verify_id

Accepts: Verify id request

{success} Success

Status	Meaning	Schema
200	OK	Matching Result

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

{warning} Conflict 409 can be raised if enrolled or gallery id does not exist.

Identify

Endpoint to perform face one-to-many comparison using a biometric template against a specific gallery.

POST | {base_url}/face/identify

Accepts: Identify request

{success} Success

Status	Meaning	Schema
200	OK	Candidates
Status	Meaning	Schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

{warning} Conflict 409 is raised if gallery id does not exist.

Gallery management

Gallery Creation

Endpoint to create a gallery to store the templates and their corresponding ids.

POST | {base_url}/gallery/{gallery_id}

Accepts: gallery_id parameter in the endpoint url

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

{warning} The conflict 409 status is raised when a gallery with the provided id already exists.

List gallery ids

Endpoint to list all ids enrolled in the specified gallery.

GET | {base_url}/gallery/{gallery_id}

Accepts: gallery_id parameter in the endpoint url

{success} Success

Status	Meaning	Schema
200	OK	Enrolled ids

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
404	Not Found	Error response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

Gallery deletion

Endpoint that deletes the specified gallery.

DELETE | {base_url}/gallery/{gallery_id}

Accepts: gallery_id parameter in the endpoint url

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
404	Not Found	Error response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

{warning} If the gallery does not exists the Conflict 409 Status Code is returned.

Add template to gallery

Endpoint to add a template with to a given gallery.

POST| {base_url}/gallery/{gallery_id}/{template_id}

Accepts: gallery_id and template_id in the endpoint URL and a Template Insertion schema in request body

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
404	Not Found	Error response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

If the template id already exists the HTTP 409 Status Code is returned.

Get template

Endpoint to return a template from a given gallery.

GET | {base_url}/gallery/{gallery_id}/{template_id}

Accepts: gallery_id and template_id in the endpoint URL.

{success} Success

Status	Meaning	Schema
200	OK	Template

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
404	Not Found	Error response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

Delete template from gallery

Endpoint to delete template from a given gallery.

DELETE | {base_url}/gallery/{gallery_id}/{template_id}

Accepts: gallery_id and template_id in the endpoint URL.

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	Error response
401	Unauthorized	Error response
403	Forbidden	Forbidden response
404	Not Found	Error response
405	Method Not Allowed	Error response
409	Conflict	Error response
500	Internal Server Error	Error response

Schemas

Process request

Request processing of an image in base64 and the biometric processings.

{
    "image": "string",
    "processings": ["detect", "analyze", "templify"],
    "configuration": [configA, configB]
}

Properties

Name	Type	Required	Restrictions	Description
image	string	True	BMP, PNG or JPG	Base 64 image
processings	array	False	None	Array of processings. Default is ["detect, "analyze", "templify"]
configuration	array	False	None	Array of extensible configurations.

Enumerable types

Property	Value	Description
processings	"detect"	Face detection
processings	"analyze"	Face analysis
processings	"templify"	Face templification

Process request config

Extensible configurations for biometric processing.

{
    "name": "string",
    "value": "string"
    "bvalue": true
}

Properties

Property	Value	Description
name	string	Configuration name.
value	string	Configuration value.
bvalue	boolean	Configuration boolean value.

Process Response

Processed image results. Each element of the array corresponds to a different face detected.

[
{
    "biometric_type": "face",
    "x": 0.0,
    "y": 0.0,
    "z": 0.0,
    "width": 0.0,
    "height": 0.0,
    "matching_score": 0.0,
    "matching_image": "string",
    "template": "string",
    "template_version": "string",
    "template_id": "string",
    "tracking_id": "string",
    "biometric_points": [firstPoint, secondPoint,...],
    "quality_metrics": [firstMetric, secondMetric...]    
}
]

Properties

Property	Value	Description
biometric_type	string	Always returns "face".
x	double	Face center coordinate x.
y	double	Face center coordinate y.
z	double	Face center coordinate y.
width	double	Face bounding box width.
height	double	Face bounding box height.
matching_score	double	Matching score obtained with template_id person.
matching_image	string	Thumbnail/crop used for template extraction.
template	string	Biometric template.
template_version	string	Template version.
template_id	string	Template id.
tracking_id	string	N/A from the API consumption perspective.
biometric_points	array	Array of face biometric points.
quality_metrics	array	Array of face quality metrics.

Biometric point

Representation of face biometric point.

{
    "name": "point name",
    "x": 0,
    "y": 0
}

Properties

Property	Value	Description
x	integer	Point y coordinate.
y	integer	Point y coordinate.
name	string	Point coordinate name.

Enumerable Types

Property	Value	Description
name	right_eye	Right eye center.
name	left_eye	Left eye center.
name	nose_tip	Nose tip point.
name	mouth_right	Mouth right corner point.
name	mouth_left	Mouth left corner point.
name	right_eye_right_corner	Right eye right corner point.
name	left_eye_left_corner	Left eye left corner point.
name	chin	Chin point.
name	undefined	Undefined point.

Quality metric

Representation of face quality metric, tresholds, and test decision.

{
    "name": "metric name",
    "value": 0.5,
    "enum": "string enumerable if applicable",
    "bottom_threshold": 0.0,
    "top_threshold": 1.0,
    "test": true
}

Properties

Property	Value	Description
name	string	Metric name.
value	double	Metric value.
enum	string	String with metric value for enumerables.
bottom_threshold	double	Bottom threshold.
top_threshold	double	Top threshold.
test	boolean	Metric test according to threshold.

Enumerable Types

Property	Value	Description
name	brightness	Average face brightness.
name	light_uniformity	Light distribution measurement.
name	contrast	Face contrast measurement.
name	sharpness	Face sharpness measurement.
name	roll	Face roll angle.
name	pitch	Face pitch angle.
name	yaw	Face yaw angle.
name	liveness	Face liveness measurement.
name	no_mask_present	Face mask presence detection.
name	age	Not yet available.
name	gender	Not yet available.
name	neutral_expression	Not yet available.
name	background_uniformity	The background is any surface or scene that is behind the subject. The background requirements are described in the ISO/IEC 39794-5:2019 standard. Three background checks form the basis for the background quality computation, i.e., uniformity, texturing, and white balance. Background uniformity is required for ID or passport emission applications but is not mandatory for other applications like enrolment in the airport for border control. Background uniformity is not expected to affect face matching/recognition performance.
name	ethnicity	Not yet available.
name	confidence	Face detection confidence.
name	grayscale_density	Measurement of number of levels of gray.
name	relative_horizontal_size	Face width per image width.
name	relative_vertical_size	Face height per image height.
name	relative_interocular_distance	Interocular distance per image width.
name	relative_horizontal_deviation	Relative deviation from image center.
name	relative_vertical_deviation	Relative deviation from image center.
name	eyes_open	Determines the likelihood of a face having both eyes open.
name	single_face	Determine the presence of a single face in the image.
name	mouth_closed	Determines the likelihood of a face having its mouth closed.
name	head_size	Relative head size to determine of crop is within image boundaries.
name	no_eye_glasses	Determine the presence of eyeglasses in the face picture.
name	no_eye_occlusion	In case the presence of glasses is detected, this metric provides a dark glasses metric.
name	no_under_exposure	Determines if a face is too dark if it has a high proportion of pixels with a low luminance value.
name	no_over_exposure	Determines if the face is too bright and has a high proportion of saturated pixels (with values 255).
name	natural_skin_color_a	Determines if a face picture presents a natural skin color tone. If the environment light is too warm and the face gains orangeish tones, the metric “natural_skin_color_a” should start to fail.
name	natural_skin_color_b	Single valued global image quality metric. When the face presents a blueish tone due to white-balance issues, the “natural_skin_color_b” metric should fail.
name	is_icao_compliant	Global metric that automatically accomodates all metric scores for icao compliance.
name	global_quality	Single valued global image quality metric.

Error response

{
  "status_code": 400,
  "phrase": "string",
  "message": "string"
}

Properties

Name	Type	Required	Restrictions	Description
status_code	integer	True	None	HTTP status code.
phrase	string	True	None	HTTP status code phrase.
message	string	True	None	Detailed error message.

Forbidden response

{
  "message": "Missing Authentication Token"
}

Properties

Name	Type	Required	Restrictions	Description
message	string	True	None	Detailed error message.

Template

Encrypted face biometric template.

{
    "template": "string"
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Face biometric template.

Template Insertion

Encrypted face biometric template to be inserted in gallery.

{
    "template": "string",
    "duplicate_check": false
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Face biometric template.
duplicate_check	boolean	False	Default:false	Deduplicate check before insert in gallery.

Matching result

Match result between two faces biometric templates or two face images.

{
    "score": 0.0
}

Properties

Name	Type	Required	Restrictions	Description
score	double	True	None	Similarity between two biometric templates.

Verify Request

Verification of two face biometric templates.

{
    "first_template": "string", 
    "second_template": "string"
}

Properties

Name	Type	Required	Restrictions	Description
first_template	string	True	None	Encrypted face biometric template.
second_template	string	True	None	Encrypted face biometric template.

Verify Id request

Verify id from a given gallery

{
    "template": "string", 
    "template_id": "string",
    "gallery_id": "string"
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Encrypted face biometric template.
template_id	string	True	None	Corresponds to the enrolled id gallery.
gallery_id	string	False	None	Gallery id.

Identify request

Identification of template in a given gallery.

{
    "template": "string",
    "candidate_list_length": 1,
    "minimum_score": -1,
    "gallery_id": "string"
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Encrypted face biometric template.
candidate_list_length	integer	False	minimum: 1	Maximal number of candidates to be returned.
minimum_score	string	False	minimum: -1	Minimum value for a positive match.
gallery_id	string	False	None	Gallery id.

Enrolled ids

List of ids in a given gallery.

["id", ...]

Properties

Name	Type	Required	Restrictions	Description
id	string	False	None	Enrolled id.

Candidates

Candidates from identification request.

[
    {
        "template_id":"string",
        "score": 0.5
    },...
]

Properties

Name	Type	Required	Restrictions	Description
template_id	string	True	None	Enrolled id.
score	string	False	None	Result score from comparing the identification template to the enrolled candidate.

Samples & SDKs

Please check our github space for more information about our integration SDKs.
We are looking into expand our current SDK offers, if you want to contribute please contact us.

Get started

Products

IAM Integrations

Face API

Use cases

Biometric Performance

False Match Operating (FMR)

False Non Matches Rate(FNMR)

Public Benchmarks

NIST Evaluation

Visa - Border & Know Your Customer Applications

Mugshot

Face endpoints

Process

Verify Templates

Verify Id

Identify

Gallery management

Gallery Creation

List gallery ids

Gallery deletion

Add template to gallery

Get template

Delete template from gallery

Schemas

Process request

Process request config

Process Response

Biometric point

Quality metric

Properties

Enumerable Types

Error response

Forbidden response

Template

Template Insertion

Matching result

Verify Request

Verify Id request

Identify request

Enrolled ids

Candidates

Samples & SDKs