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.
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.
* 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 |
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"'
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));
- 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. |
{
"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 Code | Message | Description |
|---|---|---|
mrz_protocol_fail | Failed to detect full MRZ | When failed to detect MRZ code for 'passport' |
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. | |
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. |
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
Last modified 12d ago