Integration with Face API

The integration of the Face API to the Document Reader SDK adds an automatic face match and search by a portrait taken from the document (Visual Zone and RFID chip) or a live owner photo.

Settings for the Face SDK can be defined by one of the methods:

At the service startup. See the details on the Integration with Face API page.
Per each request—in JSON parameters. See the details in further sections.

Note that values specified in JSON take priority. For example, if one service address is specified in the config.yaml file and another is specified in the body of the request, the latter will be applied.

To set up the integration with Face API, use:

{
    "processParam": {
        "useFaceApi": true
    }
}

Configuration

To add a live photo of the document owner (selfie) for comparison with the photo from the visual zone of the document, use:

{
    "processParam": {
        "useFaceApi": true
    },
    "livePortrait": "base64image"
}

To add a photo from an external source, for example, a database, use:

{
    "processParam": {
        "useFaceApi": true
    },
    "extPortrait": "base64image"
}

To crop a selfie from the same image as the document and compare the selfie with document holder's photo, use:

{
    "processParam": {
        "useFaceApi": true,
        "oneShotIdentification": true
    }
}

To configure Face SDK parameters, use:

{
    "processParam": {
        "useFaceApi": true,
        "faceApi": {
            "url": "https://faceapi.regulaforensics.com",
            "mode": "match+search",
            "search": {
                "limit": 10,
                "group_ids": ["guid1", "guid2"]
            },
            "threshold": 75,
            "serviceTimeout": 3000
        }
    }
}

See all available Face API configuration parameters and their descriptions below.

└── faceApi
|   └── url
|   └── mode
|   └── search
|   |   └── limit
|   |   └── threshold
|   |   └── group_ids    
|   └── threshold    
|   └── serviceTimeout
|   └── proxy
|   └── proxy_userpwd
|   └── proxy_type
|   └── childAgeThreshold
|   └── childDocValidityYears

Parameter	Default	Description
`url`	`https://faceapi.regulaforensics.com`	The URL of the Regula Face SDK service instance to be used. Note that the default https://faceapi.regulaforensics.com can be used for demo purposes only. For production use, you should purchase an appropriate license. Please contact us here.
`mode`	`"match"`	The processing mode: "match" or "match+search". `match` is a comparison of persons that are passed in the request, works by default. `match+search` performs both matching and searching by image. If only one person is available, `match` is not performed and only the `search` is carried out. If no search parameters are specified, the `search` is conducted over the entire database with the default parameters. Learn more in OpenAPI documentation.
`search`	—	Search filter is applied if the `match+search` mode is enabled. May include `limit`, `threshold`, `group_ids` parameters. By default, the search is performed within the default group. If the `group_ids` are specified, the search is performed only in these groups. For more information, explore the OpenAPI documentation.
`threshold`	`75`	The similarity threshold, 0-100. Above 75 means that the faces' similarity is verified, below 75 is not.
`serviceTimeout`	`3000`	The service request timeout, ms.
`proxy`	—	Proxy to use, should be set according to the cURL standard.
`proxy_userpwd`	—	Username and password to use for proxy authentication, should be set according to the cURL standard.
`proxy_type`	—	Proxy protocol type, should be set according to the cURL standard.
`childAgeThreshold`	`13`	Minimum age of a child, at which photo comparison is initiated.
`childDocValidityYears`	`5`	Estimated duration of validity for a child's passport, years.

Next Steps

OpenAPI Specification