Links

POST/Submission/Step 1

  • KYB submission process is divided into 2 steps, Step1 -> Step 2.
  • Step 1 is the process where we extract text from the ID and get confirmation from users.
  • For Step 1 process, data should be submitted in 'form-data' format.
  • If a submission ID is not created at Step 1, Step 2 can not proceed.

Request URL

curl -X POST "https://rest-api.argoskyc.com/v3/submission/step1"
-H "x-api-key: {yourAPIKey}"
-d ...
  • For Step 1, issuingCountry/email/idType/dImage must be submitted.
  • userid, cf1, cf2, cf3 are options. Please refer to the Input Data table for detail.

Input Data

* means required parameters.
Parameter
Format
Description
*issuingCountry
ISO alpha 3 format of the country the ID card is issued.
*email
string
email address of the KYC applicant
*idType
string
<passport, government_id, drivers_license>
*idImage
file
jpg, jpeg, png file format of the ID front image
(recommendation: 1mb, limit: 2mb)
idBackImage
file
jpg, jpeg, png file format of the ID back image
(recommendation: 1mb, limit: 2mb)
submissionId
string
Unique Id needed for retry
userid
string
custom optional unique identifier of the user
cf1
string
custom optional field
cf2
string
custom optional field
cf3
string
custom optional field

Sample Request 1

curl --location --request POST 'https://rest-api.argoskyc.com/v3/submission/step1' \
--header 'x-api-key: {YOUR_API_KEY}' \
--form 'issuingCountry="USA"' \
--form 'email="[email protected]"' \
--form 'idType="drivers_license"' \
--form '[email protected]"/C:/Users/sampleID.jpg"' \
--form 'cf1="test"' \
--form 'userid="user1"'

Sample Request 2

var myHeaders = new Headers();
myHeaders.append("x-api-key", "{YOUR_API_KEY}");
var formdata = new FormData();
formdata.append("issuingCountry", "USA");
formdata.append("email", "[email protected]");
formdata.append("idType", "drivers_license");
formdata.append("idImage", fileInput.files[0], "/C:/Users/sampleID.jpg");
formdata.append("cf1", "test");
formdata.append("userid", "user1");
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: formdata,
redirect: 'follow'
};
fetch("https://rest-api.argoskyc.com/v3/submission/step1", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

Output Data

  • When Step 1 is successfully completed, documnt_fields, missing_fields, reviewOCRData, SubmissionId, idImage will be returned.
  • 'document_fields' for confirmable data from the submitted ID, 'missing_fields' for data that exist on the ID but failed to read, 'reviewOCRData' for data extracted from the ID.
Response
Description
Submissionid
submission의 ID. *It will be needed at Step 1 retry and Step 2*
reviewOCRData
OCR object that contains ID card information. If OCR fails, this parameter is not returned.
reviewOCRData.ocr_birthDate
YYYY-MM-DD format date of birth
reviewOCRData.accepted_ocr_birthDate
Birthdate recognition: true/false
reviewOCRData.ocr_issueDate
Issued date
reviewOCRData.accepted_ocr_issueDate
Issue date recognition: true/false
reviewOCRData.ocr_expireDate
Expiary date
reviewOCRData.accepted_ocr_expireDate
Expiary date recognition: true/false
reviewOCRData.ocr_lastName
Last name
reviewOCRData.accepted_ocr_lastName
Last name recognition: true/false
reviewOCRData.ocr_firstName
First name
reviewOCRData.accepted_ocr_firstName
First name recognition: true/false
reviewOCRData.ocr_name
Full name
reviewOCRData.accepted_ocr_name
Name recognition: true/false
reviewOCRData.ocr_gender
Gender
reviewOCRData.accepted_ocr_gender
Gender recognition: true/false
reviewOCRData.ocr_nationality
ISO3 code format of nationality if available
reviewOCRData.accepted_ocr_nationality
Nationality recognition: true/false
reviewOCRData.ocr_identityNumber
Identity number
reviewOCRData.accepted_ocr_identityNumber
Identity number recognition: true/false
reviewOCRData.ocr_licenseNumber
License number(Korean only)
reviewOCRData.accepted_ocr_licenseNumber
License numbe recognition: true/false
reviewOCRData.ocr_documentNumber
Document Number
reviewOCRData.accepted_ocr_documentNumber
ocument Number recognition: true/false
idImage
Path of ID front image
idBackImage
Path of ID back image
file_upload
"true" if the ID card front image is successfully received. "false" otherwise.
file_back_upload
"true" if the ID card back image is successfully received. "false" otherwise.
document_fields
Whether the ID has specific information or not. documentnumber, expireDate, gender, identityNumber, issueDate, nationality: true/false
document_fields.expireDate
true/false
document_fields.identityNumber
true/false
document_fields.gender
true/false
document_fields.issueDate
true/false
document_fields.nationality
true/false
document_fields.documentNumber
true/false
missing_fields
It should be in the ID, but the returned data due to OCR recognition fail. ex) [gender, documentNumber, identityNumber]
retry
retryCode + retryMsg format text explaining the reason for being 'incomplete'
kycStatus
<pending, approved, rejected, incomplete> incomplete: Due to insufficient KYC data, failed to get final result. We provide 3 chances in total, and recommend not to stop in the middle
retryCount
Tried count for Step 1, when it becomes 3 the KYC submission will be rejected.

Sample Response

{
"document_fields": {
"gender": false,
"expireDate": true,
"nationality": false,
"documentNumber": true,
"issueDate": true,
"identityNumber": true
},
"file_back_upload": true,
"idBackImage": "https://liveformimages135940-qqa.s3.ap-northeast-2.amazonaws.com/t5ckpk03m4/cb6f4bbd-4ea4-45c6-8580-5e57f02d8066_drivers_license.png",
"missing_fields": [],
"reviewOCRData": {
"accepted_ocr_issueDate": true,
"ocr_issueDate": "YYYY-MM-DD",
"accepted_ocr_expireDate": true,
"ocr_expireDate": "YYYY-MM-DD",
"ocr_gender": "male",
"ocr_nationality": "KOR",
"accepted_ocr_nationality": true,
"ocr_birthDate": "YYYY-MM-DD",
"ocr_identityNumber": "9*****-1******",
"accepted_ocr_birthDate": true,
"accepted_ocr_identityNumber": true,
"accepted_ocr_gender": true,
"ocr_name": "test"

Retry Codes(OK)

Retry Code
Message
Description
mrz_protocol_fail
Failed to detect full MRZ
When failed to detect MRZ code for 'passport'

Error Codes (400 Errors)

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_id_image
Invalid ID image. Please retry with another ID image.
The ID doesn't contain enough information to process KYC.
invalid_request
Failed to find the project. Please check the project ID.
There is no matching project ID. Please check the project ID again.
invalid_project
This project is not available.
When the status of the project if 'closed'. Please contact Help Desk.
missing_parameters
Missing required parameters.
Missing required parameters: issuingCountry, email, idType
invalid_id_type
Invalid id type: Id type must be passport, government_id or drivers_license.
Missing required parameters: government_id, passport, drivers_license
invalid_email
Invalid email address format.
Invalid email address format.
id_image_error
ID image processing error. Please retry.
ID image processing error.
data_processing_error
Data processing error. Please retry.
Data processing error.
save_image_error
ID image save error. Please retry.
ID image save error.
processed_submission
{email} has approved KYC data. No need to submit another KYC.
When the email account aleady has a approved KYC data.
reviewing
{email}’s KYC is currently reviewing. Please wait.
When the email account has a pending submission.
not_an_id
Please take a picture of an ID card.
Invalid ID image(An image of something else other than an ID card)
id_detection_error
ID detection error. Please retry.
An error occurred while detecting ID.
ocr_fail
OCR not supported ID. Please retry with another ID.
When OCR un-supported ID is submitted.
invalid_id
Invalid ID. Please resubmit with another ID.
The ID is not valid anymore due to the policies of the country.
invalid_passport
Passport validation failed. Please resubmit with a clearer image or another ID.
When failed to read the MRZ code of passport or failed to read it accurately.

Caution

For OCR engine to well-function, it needs to recognize a rectangle ID in the image. To do this, it's better that the image has a little bit of padding around the ID. With an image without any buffer, there might be no OCR response.
ID Image Example