The API service exposes the following actions in JSON format.
Upload and Match Two Face Photos
This action is used for uploading two face images, which are then processed and evaluated. The result is included in the response to the call and indicates if the two images contain faces of the same person. This is currently a synchronous (blocking) call. The request will return once the processing is complete
Important Note: Depending on the configuration of the IDFM system you might need to authenticate before being able to invoke this action.
- Upload and Match Two Face Photos
This action is used for uploading two face images, which are then processed and evaluated. The result is included in the response to the call and indicates if the two images contain faces of the same person. This is currently a synchronous (blocking) call. The request will return once the processing is complete.
Important Note: Depending on the configuration of the IDFM system you might need to authenticate before being able to invoke this action.
- Signature
The are two APIs for accessing the Face Match functionality, Matchfaces and MatchfacesWithRotation.
[POST] http://{serviceURL}/API/face/Matchfaces Request/Response format: JSON
Body Parameters:
| Parameter Name | Description | Format |
| RequestID | (Optional) The request identifier. If provided, its value will be returned in the result’s “Request ID” key. | |
| InputImages |
(Mandatory)
A list of face images to be processed. See the next table “Input Image Object” for the exact structure of this object, This list should contain two images. | Array of Object |
| MatchingRotation | (Optional) Whether to rotate images by 90 degree increments if a correctly oriented face was not detected. Possible values: “None”, “QueryOnly”, “TargetOnly”,”Both”. If not specified this defaults to Both. |
Input Image Object
| Key | Description | Format |
| Name | (Mandatory) A name to identify the image. Possible values are: “QueryFace” and “TargetFace” | String |
| ImageFormat | (Optional) The format of the image, possible values: “jpg”, “png” and “bmp”. If this parameter is omitted the engine will attempt to auto detect the image type. Please note that the standard image header data must also be included for these formats. | String |
| Data | Image binary data. | String containing Base64 encoding of the face image |
Note: It is advisable to use the same character format for object keys in the request as shown in the documentation (e.g. “InputImages” and not “inputimages”).
Result:
| Key name | Description | Format |
| Result | The processing result. See Table for possible values. | String. One of possible values. |
| HasErrors | Indicates whether an error has happened during request processing that prevented completion. In case of an error the caller should assume the request has not completed and the Result field value should be discarded. In this case, the ErrorDescription field can be checked to get more details on the cause of the error. | Boolean (encoded as a string “true” or “false”) |
| ErrorDescription | Description of the error if an error has happened (HasErrors is “true”). This helps to understand the reason for the error. Please see attached table for a list of common errors. | String |
| RequestId | The request identifier. If parameter “RequestID” was passed in the request, its value will be returned. Otherwise, it will be generated by the engine. It is advised that this identifier is stored along with the request result to be quoted when seeking support about the request. | String |
Possible Processing result values for Result:
| Result | Description |
| Matched | The input face images match and are therefore of the same person. |
| NotMatched | The input face images do not match. |
| NoFace | No face was detected in one or both images |
| Undetermined | The comparison result between the two faces was inconclusive. The engine was not able to find a close enough match to reach a confident decision. Processing different face images, especially of higher quality, may resolve the ambiguous outcome. |
| Identical | The two input images are identical. No attempt to find faces was made. |
Common errors that can happen as part of the request
| Error | Description |
| Invalid Input Image | The engine was not able to process the image provided. Either there is a problem with the image itself (such as being in an unsupported format or the image was not uploaded/encoded correctly) or the engine couldn’t proceed because the image was unsuitable. |
| Out of System Resources | The processing system was out of resources while processing the request. This might be due to an out of memory error or because of a shortage of other resources needed. |
| Internal Error | The engine faced an unexpected problem. If this problem is not specific to some images but happens with all images then it is most likely to be an installation issue with the engine. If the issue is specific to certain images then it’s advisable to report this rare case to GBG IDscan for support. |
[POST] http://{serviceURL}/API/face/MatchfacesWithRotation Request/Response format: JSON
Body Parameters:
| Parameter Name | Description | Format |
| RequestID | (Optional) The request identifier. If provided, its value will be returned in the result’s “Request ID” key. | |
| InputImages | (Mandatory) A list of face images to be processed. See the next table “Input Image Object” for the exact structure of this object, This list should contain two images. | Array of Object |
| MatchingRotation | (Optional) Whether to rotate images by 90 degree increments if a correctly oriented face was not detected. Possible values: “None”, “QueryOnly”, “TargetOnly”,”Both”. If not specified this defaults to Both. |
Input Image Object
| Key | Description | Format |
| Name | (Mandatory) A name to identify the image. Possible values are: “QueryFace” and “TargetFace” | String |
| ImageFormat | (Optional) The format of the image, possible values: “jpg”, “png” and “bmp”. If this parameter is omitted the engine will attempt to auto detect the image type. Please note that the standard image header data must also be included for these formats. | String |
| Data | Image binary data | String containing Base64 encoding of the face image |
Result:
| Key name | Description | Format |
| Result | The processing result. See Table for possible values. | String. One of possible values. |
| HasErrors | Indicates whether an error has happened during request processing that prevented completion. In case of an error the caller should assume the request has not completed and the Result field value should be discarded. In this case, the ErrorDescription field can be checked to get more details on the cause of the error. | Boolean (encoded as a string “true” or “false”) |
| ErrorDescription | Description of the error if an error has happened (HasErrors is “true”). This helps to understand the reason for the error. Please see attached table for a list of common errors. | String |
| RequestId | The request identifier. If parameter “RequestID” was passed in the request, its value will be returned. Otherwise, it will be generated by the engine. It is advised that this identifier is stored along with the request result to be quoted when seeking support about the request. | String |
| TargetRotation | Degree of the rotation made on the target object to be correctly oriented for face match operation; possible values, 0, 90,180, 270. | Float |
| QueryRotation | Degree of the rotation made on the query object to be correctly oriented for face match operation; possible values, 0, 90,180, 270. | Float |
Note: It is advisable to use the same character format for object keys in the request as shown in the documentation (e.g. “InputImages” and not “inputimages”).
Possible Processing result values for Result
| Result | Description |
| Matched | The input face images match and are therefore of the same person. |
| NotMatched | The input face images do not match. |
| NoFace | No face was detected in one or both images |
| Undetermined | The comparison result between the two faces was inconclusive. The engine was not able to find a close enough match to reach a confident decision. Processing different face images, especially of higher quality, may resolve the ambiguous outcome. |
| Identical | The two input images are identical. No attempt to find faces was made. |
Common errors that can happen as part of the request
| Error | Description |
| Invalid Input Image | The engine was not able to process the image provided. Either there is a problem with the image itself (such as being in an unsupported format or the image was not uploaded/encoded correctly) or the engine couldn’t proceed because the image was unsuitable. |
| Out of System Resources | The processing system was out of resources while processing the request. This might be due to an out of memory error or because of a shortage of other resources needed. |
| Internal Error | The engine faced an unexpected problem. If this problem is not specific to some images but happens with all images then it is most likely to be an installation issue with the engine. If the issue is specific to certain images then it’s advisable to report this rare case to GBG IDscan for support. |
2.1.2. Example JSON
Request:
{
"RequestID":”01c000b4-5a71-48f3-99af-179c51489284”,
"InputImages":[
{"Name" : "FirstFace ","ImageFormat":"jpg","Data":"<BASE64 Encoded Image Data>"},
{"Name" : "SecondFace ","ImageFormat":"jpg", Data:"<BASE64 Encoded Image Data>"},
],
“MatchingRotation”: “QueryOnly”
}Response for API Matchfaces:
{
"Result ": "Matched",
"HasErrors": false
"ErrorDescription": “”
}Response for API MatchfacesWithRotation:
{
"Result ": "Matched",
"HasErrors": false
"ErrorDescription": “”
“TargetRotation”: 90
“QueryRotation”:180
}End of upload response example.