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="sample@email.com"' \
--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", "sample@email.com");
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.

PreviousSubmit Via API NextStep 1 Retry

Last updated 4 months ago