POST/FaceAuth

The faceAuth compares the faceImage submitted with either the selfie image from a prior KYC Submission or the idCard image(if the selfie option was not used.).

• The authentication result (approved <> rejected) is returned based on option usage and defined thresholds.

• To proceed, a approved status from the KYC Submission is a prerequisite.

• The faceAuth submission is dependent on a sub-project under the existing KYC Project.

• It is mandatory to use a dedicated faceAuth API Key when sending the request.

• Option usage and individual thresholds can be configured and changed within the detailed screen of the FaceAuth project on the dashboard.

• The detailed information of the submitted KYC data can be reviewed on the dashboard (https://admin.argoskyc.com).

• It is recommended to submit faceAuth in Body/form-data format.

• The standard recommended dimensions for the face image are 960 x 720.

Input data

To submit a Face Auth request, certain parameters are required.

• 'submissionId' and 'faceImage' are mandatory parameters that must be entered.

• 'userId', 'cf1', 'cf2', and 'cf3' are optional parameters. (If using Liveform, please enter these in accordance with the Query String format.)

Parameter	Format	requirement	Description
submissionId	string	*required	Enter the KYC Submission ID. Face Auth can only proceed if the KYC result is marked as approved.
faceImage	file	*required	Enter the user's selfie image as a file. If utilizing the PPE (head cover, face cover) option, it is essential for the user's safety equipment to be fully captured in the image for accurate recognition.
userId	string	optional	If needed, enter the user ID used withing your company.
cf1	string	optional
cf2	string	optional
cf3	string	optional

Output Data

Here is the list of data that can be viewed upon the completion of a Face Auth submission.

Property	Format	Description
authentication_id	string	A unique ID for each Face Auth submission.
auth_status	string	The final result of Face Auth, returning either approved (successful) or rejected (failed).
score	object	A score for the recognition result based on the used options. Depending on the options, properties such as "face_similarity_score", "occluded_score", "face_cover_score", and "head_cover_score" may be included.
create_time	string	The timestamp when the Face Auth was submitted.
fail_code	Array	If rejected, a failure code is returned.
rejected_comment	Array	If rejected, a detailed message explaining the reason for the failure is returned.

Fail Codes (200 Rejected)

fail_code	rejected_comment	description
face_compare_underscore	face compare similarity score is lower than threshold	If the facial similarity score is lower than the threshold.
Face_Occluded_fail	face is occluded	In the case where the face is obscured.
Face_cover_fail	Protection equipment is not found on Face	In the case where no protective gear is detected on the face.
Head_cover_fail	Protection equipment is not found on Head	In the case where no protective gear is detected on the head.

Error Codes (400 error)

If a submission in Face Auth fails, a message is provided along with an error code detailing the reason for the failure.

error_code	Message	description
invalid_data_format	data parsing error. please check input data	If the input parameter format is inappropriate, please check the data format.
required_field_missing	required field is missing	If a required parameter is missing, please verify the two mandatory parameters and the API key.
Invalid_submissionId	Fail to find the submission data	If the KYC submission does not exist.
Invalid_projectId	Fail to find the project data	If the FaceAuth project does not exist.
invalid_submission_status	The submission must be approved to process face authentication	If the authentication status of the KYC submission is not marked as approved.
image_converting_error	image converting error	If the image format is not appropriate. Submit the image file as form-data (in base64 format).
image_processing_error	image processing error	If an error occurs during image data processing.
detection_server_error	cannot finished process of detecting face	If an error occurs in the facial image comparison verification module.
no_face	face is not detected	If a face is not recognized in the submitted faceImage.
data_processing_error	data processing error	If an error occurs during data retrieval or storage.

Request URL

Instructions on 'How to Submit Face Auth':

• It is mandatory to enter both the URL and the x-api-key.

curl -X POST "https://rest-api.argoskyc.com/v3/faceauth" \
-H "x-api-key: {yourAPIKey}" \

Sample Request

After completing the KYC process, it is mandatory to enter the unique identification ID of the KYC data ('submissionId'). Additionally, the corresponding KYC submission must be in an approved state.

• Both 'submissionId' and 'faceImage' are required input data.

• The input data must be entered according to the specified format.

curl --location --request POST 'https://rest-api.argoskyc.com/v3/faceauth' \
--header 'x-api-key: {yourAPIKey}' \
--form 'faceImage=@"/C:/Users/face.jpg"' \
--form 'submissionId= "{submissionId}"' \

Sample Response - Approved

{
    "authentication_id": "{authentication_id}",
    "auth_status": "approved",
    "create_time": "2023-08-08T07:04:48.633Z",
    "score": {
				"face_similarity_score": 99.5,
        "occluded_score": 99.9
    }
}

Sample Response - Rejected

{
    "authentication_id": "{authentication_id}",
    "auth_status": "rejected",
    "create_time": "2023-08-08T07:04:48.633Z",
    "score": {
        "face_similarity_score": 83.6,
        "occluded_score": 40,
        "face_cover_socre": 93.3,
        "head_cover_socre": 87
    },
    "fail_code": [
        "Face_Occluded_fail",
    ],
    "rejected_comment": [
        "face is occluded and the confidence is higher than threshold.",
    ]
}