Links

POST/Submission/Step 2

  • At Step 2, data should be transmitted based on the Step 1 response.
  • Step 2 is where we compare face, compare OCR data and user-confirmed data and get address information or address image.
  • For Step 2 process, data should be submitted in 'form-data' format.
  • For Step 2, you can send the selfies 3 times maximum(1st try + 2 retries). If 1st try of Step 2 is processed, KYC submission should be done in 24 hours from Step 1 start time. (Because 'Step 2 processed but no KYC result yet' submission will be rejected after 24 hours.)
  • You can check the submitted data at Dashboard or get it by Get/Submission API.
  • When collect-address option is on, globalCode, compoundCode, formatted_address, address_input, addressdetail are required. Get these information through Post/Address_code API.
  • Any of globalCode, compoundCode, formatted_address must be submitted.
  • 'address_input' is the user-typed address, 'address_detail' is detailed address. Both are optional.

Request URL

curl -X POST "https://rest-api.argoskyc.com/v3/submission/step2"
-H "x-api-key: {yourAPIKey}"
-form ...
  • Submission ID created at Step 1 process must be included.
  • SubmissionId, faceimage, name, date_of_birth are required parameters.

Input Data

* means required parameters.
Parameter
Format
Description
*submissionId
string
The unique submission ID received from step 1.
*faceImage
file
A selfie image that has only one face. If multiple faces are detected, it will respond with retry.
(Recommended size: 1mb, limit: 2mb)
*name
string
The name should be in 'Fullname' format. (First_Name & Last_Name)
*date_of_birth
string
YYYY-MM-DD
gender
string
<male, female>
nationality
string
ISO alpha 3 format of nationality. The nationality is not necessarily same as the ID issued country.
identity_number
string
This is unique identity number for Korean photo IDs.
license_number
string
(KOREAN DRIVER LICENSE ONLY) 12 code license number for ID verification ex) 12 Digit (12-34-567890-12 ) or
2 Korean characters & 10 Digit (서울-12-345678-90)
document_number
string
Document number of ID(Passport number, License number etc...)
serial_number
string
(Korean Driver's License Only)6 letter unique serial number in Korean driver's license.
date_of_issue
string
YYYY-MM-DD format of ID issue date.
date_of_expiry
string
YYYY-MM-DD format of ID expiry date.
addressImage
file
Address document image to verify the address information.
(Recommended size: 1mb, limit: 2mb)
address_street
string
street
address_city
string
city
address_state
string
state
address_country
string
country code in ISO 3 format
address_zipcode
string
zip-code (postal code)
globalCode
string
Detailed code from the address (ex. 87C4VXX7+39)
compoundCode
string
Detailed code, city and country from the address (ex. VXX7+39 Washington, DC, USA)
formatted_address
string
Transformed address from detailed code
address_input
string
User input address(When user input address data is needed)
address_detail
string
User input detailed address(When user input detail address data is needed)

Sample Request 1

curl --location --request POST 'https://rest-api.argoskyc.com/v3/submission/step2' \
--header 'x-api-key: {YOUR_API_KEY}' \
--form '[email protected]"/C:/Users/face.jpg"' \
--form 'name="Jhon Smith"' \
--form 'nationality="USA"' \
--form 'date_of_birth="1998-11-11"' \
--form 'date_of_issue="2016-11-11"' \
--form 'submissionId="d76h19l46m****"' \
--form 'identity_number="981112-1******"' \
--form 'gender="male"'

Sample Request 2

var myHeaders = new Headers();
myHeaders.append("x-api-key", "{YOUR_API_KEY}");
var formdata = new FormData();
formdata.append("faceImage", fileInput.files[0], "/C:/Users/face.jpg");
formdata.append("name", "Jhon Smith");
formdata.append("nationality", "USA");
formdata.append("date_of_birth", "1998-11-11");
formdata.append("date_of_issue", "2016-11-11");
formdata.append("submissionId", "d76h19l46m****");
formdata.append("identity_number", "981112-1******");
formdata.append("gender", "male");
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: formdata,
redirect: 'follow'
};
fetch("https://rest-api.argoskyc.com/v3/submission/step2", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

Output Data

Response
Description
kycStatus
<pending, approved, rejected, incomplete>
If kycStatus is 'pending', the kyc submission is completed, but it will be manually reviewed to finalize whether the submission is approved or rejected.
*If kycStatus is 'incomplete', the KYC is not accepted due to invalid KYC data and step 2 retry is recommended until kycStatus returns 'pending', 'approved' or 'rejected'.
faceSimilarityScore
The face similarity score between the face in the ID and the selfie image. The closer the score is to 100, it is more likely that the two faces are matched(0~100).
livenessScore
The liveness score evaluates whether the face in the selfie image is a live person or not. The closer the score is to 100, it is more likely that the image is a picture of a live person(1~100).
verificationResult
<success, fail>
retryCount
Retry count of Step 2. If Step 2 fails at retry count 2, the KYC is rejected.
retry
If the kycStatus is "incomplete", message is shown to explain why the KYC application is not accepted.

Sample Response - Approved

{
"faceSimilarityScore": 99,
"livenessScore": 74,
"kycStatus": "approved",
"retryCount": 0
}

Sample Response - Rejected

{
"livenessScore": 74,
"kycStatus": "rejected",
"retryCount": 3
}

Sample Response - Pending

{
"faceSimilarityScore": 99,
"livenessScore": 74,
"kycStatus": "pending",
"retryCount": 0
}

Sample Response - Incomplete

{
"retry": [
{
"retryCode": "face_compare_fail",
"retryMsg": "Face compare failed: no matching face"
}
],
"kycStatus": "incomplete",
"retryCount": 1
}

Retry Code (200 OK)

Retry Code
Message
Description
identity_verification_fail
ID verification failed: {message}. Please check the ID data.
Authentication failed.
no_face
Detect face failed: No face detected, the face image should have a face. Please retry.
When a face is not detected.
multiple_faces
Detect face failed: face image should have only one face. Please retry.
When more than two faces are detected.
face_compare_underscore
The face doesn’t match. Please retry with another face image.
When face compare score is lower than 85.
face_compare_fail
Failed to find a matching face. Please retry with another face image.
When there is no matching face.
liveness_fail
Liveness fail. Please retry with another face image.
When Liveness score is lower than 50.

Error Codes (400 Errors)

  • When failed at Step 2, error code and message are provided.
Error Code
Message
Description
invalid_payload
Failed to parse the input data.
It occurs at API calls, mostly when no image file or wrong image file has submitted.
invalid_request
Failed to find the project. Please check the API key.
There is no matching project ID. Please check the project ID again.
invalid_face_image
Invalid face image. Please retry with another face image.
No selfie image or wrong selfie image.
invalid_address_image
Invalid address image. Please retry with another address image.
No address proof image or wrong address proof image.
invalid_submission_id
Invalid submission ID error. Please check the submission ID.
Invalid submission ID(Created from Step 1)
no_submission
Fail to find the submission data. Please contact CS center.
Fail to find the submission data.
processed_submission
This submission is already processed.
When the submission is already compelted.
unauthorized
Invalid API key. Please check.
When there is something wrong with the API key.
missing_address
Missing address data information.
When the address collection option is on, but no address data has submitted.
missing_params
Missing required identity information.
Missing parameters: name, date_of_birth or parameters for authentication below. Korean Government ID: fullName, issueDate, identityNumber Korean Driver's Licnse: fullName, birthDate, licenseNumber, serialNumber
unexpected_error
Failed to submit KYC.
Failed at final work such as DB save, webhook, sending emails.
face_detect_error
Failed to detect a face.
Face detection error.
face_compare_error
Failed to compare face.
Face compare error.
liveness_error
Liveness fail: {message}. Please retry.
Liveness FAIL. (When the face is too small or large, there is more than two faces.)

Caution

To compare the faces fluently the ratio of a face should be appropriate in the image. When it's too large or small, face comparison might fail. Below image is the guideline for Argos Liveform and examples of selfie images.
Liveform Guide
Selfie examples