GBG Developers

Guides   |   FaceMatch


Our FaceMatch API is designed to be used in conjunction with the verify document API to provide an added level of assurance to your identity checks.


What does FaceMatch do?

The FaceMatch API allows you to upload a selfie of the user you are trying to validate. This selfie is then compared to the image on the document provided and returns a verification result, indicating if the two images match.


How does FaceMatch work?

The Request

To perform a Face Match request, you will first need to obtain a verification identifier ('verification-id' field) by performing a verify document check. The verify document check performed will be used to compare the Face Match against the portrait photo on the document uploaded (it is therefore not possible to perform a Face Match against a document that doesn't have the portrait photo).  This 'verification-id' identifier is then submitted as part of the Face Match request in the 'document-verification-id' header.

The selfie image is submitted to the service using a POST request, supplying your image as multipart/form-data.

The Person Id

For the first request made in a series of verification requests that relate to a single subject, a person identifier or 'person-id' field will be returned by the Identity Solution. You should use this identifier for each subsequent request you make to any of the verification services. This will allow the Identity Solution to combine these verifications into a single record and perform actions such as combined decision. The Face Match request requires the person-id field to be populated from the response (header) to a previous verification request.

For more information on where and how to supply the person identifier, see our API Reference Documentation.

The Response

The response will contain a timestamp, verification result and combined decision.  For more information on the response details, see our API Reference Documentation.

The verification result

The possible values of the result field are as follows:

  • PASS: Matched
  • NotMatched
  • NoFace
  • Undetermined
  • Identical

Only the "PASS" result listed first above is considered a successful result by the Combined Decision.  "NotMatched" indicates no correlation in facial features, "NoFace" indicates that a face was not found on the image provided, "Undetermined" indicates that a result couldn't be made and "Identical" indicates that the images used were the same (which could be a person also trying to re-use their document portrait photo in the Face Match verification).

What next?

To implement the Face Match API, find detailed API information in our API Reference.