Integration with Face API

Integration of the Face API with the Document Reader SDK enables automatic face matching and search using a portrait. The portrait can be extracted from the document Visual Zone or RFID chip, a submitted selfie, or a facial image captured during a liveness transaction.

Define Settings
Configuration

Define Settings

You can define the Face SDK settings in one of the following ways:

Define the settings at service startup. For details, see Integration with Face API.
Define the settings for each request in JSON parameters. See the sections below.

Values specified in JSON take priority. For example, if config.yaml and the request body specify different service addresses, the request body value is used.

To configure the integration with the Face API, use:

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

Configuration

To add a selfie of the document holder for comparison with the photo from the Visual Zone of the document, provide the selfie in the livePortrait parameter:

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

To use the facial image captured during a liveness transaction instead of providing a selfie, specify the liveness transaction ID:

{
    "processParam": {
        "useFaceApi": true,
        "faceApi": {
            "livenessTransactionId": "abc123ab-c123-abc1-23ab-c123abc123ab"
        }
    }
}

Note

If both livePortrait and livenessTransactionId are specified, livenessTransactionId takes priority. The livePortrait image is ignored and is not sent to the Face API.

To add a photo from an external source, for example, a database, provide it in the extPortrait parameter:

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

To crop a selfie from the same image as the document and compare the selfie with the document holder's photo, set oneShotIdentification to true:

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

To configure Face SDK parameters, specify them in the processParam.faceApi object:

{
    "processParam": {
        "useFaceApi": true,
        "faceApi": {
            "livenessTransactionId": "abc123ab-c123-abc1-23ab-c123abc123ab",
            "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
|   └── livenessTransactionId
|   └── url
|   └── mode
|   └── search
|   |   └── limit
|   |   └── threshold
|   |   └── group_ids    
|   └── threshold    
|   └── serviceTimeout
|   └── proxy
|   └── proxy_userpwd
|   └── proxy_type
|   └── childAgeThreshold
|   └── childDocValidityYears

Parameter	Default	Description
`livenessTransactionId`	—	The ID of the liveness transaction from which the captured facial image is used for face matching instead of a submitted selfie. In `match+search` mode, the facial image captured during the liveness transaction is not returned in the response.
`url`	`https://faceapi.regulaforensics.com`	The default https://faceapi.regulaforensics.com URL is for demo purposes only. For production use, purchase an appropriate license. Contact Regula about a Face SDK license.
`mode`	`match`	The processing mode: `match` or `match+search`. `match` compares the persons passed in the request. This mode works by default. `match+search` matches the persons passed in the request and searches 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`	—	The search filter applies when the `match+search` mode is enabled. It may include the `limit`, `threshold`, and `group_ids` parameters. By default, the service searches the default group. If `group_ids` are specified, the service searches only these groups. For more information about search operations, see the OpenAPI documentation.
`threshold`	`75`	The similarity threshold is a value from 0 to 100. Values above 75 verify face similarity. Values below 75 do not verify face similarity.
`serviceTimeout`	`3000`	The service request timeout, ms.
`proxy`	—	The proxy to use. Set it according to the cURL standard.
`proxy_userpwd`	—	The username and password for proxy authentication. Set them according to the cURL standard.
`proxy_type`	—	The proxy protocol type. Set it according to the cURL standard.
`childAgeThreshold`	`13`	The 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