Skip to main content
Before you start — FaceAuth has two delivery methods.This API is the client-implemented camera method: your app captures the selfie and posts the image file. This method does not support Active Liveness, so it cannot block spoofing attempts such as screen replays or printed photos. If physical-presence (liveness) verification matters, use the Face Auth URL method instead.→ Method comparison and URL setup: Add-on Getting Started · FACE AUTH guide
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.