Notes
  • The authentication result is determined based on option settings and threshold values, returning either approved or rejected.
  • Recommended faceImage specifications: 960 x 720
  • How to check submissionId: Log in to the dashboard, go to Settings > Liveform URL, and complete the ID Check process. Once ID Check is approved, you can find the submissionId data in the User Management menu > Submission List in the dashboard.
    • The final status of the ID Check must be approved.
  • API Key Information: A separate API Key is required from the existing liveform API Key. You can check your Add-on API Key under Getting Started.

​
1. Base URL

POST/faceauth
https://rest-api.argosidentity.com/v3/faceauth

​
2. Authentication

Include the API key in the x-api-key header:
x-api-key
x-api-key: {yourAPIKey}

​
3. Request Example

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

​
4. Request Body

The request body must be in JSON format. The following are the field descriptions:
​
submissionId
string
required
Unique identifier for each KYC submission.
FaceAuth can only proceed if the corresponding submission (submissionId) is approved.
​
faceImage
file
required
Upload the user’s selfie image as a file. If PPE (head/face protective equipment) options are enabled, ensure that all safety equipment is clearly visible in the image for accurate recognition.
​
userId
string
A unique identifier for the KYC submitter as defined by the customer.
​
cf1
string
Custom field 1 value.
​
cf2
string
Custom field 2 value.
​
cf3
string
Custom field 3 value.

​
5. Response

​
5-1. Success Response

result.json
{
    "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
    }
}

​
5-2. Rejection Response

result.json
{
    "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_score": 93.3,
        "head_cover_score": 87
    },
    "fail_code": [
        "Face_Occluded_fail"
    ],
    "rejected_comment": [
        "Face is occluded and the confidence is higher than the threshold."
    ]
}

​
5-3. Response Data

Field NameData TypeDescription
authentication_idStringUnique ID for the faceAuth submission.
auth_statusStringThe final result of faceAuth, returning either approved (success) or rejected (failure).
scoreObjectRecognition scores based on the selected options. Properties may include face_similarity_score, occluded_score, face_cover_score, and head_cover_score.
create_timeStringThe date and time when faceAuth was submitted (UTC+0).
fail_codeArrayIf the status is rejected, a failure code is returned.
rejected_commentArrayIf the status is rejected, a detailed reason for the failure is returned.

​
6. Error Codes

​
6-1. Failure Codes

Failure CodeRejection CommentDescription
face_compare_underscoreFace compare similarity score is lower than the thresholdFace similarity score is below the threshold.
Face_Occluded_failFace is occludedThe face is obstructed.
Face_cover_failProtection equipment is not found on FaceFace protective equipment is missing.
Head_cover_failProtection equipment is not found on HeadHead protective equipment is missing.

​
6-2. Error Codes

Error CodeMessageDescription
invalid_data_formatData parsing error. Please check input data.The provided data format is incorrect. Verify the data format.
required_field_missingRequired field is missingA required field is missing. Ensure submissionId, faceImage, and API Key are included.
Invalid_submissionIdFail to find the submission dataThe KYC submission does not exist.
Invalid_projectIdFail to find the project dataThe FaceAuth project does not exist.
invalid_submission_statusThe submission must be approved to process face authenticationThe KYC submission status is not approved.
image_converting_errorImage converting errorThe image format is invalid. Submit the image as form-data (base64 format is not supported).
image_processing_errorImage processing errorAn error occurred while processing the image data.
detection_server_errorCannot finish process of detecting faceAn error occurred in the face comparison verification module.
no_faceFace is not detectedNo face was detected in the submitted faceImage.
data_processing_errorData processing errorAn error occurred while retrieving or storing data.