GBG Developers

Guides   |   FaceMatch

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 FaceMatch request, you will first need to obtain a verification identifier ('verificationID' field) by performing a verify document check. This identifier is then submitted as part of the FaceMatch 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 scoring. The FaceMatch request requires the person-id field to be populated from the response to a previous verification request.

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

The Response

An id for this request that can be used with the verification history API to look up results at a later date is returned as a response header with the key 'verification-id'.

A successful response will contain a body with the following schema:

{
  "verificationID": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  "timestamp": "2019-01-04T14:38:25Z",
  "customerReference": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
  "journey": {
    "journey-id": "7ab2ff08-728a-42e6-aa38-df191ffd4817",
    "journey-version": 0
  },
  "verification": {
    "derivedData": {
      "isRecognised": true,
      "person": {
        "title": "Mr",
        "firstName": "David",
        "middlenames": [
          "James"
        ],
        "lastnames": [
          "Jones"
        ],
        "gender": "MALE",
        "birthdate": "2000-01-01",
        "address": {
          "extracted": "string",
          "enrichment": {
            "cleansed": {
              "lines": [
                "string"
              ],
              "address": "string",
              "premise": "128",
              "building": "string",
              "subBuilding": "string",
              "thoroughfare": "Queen Victoria Street",
              "dependentThoroughfare": "string",
              "locality": "London",
              "dependentLocality": "string",
              "doubleDependentLocality": "string",
              "postalCode": "EC4V 4BJ",
              "postBox": "string",
              "country": "GBR",
              "superAdministrativeArea": "string",
              "administrativeArea": "string",
              "subAdministrativeArea": "string",
              "organization": "GB Group",
              "quality": {
                "avc": "string",
                "aqi": "string"
              },
              "location": {
                "latitude": "string",
                "longitude": "string",
                "geoAccuracy": "string"
              }
            }
          }
        }
      },
      "fields": [
        {
          "id": "string",
          "name": "string",
          "type": "string",
          "description": "string",
          "value": "string"
        }
      ],
      "images": [
        {
          "type": "DIGITAL_TAMPERING_HEAT_MAP",
          "imageUrl": "string",
          "imageID": "string",
          "base64Image": "string"
        }
      ],
      "classification": {
        "type": "string",
        "category": "string",
        "name": "string",
        "issue": "string",
        "issuingAuthority": "string"
      }
    },
    "analysis": [
      {
        "name": "string",
        "description": "string",
        "id": 0,
        "country": {
          "code": "string",
          "name": "string"
        },
        "comments": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "matches": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "warnings": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "mismatches": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "flags": {
          "address": "NA",
          "firstName": "NA",
          "lastName": "NA",
          "birthDate": "NA",
          "alert": "NA",
          "pass": "NA"
        }
      }
    ],
    "result": {
      "function": "VERIFY-PERSON",
      "state": "string",
      "score": 0
    }
  },
  "triangulation": {
    "candidates": [
      {
        "index": "string",
        "title": "Mr",
        "firstName": "David",
        "middlenames": [
          "James"
        ],
        "lastnames": [
          "Jones"
        ],
        "gender": "MALE",
        "birthdate": "2000-01-01",
        "addresses": [
          {
            "type": "CURRENT",
            "address": {
              "lines": [
                "string"
              ],
              "address": "string",
              "premise": "128",
              "building": "string",
              "subBuilding": "string",
              "thoroughfare": "Queen Victoria Street",
              "dependentThoroughfare": "string",
              "locality": "London",
              "dependentLocality": "string",
              "doubleDependentLocality": "string",
              "postalCode": "EC4V 4BJ",
              "postBox": "string",
              "country": "GBR",
              "superAdministrativeArea": "string",
              "administrativeArea": "string",
              "subAdministrativeArea": "string",
              "organization": "GB Group",
              "quality": {
                "avc": "string",
                "aqi": "string"
              },
              "location": {
                "latitude": "string",
                "longitude": "string",
                "geoAccuracy": "string"
              }
            },
            "resident": {
              "from": "2000-01-01",
              "to": "2000-01-01"
            },
            "enrichments": {
              "cleansed": {
                "lines": [
                  "string"
                ],
                "address": "string",
                "premise": "128",
                "building": "string",
                "subBuilding": "string",
                "thoroughfare": "Queen Victoria Street",
                "dependentThoroughfare": "string",
                "locality": "London",
                "dependentLocality": "string",
                "doubleDependentLocality": "string",
                "postalCode": "EC4V 4BJ",
                "postBox": "string",
                "country": "GBR",
                "superAdministrativeArea": "string",
                "administrativeArea": "string",
                "subAdministrativeArea": "string",
                "organization": "GB Group",
                "quality": {
                  "avc": "string",
                  "aqi": "string"
                },
                "location": {
                  "latitude": "string",
                  "longitude": "string",
                  "geoAccuracy": "string"
                }
              }
            }
          }
        ],
        "phones": [
          {
            "type": "HOME",
            "number": "+44 207 4281250"
          }
        ]
      }
    ],
    "analysis": [
      {
        "comments": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "matches": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "warnings": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ],
        "mismatches": [
          {
            "text": "string",
            "code": 0,
            "override": "string"
          }
        ]
      }
    ],
    "rule": {
      "id": "string",
      "description": "string"
    },
    "result": "string"
  },
  "combined": {
    "verifications": [
      {
        "result": {
          "function": "VERIFY-PERSON",
          "state": "string",
          "score": 0
        }
      }
    ],
    "decision": "string",
    "notes": "string"
  },
  "action": "string"
}

 

What next?

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