POST/Submission/Step 1

Request URL

curl -X POST "https://rest-api.argosidentity.com/v3/submission/step1"
-H "x-api-key: {yourAPIKey}"
-d ...

• KYC 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.

• For Step 1, issuingCountry/email/idType/dImage must be submitted.

• The recommended standard for 'idImage' and 'idBackImage' is 640 x 480 pixels.

• userid, cf1, cf2, cf3 are options. Please refer to the Input Data table for detail.

• Refer to Retry & Error Codes page for retry codes and error codes.

Input Data

* means required parameters.

Parameter	Type	Description
*issuingCountry	string (ISO alpha3)	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, residence_permit, visa, vehicle_registration_certificate, aadhaar, pancard, universal
*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 veirifying ID needed for further steps, it is valid for 4 hours.
userid	string	custom optional unique identifier of the user
cf1	string	custom optional field
cf2	string	custom optional field
cf3	string	custom optional field
customOptions	serialized JSON object in string	Regardless of project options, an object to apply options for each submission. Convert to string and transmit.
customOptions. blacklistCountries	boolean	Turn OFF options for blacklisted countries for the respective submission ('false' only possible).
customOptions. approvePeriod	boolean	Turn OFF options for the approved duplicate submission prevention period for the respective submission ('false' only possible).
customOptions. rejectPeriod	boolean	Turn OFF options for the rejected duplicate submission prevention period for the respective submission ('false' only possible).
customOptions. ageLimit	boolean	Turn OFF options for age restrictions for the respective submission ('false' only possible).
customOptions. rejectDuplicateUser	boolean	Turn ON/OFF options for duplicate submission prevention for the respective submission ('true' and 'false' both possible).

• Detailed explanation of 'customOptions':

  • 'customOptions' itself is an object containing a boolean property indicating the use of options internally.

  • However, the entire object must be converted to a string for transmission.

  • It can only be submitted in Step 1 and also referenced in Step 2.

  • Only 'rejectDuplicateUser' can be toggled ON/OFF.

• Example

// javascript
let customOptions = {
    blacklistCountries: false,
    approvePeriod: false,
    rejectPeriod: false
};

customOptions = JSON.stringify(customOptions);

// python
import json

custom_options = {
    'blacklistCountries': False,
    'approvePeriod': False,
    'rejectPeriod': False
}

json_string = json.dumps(custom_options)
print(json_string)

For 'issuingCountry', 'idType' and rear side collection, please check the file at ID Type & Rearside Collection page.

Sample Request 1

curl --location --request POST 'https://rest-api.argosidentity.com/v3/submission/step1' \
--header 'x-api-key: {YOUR_API_KEY}' \
--form 'issuingCountry="USA"' \
--form 'email="[e-mail]"' \
--form 'idType="drivers_license"' \
--form 'idImage=@"/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", "[e-mail]");
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.argosidentity.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
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 1) When using Universal Mode, Array format when OCR recognition fails 2) Others, single object type
document_fields.expireDate	true/false
document_fields.idNumber	true/false
document_fields.identityNumber	true/false
document_fields.gender	true/false
document_fields.issueDate	true/false
document_fields.nationality	true/false
document_fields.number	true/false
document_fields.name	true/false
document_fields.birthDate	true/false
document_fields.serialNumber	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://sampleID_back.jpg",
    "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 & Error Codes

• Refer to Retry & Error Codes page for retry codes and error codes.

Step 1 Sample

Request URL

curl -X POST "https://rest-api.argosidentity.com/v3/submission/step1" \
-H "x-api-key: {yourAPIKey}" \

Sample Request

curl --location --request POST 'https://rest-api.argosidentity.com/v3/submission/step1' \
--header 'x-api-key: {yourAPIKey}' \
--form 'issuingCountry="USA"' \
--form 'email="{email}"' \
--form 'idType="drivers_license"' \
--form 'idImage=@"/C:/Users/sampleID.jpg"' \
--form 'idBackImage=@"/C:/Users/sampleID_back.jpg"' \
--form 'cf1="test"' \
--form 'userid="user1"'

Sample Response

{
    "document_fields": {
				"gender": true,
        "expireDate": true,
        "nationality": true,
        "number": true,
        "issueDate": true,
        "name": true,
        "serialNumber": false,
        "birthDate": true,
        "idNumber": true
    },
		"file_back_upload": true,
    "idBackImage": "https://sampleID_back.jpg",
    "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": "USA",
        "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"
    },
    "file_upload": true,
    "submissionId": "{submission_id}",
    "idImage": "https://sampleID.jpg"
}

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 Backside Collection

For the IDs with 'ID Card Back' column 'True', we collect the back of the ID. It will be saved depending on the detailed type. Please check the file at ID Type & Rearside Collection.