Digital Onboarding

Face verification - MS Face API

342 views August 28, 2017 December 1, 2017 1

Overview

The Microsoft Face API provides the functionality of determining the likelihood of two facial images belonging to the same person. The API will return a conclusion along with a confidence score that can be used to decide if the match is successful or not. Determining the proper confidence threshold for an application is typically subject to tuning as it will depend on image quality as well as the required strictness for the application.

Using the service

Authentication

All requests must be authenticated by means of an OIDC access token, supplied as an Authorization header of type Bearer. For more
instructions on how to obtain such a token, please refer to Accessing Signicat REST services.

API

Environment
Base URL
Beta https://beta.signicat.com
Preproduction https://preprod.signicat.com
Production https://id.signicat.com
Path
Verb
Content type
Input
Output
/ms-face/detect POST application/octet-stream Binary image file, max file size 4 MB If successful (HTTP 200), returns DetectResponse.
/ms-face/verify POST application/json VerifyRequest VerifyResponse

Code examples

Example using cURL
curl -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/octet-stream" \
    -H "Cache-Control: no-cache" \
    -H "Authorization: Bearer <token>" \
    --data-binary "@<photo-file>" \
  "https://<ENVIRONMENT>.signicat.com/ms-face/detect"
Example using cURL
curl -X POST \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "Cache-Control: no-cache" \
    -H "Authorization: Bearer <token>" \
    -d '{ \
    "faceId1":"<faceid1>", \
    "faceId2":"<faceid2>" \
    }' \
  "https://<ENVIRONMENT>.signicat.com/ms-face/verify"
Example using Java
package com.example;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ByteArrayEntity;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
public class MSFaceConnector {
    private final static String DETECT_ENDPOINT = "detect_endpoint_url";
    private final static String VERIFY_ENDPOINT = "verify_endpoint_url";
    private final static String VERIFY_JSON_TEMPLATE =
            "{\"faceId1\":\"<FACE_ID_1>\",\"faceId2\":\"<FACE_ID_2>\"}";
    public static String detect(CloseableHttpClient client, String
            accessToken, byte[] image) {
        HttpPost detectRequest = getRequestWithToken(DETECT_ENDPOINT,
                accessToken);
        detectRequest.setEntity(new ByteArrayEntity(image));
        return getResponse(client, detectRequest);
    }
    public static String verify(CloseableHttpClient client, String
            accessToken, String id1, String id2) {
        HttpPost verifyRequest = getRequestWithToken(VERIFY_ENDPOINT,
                accessToken);
        verifyRequest.addHeader("Content-Type", "application/json");
        verifyRequest.setEntity(new StringEntity(createJsonEntity(id1,
                id2), StandardCharsets.UTF_8));
        return getResponse(client, verifyRequest);
    }
    private static String createJsonEntity(String id1, String id2) {
        return VERIFY_JSON_TEMPLATE.replace("<FACE_ID_1>",
                id1).replace("<FACE_ID_2>", id2);
    }
    private static HttpPost getRequestWithToken(String endpoint, String
            accessToken) {
        HttpPost request = new HttpPost(endpoint);
        request.addHeader("Authorization", "Bearer " + accessToken);
        request.addHeader("Accept", "application/json");
        return request;
    }
    private static String getResponse(CloseableHttpClient client, HttpPost
            request) {
        try (CloseableHttpResponse response = client.execute(request)) {
            switch (response.getStatusLine().getStatusCode()) {
                case 200:
                    return EntityUtils.toString(response.getEntity());
                default:
                    return response.getStatusLine().getStatusCode() + ": " +
                            response.getStatusLine().getReasonPhrase();
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
        return null;
    }
}

Messages

DetectResponse

Name
Type
Description
FaceId UUID A unique identifier for the face detected in the image
FaceRectangle FaceRectangle Coordinates for the face location in the image

FaceRectangle

Name
Type
Description
Top Int The y-coordinate for the bounding rectangle
Left Int The x-coordinate for the bounding rectangle
Width Int The width of the bounding rectangle
Height Int The height of the bounding rectangle

VerifyRequest

Name
Type
Description
FaceId1 UUID The first unique identifier of a detected face, as returned by the DetectResponse.
FaceId2 UUID The second unique identifier of a detected face, as returned by the DetectResponse.

VerifyResponse

Name
Type
Description
IsIdentical Boolean True if the two faces are determined to belong to the same person.
Confidence Decimal A confidence score for the IsIdentical determination.

Was this helpful?