KR

API 가이드(구버전)

https://rest-api.argoskyc.com/v2/submission

아르고스 API를 이용하여 고객의 KYC 폼 데이터를 제출하고 KYC 진행 상황을 확인할 수 있습니다.

아르고스 API는 RESTful Endpoints와 기본인 HTTP Method를 사용합니다.

  • 응답 데이터에는 요청 상태와 발생 가능한 오류 코드가 포함됩니다.

  • 모든 응답 데이터는 JSON 형식으로 제공됩니다.

  • 토큰 인증을 사용합니다.

  • 모든 요청은 HTTPS에서 수행해야 합니다. HTTP 요청은 실패 됩니다.

1. 시작하기

API를 이용하기 위해서는 유효한 API 키가 필요합니다. API 키는 서비스 시작 전 전달되며, 찾을 수 없는 경우 헬프데스크로 문의 부탁 드립니다.

2. 인증

API는 토큰에 기반한 인증을 이용합니다. API를 이용하기 위해서는 반드시 아르고스에서 제공한 API만 이용해야 합니다.

HTTP 헤더로 인증하기

쿼리와 함께 API 키를 HTTP 헤더로 보낼 수 있습니다.

API 키는 메소드 요청 헤더에 'x-api-key: {yourAPIKey}’로 포함되어야 합니다.

curl -H "x-api-key: {yourAPIKey}" "https://rest-api.argoskyc.com/..."

오류

일반 HTTP 응답 코드로 응답합니다. 성공하면 2xx 코드로 표시됩니다. 4xx는 클라이언트에서 전송된 정보에 오류가 있을 때 발생하며, 5xx는 Argos 서버에서 오류가 있을 때 발생합니다.

오류코드

HTTP CodeMessage설명

400

Invalid Query String parameters

클라이언트 에러 (예. 잘못된 형식의 요청 구문, 잘못된 요청 메시지 프레임)

403

Forbidden

API 키에 문제가 있습니다.

413

Request Entity Too Large

요청이 서버가 의도하거나 수행할 수 있는 것보다 큽니다.

500

Internal Server Error

아르고스 서버의 에러일 수 있습니다. 아르고스 팀에 문의하세요.

502

Bad Gateway

서버가 업스트림 서버로부터 잘못된 응답을 받았습니다.

3. GET /submission

제출 목록을 가져옵니다.

  • KYC/AML 상태는 GET 요청으로 확인할 수 있습니다.

  • 특정 제출의 KYC 상태를 확인하거나 GET 요청과 함께 KYC 제출 목록을 얻을 수 있습니다.

  • 매개 변수가 제공되지 않으면 모든 제출 목록이 반환됩니다.

  • 매개 변수가 제공된 경우 지정된 매개 변수를 기준으로 목록을 필터링합니다.

  • 특정 제출의 제출 데이터를 가져오려면 제출 ID를 매개 변수로 제공해야 합니다.

요청 URL 

curl -X GET "https://rest-api.argoskyc.com/v2/submission?submission_id={submission_id}"\
-H "x-api-key: {yourAPIKey}"

Input 데이터

파라미터필수여부설명

Submission_id

선택사항

하나의 제출된 데이터에 일치하는 Submission ID가 반환됩니다.

Userid

선택사항

사용자 ID와 일치하는 목록이 반환됩니다. userid는 submission을 post 할 때 선택적으로 추가되는 변수입니다.

Email

선택사항

이메일 주소와 일치하는 제출 목록이 반환됩니다.

count

선택사항

리스트 출력 요청시 전달 받을 데이터 건수 (최대 2,000개).

count parameter 없이 리스트 요청 시 default로 최대 2000개까지 출력 됩니다.

nextpage_id

선택사항

리스트 출력 요청 시 응답에 nextpageKey가 리턴되는 경우, 다음 페이지가 있음을 의미합니다.

요청 parameter에 nextpage_id(nextpageKey.id)와 nextpage_date(nextpageKey.created_at)를 함께 포함하여 요청하면 다음 페이지가 호출됩니다.

nextpage_date

선택사항

리스트 출력 요청 시 응답에 nextpageKey가 리턴되는 경우, 다음 페이지가 있음을 의미합니다.

요청 parameter에 nextpage_id(nextpageKey.id)와 nextpage_date(nextpageKey.created_at)를 함께 포함하여 요청하면 다음 페이지가 호출됩니다.

Output 데이터

Response설명

data

KYC 제출자 데이터

data.name

이름

data.gender

<male, female>

data.nationality

3글자 형식의 국가코드 (ISO alpha3 형식)

data.date_of_birth

YYYY-MM-DD의 날짜 형식

data.idType

신분증 종류<passport, government_id, drivers_license>

data.idcard_issuingCountry

신분증 발급 국가의 ISO alpha 3 형식의 코드

data.idcard_issueDate

YYYY-MM-DD 형식의 신분증 발급일자

data.idcard_expireDate

YYYY-MM-DD 형식의 신분증 만료일자

data.identityNumber

주민등록번호

data.documentNumber

신분증 번호

data.address_city

도시

data.address_country

국가

data.address_state

주

data.address_street

도로

data.address_zipcode

우편번호

data.address_globalCode

전체 주소에 대한 상세코드 값 (Ex. 8Q98HXPG+MP)

data.address_compoundCode

국가 및 도시와 상세주소 코드 값 (Ex. HXPG+MP Seoul, South Korea)

data.address_formatted

상세 코드를 변환한 주소

data.address_input

사용자 입력 주소 값

data.address_detail

사용자 입력 상세주소 값

data.cf1

submission을 제출할 때 선택적으로 추가되는 값 1

data.cf2

submission을 제출할 때 선택적으로 추가되는 값 2

data.cf3

submission을 제출할 때 선택적으로 추가되는 값 3

email

이메일 주소

submission_id

각 submission에 부여된 고유 식별 ID

applicant_id

승인된 제출자에 부여된 고유 식별 ID

created_at

KYC가 제출된 날짜와 시간

userid

submission을 생성할 때 선택적으로 추가되는 파라미터

kyc

KYC 데이터 오브젝트

kyc.result

<Incomplete, pending, approved, rejected> incomplete: KYC 제출이 불완전합니다. 신분증을 제출하였으나 셀가 제출되지 않았을 때 발생하는 오류입니다.

pending: 제출된 파일은 수동 검수중 입니다. approved: 제출된 파일이 승인되었습니다. rejected: 제출된 파일이 거절되었습니다. 거절 사유는 kyc.comment에서 확인할 수 있습니다.

kyc.comment

KYC 거절 사유는 KYC 결과가 ‘rejected’ 되었을 때 반환됩니다.

kyc.commentCode

KYC 거절 사유(kyc.comment)에 대한 코드 값

kyc.attempts

Liveness, Detect face, Face compare, 신분증 진위확인의 실행건에 대한 오브젝트

kyc.attempts[i].error

Liveness, Detect face, Face compare, 신분증 진위확인 실행 시 발생되는 예외 오류 메세지

kyc.attempts[i].retryMsg

Liveness, Detect face, Face compare, 신분증 진위확인 실행 시 발생되는 실패 원인 메세지

kyc.attempts[i].livenessScore

i번째 실행되는 liveness 점수 값

kyc.attempts[i].faceSimilarityScore

i번째 실행되는 face compare 비교 값

kyc.attempts[i].verificationParams

i번째 실행되는 신분증 진위확인 실행 입력 값

kyc.attempts[i].verificationResult

i번째 실행된 신분증 진위확인 결과 값 <success, fail>

aml

aml 스크리닝 결과 데이터 오브젝트

aml.risk_level_summary

<Not Screened, High, Medium, Low>

aml.currentstatus

<Not Screened, Red Flag>

aml.matches

상세 AML 스크리닝 결과. aml.currentstatus가 ‘Red Flag’일때만 이용 가능합니다.

aml.matches[i].resource_id

AML 보고서를 조회하기 위한 리소스 고유 ID

nextpageKey

추가로 출력될 다음 페이지가 있을 경우에 전달되는 키 값 오브젝트

nextpageKey.id

다음 페이지 호출시 필요한 가장 마지막으로 조회되었던 submission의 id 값

nextpageKey.created_at

다음 페이지 호출시 필요한 가장 마지막으로 조회되었던 submission의 created_at 값

샘플 응답 1. 단건조회 

{	
Items: [	
{	
data: {	
name: "홍길동",	
gender: "male",	
nationality: "KOR",	
date_of_birth: "1998-11-12",	
cf1: "test",	
ip_address: "*.*.*.*",	
idcard_issuingCountry: "KOR",	
idcard_issueDate: "2016-08-16",	
idType: "government_id",	
identityNumber: "981112-1******"	
},	
email: "test@gmail.com",	
submission_id: "gt7rcxx9l1o*****",	
created_at: "2022-04-07T00:30:35.919Z",	
userid: "test1",	
kyc: {	
result: "rejected",	
comment: [	
Too many retry 	
],	
	commentCode: [
too_many_retry	
],	
attempts: [	
{	
attemptCnt: 1,	
livenessScore: 91,	
faceSimilarityScore: 99,	
verificationParams: {	
fullName: "홍길동",	
idType: "government_id",	
issueDate: "2016-08-15",	
identityNumber: "981112-1******"	
},	
verificationResult: "fail",	
retryMsg: "1. Identity verification failed: 입력하신 발급일자는 등록된 발급일자와 일치하지 않습니다. 궁금하신 사항은 가까운 읍면동에 문의하시기 바랍니다"	
},	
{	
attemptCnt: 2,	
livenessScore: 98,	
verificationParams: {	
fullName: "홍길동",	
idType: "government_id",	
issueDate: "2016-08-16",	
identityNumber: "981112-1******"	
},	
verificationResult: "success",	
retryMsg: "1. Face compare failed: no matching face"	
},	
{	
attemptCnt: 3,	
faceSimilarityScore: 99,	
verificationParams: {	
fullName: "홍길동",	
idType: "government_id",	
issueDate: "2016-08-16",	
identityNumber: "981112-1******"	
},	
verificationResult: "success",	
retryMsg: "1. Liveness check failed: Absolute face size is too small"	
}	
],	
}	
}	
]	
}

샘플 응답 2. 목록조회 

{ 
Items: [ 
{ 
data: { 
name: "John Smith", 
gender: "male", 
nationality: "USA", 
date_of_birth: "1965-08-29", 
cf1: "test", 
ip_address: "XX.XX.XXX.XXX" 
}, 
email: "example@gmail.com", 
submission_id: "whkksdfyi1on0e", 
created_at: "2022-01-17T02:05:02.309Z", 
userid: "John Smith", 
kyc: { 
result: "approved" 
} 
}, 
{ 
data: { 
name: "Smith John", 
gender: "male", 
nationality: "USA", 
date_of_birth: "1965-08-29", 
cf1: "test", 
ip_address: "XX.XX.XXX.XXX" 
}, 
email: "example@gmail.com", 
submission_id: "whksdkyi1i76x", 
created_at: "2022-01-17T02:00:02.808Z", 
userid: "John ", 
kyc: { result: "incomplete" 
} 
}

3-1. GET /submission/applicant

동일 인물이 제출한 승인된 submission 목록을 가져옵니다.

  • 이름, 생년월일, 국적, 성별, 얼굴이 같은 사람의 submission이 다수 있을 경우 중복 제출로 판단하며, 중복 제출된 submission들을 확인 할 수 있습니다.

  • 중복으로 제출하지 않은 일반적인 제출자의 경우 승인된 단일 submission만 가져옵니다.

  • applicant_id를 기준으로 조회하기때문에, submission 정보에서 applicant_id를 획득해야 합니다.

Request URL

curl -X GET "<https://rest-api.argoskyc.com/v2/submission/applicant?applicant_id={applicant_id}>"\\
-H "x-api-key: {yourAPIKey}"

Input 데이터

ParameterrequirementDescription

applicant_id

required

submission 정보에서 획득한 제출자의 고유 applicant_id로 조회합니다.

Output 데이터

ResponseDescription

submission_id

중복제출로 확인된 submission의 고유 값

email

중복 제출로 확인된 submission에 기록된 이메일 주소

4. POST /submission/step1

요청 URL

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

Input 데이터

파라미터포맷필수여부설명

issuingCountry

string (ISO3)

필수

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

email

string

필수

KYC 제출자의 이메일 주소

idType

string

필수

<passport, government_id, drivers_license>

idImage

file

필수

Jpg, jpeg, png 파일 형식의 신분증 사진 (파일 크기 제한: 3mb)

userid

string

옵션

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

cf1

string

옵션

사용자 정의 옵션 필드

cf2

string

옵션

사용자 정의 옵션 필드

cf3

string

옵션

사용자 정의 옵션 필드

Output 데이터

Response설명

Submissionid

submission의 ID. 해당 ID는 step 2에서 필요합니다.

reviewOCRData

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

reviewOCRData.ocr_birthDate

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

reviewOCRData.ocr_issueDate

발급 일자 (이용 가능할 때)

reviewOCRData.ocr_expireDate

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

reviewOCRData.ocr_lastName

성 (이용 가능할 때)

reviewOCRData.ocr_firstName

이름 (이용 가능할 때)

reviewOCRData.ocr_name

전체 이름 (이용 가능할 때)

reviewOCRData.ocr_gender

성별 (이용 가능할 때)

reviewOCRData.ocr_nationality

ISO3 코드 형식의 국가코드 (이용 가능할 때)

reviewOCRData.ocr_identityNumber

사용자 고유의 식별번호(한국 주민등록번호에만 적용)

reviewOCRData.ocr_licenseNumber

운전면허번호 (한국 운전면허증에만 적용)

file_upload

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

샘플 응답

{"reviewOCRData":
	{
	 	"ocr_issueDate":"2020-02-25",
		"ocr_gender":"male",
	 	"ocr_nationality":"USA",
	 	"ocr_birthDate":"1975-08-25",
		"ocr_name":"John Smith"
	},
	 "file_upload":true,
	 "submissionId":"1cz94l9ksfi1bokk"
	}

5. POST /submission/step2

요청 URL 

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

Input 데이터

파라미터포맷필수여부설명

submissionId

string

필수

step 1으로 받은 제출된 고유 ID

faceImage

file

필수

하나의 얼굴을 보여주는 셀피 사진. 여러 명의 얼굴이 감지될 경우, 재시도로 응답됩니다. (파일 크기 제한: 3mb)

name

string

필수

이름 형식은 ”성, 이름, 중간 이름” (예시: “Trump, Donald John”)으로 나타낼 수 있습니다. 이 형식은 각 제출자들의 성들을 정확히 알고 있을 때 선호됩니다. 제출자의 성을 정확히 모를 땐 ”이름, 중간 이름, 성” (예시: “Donald John Trump”) 형식을 쓰게 됩니다. 알고리즘이 두 가지 방식 중 하나를 자동으로 선택할 것입니다.

date_of_birth

string

필수

YYYY-MM-DD

gender

string

옵션

<남성, 여성>

nationality

string

옵션

ISO alpha 3 형식의 국가코드. 반드시 신분증이 발급된 국가일 필요는 없습니다.

identity_number

string

옵션

(한국 주민등록증)

한국 주민등록번호

license_number

string

옵션

(한국 운전면허증)

진위확인을 위한 운전면허번호

serial_number

string

옵션

(한국 운전면허증)

한국 운전면허증의 고유한 6자리 일련번호

date_of_issue

string

옵션

YYYY-MM-DD 형식의 사진 신분증 발급일자

addressImage

file

옵션

주소 정보 증명을 위한 주소 문서 사진 파일 (파일 크기 제한: 3mb)

address_street

string

옵션

주소

address_city

string

옵션

도시

address_state

string

옵션

주

address_country

string

옵션

ISO 3 형식의 국가코드

address_zipcode

string

옵션

우편번호

globalCode

string

옵션

전체 주소에 대한 상세코드 값 (Ex. 8Q98HXPG+MP)

compoundCode

string

옵션

국가 및 도시와 상세주소 코드 값 (Ex. HXPG+MP Seoul, South Korea)

formatted_address

string

옵션

상세 코드를 변환한 주소

address_input

string

옵션

사용자 입력 주소 값

address_detail

string

옵션

사용자 입력 상세주소 값

Output 데이터

응답설명

kycStatus

<pending, approved, rejected, incomplete> ‘pending’인 경우에는 kyc 제출이 끝났으나 수동 검수를 통해 제출된 파일이 승인될지 거절될지를 결정하기 위해 검토 중입니다.

‘incomplete’인 경우에는 잘못된 kyc 데이터로 인해 승인이 이루어지지 않았습니다. kycStatus가 ‘pending’, ‘approved’나 ‘rejected’ 상태로 변할 때까지 step 2의 재시도를 하길 추천드립니다.

faceSimilarityScore

신분증의 사진과 셀피 사진의 얼굴 유사도 점수입니다. 점수는 0부터 100까지이며 100에 가까울수록 두 얼굴이 일치할 확률이 큽니다.

livenessScore

라이브니스 점수는 셀피 이미지 속 얼굴이 실제 인물인지를 평가합니다. 점수는 0점부터 100점까지이며 점수가 100에 가까울수록 이미지는 (영상이나 이미지의 이미지가 아닌) 실제 인물 사진일 가능성이 높습니다.

verificationResult

<success, fail>

retryCount

Step 2의 재시도 횟수. Step 2 재시도가 3번을 넘을 경우 KYC는 거절됩니다.

message

KycStatus가 ‘incomplete”인 경우에, KYC submission이 생성되지 않은 사유를 보여줍니다.

kycStatus는 "incomplete"일 때 다음과 같은 경우 retryCount가 증가합니다.

  1. 얼굴 이미지에서 감지된 얼굴이 없는 경우

  2. 얼굴 이미지에서 세 개 이상의 얼굴이 감지된 경우

  3. 얼굴 비교 점수가 85 미만인 경우

  4. 라이브니스(Liveness) 점수가 50 미만인 경우

  5. (한국신분증만 해당) ID 확인 실패

샘플 응답

{

"verificationResult":"success",

"faceSimilarityScore":99,

"livenessScore":91,

"kycStatus":"pending",

"retryCount":0

}

5-1. POST /address_code

주소지를 '수집'하는경우에만 사용해주세요.

요청 URL 

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

요청 샘플 1 

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest-api.argoskyc.com/v2/address_code',
  'headers': {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    'address': '1 Sejongno, Jongno-gu, Seoul, South Korea'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

요청 샘플 2

curl --location --request POST 'https://rest-api.argoskyc.com/v2/address_code' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'language=en' \
--data-urlencode 'address=1 Sejongno, Jongno-gu, Seoul, South Korea'

샘플 응답

{
    "formatted_address": "1 Sejongno, Jongno-gu, Seoul, South Korea",
    "compound_code": "HXPG+MP Seoul, South Korea",
    "global_code": "8Q98HXPG+MP"
}

Input Data

파라미터포맷필수 여부설명

address

string

필수

다음 항목 중 하나를 입력하여 조회할 수 있습니다.

  • 주소

  • global code

  • compound code

  • 위도 및 경도 (콤마 구분으로 입력, ex. “37.557,126.973”)

language

string

옵션

결과 리턴값에 대한 언어 선택 (ISO 3166-2 코드) (ex. “ko”)

Output Data

응답 파라미터설명

formatted_address

상세 코드를 변환한 주소

compound_code

국가 및 도시와 상세주소 코드 값 (Ex. HXPG+MP Seoul, South Korea)

global_code

전체 주소에 대한 상세코드 값 (Ex. 8Q98HXPG+MP)

6. DELETE /submission

단일 제출 데이터를 삭제합니다.

제출 데이터와 제출과 관련된 이미지 파일이 완전히 삭제됩니다.

주의!!! 삭제된 제출 기록은 복원할 수 없습니다.

샘플 요청

curl -X DELETE "https://rest-api.argoskyc.com/v2/submission?submission_id={submission_id}"

Input 데이터

파라미터설명

submission_id

Submission ID. 각각의 제출건에 대한 고유 ID

샘플 응답 

{
	"message": "success",
	"content": "Submission #{submissionID} deleted successfully."
}

7. GET /report/aml

AML 스크리닝 결과와 pdf 보고서를 반환합니다.

'resourceId'별로 AML 보고서가 제공됩니다. AML 보고서를 다운로드하려면 'resourceId'가 필요합니다.

요청 URL

curl -X GET "https://rest-api.argoskyc.com/v2/report/aml?resourceId={resourceId}"

Input Data

파라미터설명

resourceId

리소스 아이디는 AML 검사 결과로 선별된 사람의 고유값입니다.

리소스 아이디는 제출된 파일이 AML Red Flag로 스크린 되었을 때 생성됩니다. 각 AML 선별 결과마다 고유의 리소스 아이디가 있습니다. 하나의 제출된 파일에도 여러 개의 일치 항목이 있을 수 있으므로 해당의 경우에는 여러 개의 리소스 아이디가 있습니다.

Output 데이터

응답으로 파일이 다운로드 됩니다.

8. GET /image

요청 URL

curl -X GET "https://rest-api.argoskyc.com/v2/image?submission_id={submission_id}&type={type}"

Input 데이터

파라미터필수여부설명

submission_id

필수

고유의 제출 ID

type

필수

<idImage, selfieImage, addressImage>

idImage: 신분증 사진을 다운로드합니다.

selfieImage: 셀피의 이미지를 다운로드합니다.

addressImage: 제출된 파일에 주소 문서가 있을 경우 다운로드합니다.

Output 데이터

응답으로 파일이 다운로드 됩니다.

PreviousFAQNextAPI 오류

Last updated