POST/Submission/Step 1

STEP 1

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

KYC 제출 단계는 Step1 -> Step2로 나뉩니다.
Step1은 신분증의 정보를 추출하고 확인하는 단계입니다.
Step1은 form-data 형식으로 제출해야 합니다.
Step1에서 submission_id(제출 ID)가 생성되지 않았다면 Step2를 진행할 수 없습니다.
Step1 에서는 발급 국가, 신분증 타입, 이메일, 신분증 이미지 데이터를 필수로 요구합니다.
idImage와 idBackImage 표준 권장 사양은 640 x 480 픽셀 입니다.
userid, cf1, cf2, cf3 값은 필수로 요구하지 않습니다. 상세 내용은 하단의 Input Data 표를 참조하세요.
Retry code와 error code는 Retry/Error/Reject Codes 페이지에서 확인해 주세요.

Input Data

*이 붙은 것은 필수 파라미터 입니다.

파라미터	타입	설명
*issuingCountry	sting (ISO alpha3)	ISO alpha 3 형식의 신분증이 발행된 국가
*email	string	KYC 제출자의 이메일 주소
*idType	string	government_id, passport, drivers_license, residence_permit, vehicle_registration_certificate, visa, aadhaar, pancard, universal
*idImage	file	jpg, jpeg, png 파일 형식의 신분증 앞면 이미지 (권장 용량: 1mb, 최대: 2mb)
idBackImage	file	jpg, jpeg, png 파일 형식의 신분증 뒷면 이미지 (권장 용량: 1mb, 최대: 2mb)
submissionId	string	각각의 submission을 구분하는 고유의 구분자로 이후 프로세스 진행에 필요하며, createTime으로부터 4시간 동안 유효
userid	string	사용자의 사용자 지정 고유 식별자
cf1	string	사용자 정의 옵션 필드
cf2	string	사용자 정의 옵션 필드
cf3	string	사용자 정의 옵션 필드
customOptions	serialized JSON object in string	프로젝트옵션과 무관하게, 각각의 submission 별로 옵션을 적용하기 위한 객체(object). String 으로 변환하여 전송.
customOptions. blacklistCountries	boolean	블랙리스트 국가에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. approvePeriod	boolean	Approved 중복 제출 방지 기간에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. rejectPeriod	boolean	Rejected 중복 제출 방지 기간에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. ageLimit	boolean	연령 제한에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)
customOptions. rejectDuplicateUser	boolean	중복 제출 방지에 대한 옵션을 해당 submission 에 대하여 ON / OFF 함 (’true’ 및 ‘false’ 모두 가능)

파라미터

타입

설명

*issuingCountry

sting (ISO alpha3)

ISO alpha 3 형식의 신분증이 발행된 국가

*email

string

KYC 제출자의 이메일 주소

*idType

string

government_id, passport, drivers_license, residence_permit, vehicle_registration_certificate, visa, aadhaar, pancard, universal

*idImage

file

jpg, jpeg, png 파일 형식의 신분증 앞면 이미지

(권장 용량: 1mb, 최대: 2mb)

idBackImage

file

jpg, jpeg, png 파일 형식의 신분증 뒷면 이미지 (권장 용량: 1mb, 최대: 2mb)

submissionId

string

각각의 submission을 구분하는 고유의 구분자로 이후 프로세스 진행에 필요하며, createTime으로부터 4시간 동안 유효

userid

string

사용자의 사용자 지정 고유 식별자

cf1

string

사용자 정의 옵션 필드

cf2

string

사용자 정의 옵션 필드

cf3

string

사용자 정의 옵션 필드

customOptions

serialized JSON object in string

프로젝트옵션과 무관하게, 각각의 submission 별로 옵션을 적용하기 위한 객체(object). String 으로 변환하여 전송.

customOptions. blacklistCountries

boolean

블랙리스트 국가에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)

customOptions. approvePeriod

boolean

Approved 중복 제출 방지 기간에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)

customOptions. rejectPeriod

boolean

Rejected 중복 제출 방지 기간에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)

customOptions. ageLimit

boolean

연령 제한에 대한 옵션을 해당 submission 에 대하여 OFF 함 (’false’ 만 가능)

customOptions. rejectDuplicateUser

boolean

중복 제출 방지에 대한 옵션을 해당 submission 에 대하여 ON / OFF 함 (’true’ 및 ‘false’ 모두 가능)

‘customOptions’ 상세 설명
- customOptions 자체는 내부에 옵션 사용 여부(boolean) 프로퍼티를 담은 객체(Object)임.
- 단, 객체 전체를 String 으로 변환하여 전송해야 함.
- 오직 Step1 에서만 제출 가능하며, Step2 에서도 이를 참조함.
- rejectDuplicateUser 의 경우에만 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)

*'issuingCountry'와 'idType', 뒷면 수집 여부는 '신분증별 뒷면 수집 여부' 페이지를 참고해 주세요.

Sample Request 1

curl --location --request POST 'https://rest-api.argoskyc.com/v3/submission/step1' \
--header 'x-api-key: {YOUR_API_KEY}' \
--form 'issuingCountry="KOR"' \
--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", "KOR");
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.argoskyc.com/v3/submission/step1", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Output Data

Step1이 오류없이 정상적으로 제출 되었다면 documnt_fields, missing_fields, reviewOCRData, SubmissionId, idImage를 결과 값으로 확인할 수 있습니다.
document_fields에는 신분증에서 확인할 수 있는 데이터들, missing_fields에는 신분증에 데이터가 존재하지만 읽어오지 못한 데이터들, reviewOCRData에는 신분증에서 추출된 데이터들을 확인할 수 있습니다.

응답	설명
Submissionid	submission의 ID. *해당 ID는 step1 재시도와 step 2에서 필요합니다.
reviewOCRData	신분증 정보를 포함하는 OCR 오브젝트. 만약 OCR 인식에 실패하면 이 파라미터는 반환되지 않음.
reviewOCRData.ocr_birthDate	YYYY-MM-DD 형식의 생년월일
reviewOCRData.accepted_ocr_birthDate	생년월일 인식 성공 여부 (true/false)
reviewOCRData.ocr_issueDate	발급 일자
reviewOCRData.accepted_ocr_issueDate	발급 일자 인식 성공 여부 (true/false)
reviewOCRData.ocr_expireDate	만료 일자 (이용 가능할 때)
reviewOCRData.accepted_ocr_expireDate	만료 일자 인식 성공 여부 (true/false)
reviewOCRData.ocr_lastName	성
reviewOCRData.accepted_ocr_lastName	성(last name) 인식 성공 여부 (true/false)
reviewOCRData.ocr_firstName	이름
reviewOCRData.accepted_ocr_firstName	이름(frist name) 인식 성공 여부 (true/false)
reviewOCRData.ocr_name	전체 이름
reviewOCRData.accepted_ocr_name	이름 인식 성공여부 (true/false)
reviewOCRData.ocr_gender	성별
reviewOCRData.accepted_ocr_gender	성별 인식 성공여부 (true/false)
reviewOCRData.ocr_nationality	ISO3 코드 형식의 국가코드
reviewOCRData.accepted_ocr_nationality	국적 인식 성공여부 (true/false)
reviewOCRData.ocr_identityNumber	사용자 고유의 식별번호
reviewOCRData.accepted_ocr_identityNumber	사용자 고유 식별번호 인식 성공여부 (true/false)
reviewOCRData.ocr_licenseNumber	운전면허번호(한국 only)
reviewOCRData.accepted_ocr_licenseNumber	운전면허번호 인식 성공여부 (true/false)
idImage	신분증 앞면 사진 경로
idBackImage	신분증 뒷면 사진 경로
file_upload	신분증 사진이 성공적으로 받아졌으면 “true”, 그렇지 않을 때는 “fail”
file_back_upload	신분증 뒷면 사진이 성공적으로 받아졌으면 “true”, 실패 시 “fail”
document_fields	아래의 항목이 인식된 신분증에 존재하는지 여부 documentnumber, expireDate, gender, identityNumber, issueDate, nationality: true/false 1) Universal Mode 사용 시, OCR 인식 실패 시 Array 형태 2) 그 외, 단일 Object 형태

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	인식된 신분증에 있어야 하지만 OCR인식 실패로 읽지 못한 항목 예시) [gender, documentNumber, identityNumber]
retry	kycStatus가 ‘incomplete”인 경우에, 재시도 사유를 retryCode와 retryMsg로 보여줍니다.
kycStatus	<pending, approved, rejected, incomplete> 'incomplete'는 불충분한 KYC 데이터로 인해 제출이 완료되지 못한 상태입니다. 셀피 제출 단계에서 총 3번의 기회가 주어집니다.
retryCount	Step 1의 재시도 횟수. Step 1 시도 횟수가 3회가 되면 KYC는 자동으로 거절됩니다.

응답

설명

Submissionid

submission의 ID. *해당 ID는 step1 재시도와 step 2에서 필요합니다.

reviewOCRData

신분증 정보를 포함하는 OCR 오브젝트. 만약 OCR 인식에 실패하면 이 파라미터는 반환되지 않음.

reviewOCRData.ocr_birthDate

YYYY-MM-DD 형식의 생년월일

reviewOCRData.accepted_ocr_birthDate

생년월일 인식 성공 여부 (true/false)

reviewOCRData.ocr_issueDate

발급 일자

reviewOCRData.accepted_ocr_issueDate

발급 일자 인식 성공 여부 (true/false)

reviewOCRData.ocr_expireDate

만료 일자 (이용 가능할 때)

reviewOCRData.accepted_ocr_expireDate

만료 일자 인식 성공 여부 (true/false)

reviewOCRData.ocr_lastName

성

reviewOCRData.accepted_ocr_lastName

성(last name) 인식 성공 여부 (true/false)

reviewOCRData.ocr_firstName

이름

reviewOCRData.accepted_ocr_firstName

이름(frist name) 인식 성공 여부 (true/false)

reviewOCRData.ocr_name

전체 이름

reviewOCRData.accepted_ocr_name

이름 인식 성공여부 (true/false)

reviewOCRData.ocr_gender

성별

reviewOCRData.accepted_ocr_gender

성별 인식 성공여부 (true/false)

reviewOCRData.ocr_nationality

ISO3 코드 형식의 국가코드

reviewOCRData.accepted_ocr_nationality

국적 인식 성공여부 (true/false)

reviewOCRData.ocr_identityNumber

사용자 고유의 식별번호

reviewOCRData.accepted_ocr_identityNumber

사용자 고유 식별번호 인식 성공여부 (true/false)

reviewOCRData.ocr_licenseNumber

운전면허번호(한국 only)

reviewOCRData.accepted_ocr_licenseNumber

운전면허번호 인식 성공여부 (true/false)

idImage

신분증 앞면 사진 경로

idBackImage

신분증 뒷면 사진 경로

file_upload

신분증 사진이 성공적으로 받아졌으면 “true”, 그렇지 않을 때는 “fail”

file_back_upload

신분증 뒷면 사진이 성공적으로 받아졌으면 “true”, 실패 시 “fail”

document_fields

아래의 항목이 인식된 신분증에 존재하는지 여부 documentnumber, expireDate, gender, identityNumber, issueDate, nationality: true/false 1) Universal Mode 사용 시, OCR 인식 실패 시 Array 형태 2) 그 외, 단일 Object 형태

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

인식된 신분증에 있어야 하지만 OCR인식 실패로 읽지 못한 항목 예시) [gender, documentNumber, identityNumber]

retry

kycStatus가 ‘incomplete”인 경우에, 재시도 사유를 retryCode와 retryMsg로 보여줍니다.

kycStatus

<pending, approved, rejected, incomplete> 'incomplete'는 불충분한 KYC 데이터로 인해 제출이 완료되지 못한 상태입니다. 셀피 제출 단계에서 총 3번의 기회가 주어집니다.

retryCount

Step 1의 재시도 횟수. Step 1 시도 횟수가 3회가 되면 KYC는 자동으로 거절됩니다.

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"
    },
    "file_upload": true,
    "submissionId": "3pjx8m9l46*****",
    "idImage": "https://sampleID_back.jpg"
}

Retry & Error Codes

Retry code와 error code는 Retry/Error/Reject Codes 페이지에서 확인해 주세요.

Step 1 Sample

Request URL

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

Sample Request

curl --location --request POST 'https://rest-api.argoskyc.com/v3/submission/step1' \
--header 'x-api-key: {yourAPIKey}' \
--form 'issuingCountry="KOR"' \
--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": "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"
    },
    "file_upload": true,
    "submissionId": "{submission_id}",
    "idImage": "https://sampleID.jpg"
}

주의사항

OCR 텍스트 추출이 원활하게 되기 위해서는 이미지에 사각형의 신분증이 존재한 다는 것을 알 수 있도록 약간의 여백이 필요합니다. 신분증의 네 모서리를 타이트하게 잘라 제출하면 OCR 추출 결과물이 없을 수 있습니다.

신분증별 뒷면 수집 여부

STEP1 단계에서'ID Card Back' 열이 'TRUE'인 신분증은 뒷면을 수집합니다. 저장 여부는 신분증 상세 종류에 따라 달라질 수 있습니다. 자세한 내용은 'Input Data' 영역의 첨부파일을 확인해주세요.

PreviousAPI 제출 NextStep 1 Retry

Last updated 5 days ago