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 Code	Message	설명
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: "[e-mail]",	
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: "[e-mail]", 
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: "[e-mail]", 
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 데이터

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

Output 데이터

Response	Description
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 확인 실패

샘플 응답

pending

{

"verificationResult":"success",

"faceSimilarityScore":99,

"livenessScore":91,

"kycStatus":"pending",

"retryCount":0

}

retry

{

"message": "no match face or 2 face detected",

"kycStatus": "incomplete",

"retryCount": 1

}

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 데이터

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