쿼리 스트링 및 토큰
쿼리 스트링 및 토큰
라이브폼의 QueryString 및 Token ID 옵션에 대한 종합 가이드입니다. API 호출 시 추가 정보 전송, 중복 제출 방지, 사용자 식별 등 다양한 기능을 제공합니다. ID Check 프로세스 최적화를 위한 필수 정보를 확인하세요.
1. QueryString 변경 가능 옵션
라이브폼과 API에서 사용 가능한 QueryString 옵션을 통해 추가 정보를 전송하고 KYC 프로세스를 커스터마이즈할 수 있습니다.2. 기본 URL 구조
- 기본 폼 URL:
https://form.argosidentity.com/?pid={project_Id} - QueryString 포함 URL:
https://form.argosidentity.com/?pid={project_Id}&blacklistCountries=false
2-1. 주요 QueryString 파라미터
| 파라미터 | ID Document | Knowledge-Based | 설명 |
|---|---|---|---|
blacklistCountries | Yes | Yes | 블랙리스트 국가에 대한 옵션을 해당 submission에 대하여 OFF 함 (false만 가능) |
approvePeriod | Yes | No | Approved 중복 제출 방지 기간에 대한 옵션을 해당 submission에 대하여 OFF 함 (false만 가능) |
rejectPeriod | Yes | No | Rejected 중복 제출 방지 기간에 대한 옵션을 해당 submission에 대하여 OFF 함 (false만 가능) |
ageLimit | Yes | Yes | 연령 제한에 대한 옵션을 해당 submission에 대하여 OFF 함 (false만 가능) |
rejectDuplicateUser | Yes | Yes | 중복 제출 방지에 대한 옵션을 해당 submission에 대하여 ON / OFF 함 (true 및 false 모두 가능) |
email | Yes | Yes | 사용자 이메일 |
userid | Yes | Yes | 사용자의 사용자 지정 고유 식별자 |
pid | Yes | Yes | 각각의 project를 구분하는 고유의 구분자 |
sid | Yes | Yes | 각각의 submission을 구분하는 고유의 구분자 |
cf1 | Yes | Yes | 사용자 정의 옵션 필드1 |
cf2 | Yes | Yes | 사용자 정의 옵션 필드2 |
cf3 | Yes | Yes | 사용자 정의 옵션 필드3 |
auxidField | Yes | No | 반드시 encrypted 로 암호화해서 사용해야 됩니다. 신분증 정보와 셀피 사진 이외에 보조적으로 검증이 필요한 신원 인증 정보가 필요한 경우 사용할 수 있습니다. 현재 phoneNumber가 구현되어 있으며 자세한 내용은 하단의 내용을 참조하세요. selectedIssuingCountry 및 selectedIdType과 동시에 적용할 수 없습니다. 추후 업데이트를 통해 변경될 예정입니다. |
allowedCountries | Yes | Yes | 반드시 encrypted 로 암호화해서 사용해야 됩니다. 예시로 {'allowedCountries': 'USA,KOR'} 값을 암호화하여 전달하면 United States (USA) 및 South Korea (KOR)만 허용됩니다. |
knowledgeField | No | Yes | 반드시 encrypted 로 암호화해서 사용해야 됩니다. Knowledge-based Form 에 노출시킬 필드를 정합니다. 지원하는 필드는 하단 매개변수 값 설정을 참조하세요. |
knowledgePrefill | No | Yes | 반드시 encrypted 로 암호화해서 사용해야 됩니다. 필드에 값을 미리 입력할 수 있습니다. 각 필드 별 입력이 가능한 값은 하단 매개변수 값 설정을 참조하세요. |
allowedIdTypes | Yes | No | 반드시 encrypted 로 암호화해서 사용해야 됩니다. 신분증 ID 타입 선택지를 정할 수 있습니다. 각 필드 별 입력이 가능한 값은 하단 매개변수 값 설정을 참조하세요. |
allowedDocumentFields | Yes | No | 반드시 encrypted 로 암호화해서 사용해야 됩니다. 신분증 리뷰 단계에서 보여줄 필드를 정할 수 있습니다. 각 필드 별 입력이 가능한 값은 하단 매개변수 값 설정을 참조하세요. |
projectionId | Yes | Yes | 반드시 encrypted 로 암호화해서 사용해야 됩니다. projectionId 로 projection을 적용할 수 있습니다. Id 가 지정되었으므로, ProjectionName와 함께 사용될 수 없습니다. |
projectionName | Yes | Yes | 반드시 encrypted 로 암호화해서 사용해야 됩니다. projectionName 로 projection을 적용할 수 있습니다. 이름으로 Projection이 지정되었으므로, ProjectionId와 함께 사용될 수 없습니다. |
selectedIssuingCountry | Yes | Yes | 반드시 encrypted로 암호화해서 사용해야 됩니다. 선택 시 사용자는 국가 선택 페이지를 건너뛸 수 있습니다. allowedCountries와 selectedIdType를 함께 사용할 수 있습니다. 또한 allowedCountries가 설정된 경우, allowedCountries에 포함되지 않은 국가는 사용할 수 없습니다. blacklistCountries와 동일한 국가는 함께 사용할 수 없습니다. |
selectedIdType | Yes | No | 반드시 encrypted로 암호화해서 사용해야 됩니다. 선택 시 사용자는 신분증 타입 선택 페이지를 건너뛸 수 있습니다. selectedIssuingCountry와 함께 사용해야 합니다. selectedIdType을 단독으로 사용하면 오류가 발생합니다. 또한 Universal mode와 selectedIdType을 함께 사용하면 오류가 발생합니다; (예외 케이스: 국가 선택이 한국으로 되어있고 Universal mode 옵션이 활성화 되어 있으면, 신분증 선택 페이지가 유저에게 나타납니다.) |
2-1-a. ID Type, Field 및 Knowledge-Based, Auxiliary ID Field 관련 매개변수 값 설정
[Knowledge-Based] knowledgeField 매개변수 값 설정
[Knowledge-Based] knowledgeField 매개변수 값 설정
-
name -
gender -
birthDate -
nationality -
SSN(미국 국가에 한해서만 지원됩니다.) -
address -
phoneNumbere.g.{'knowledgeField': 'gender,nationality,name'}상기의 매개변수 값은 대소문자를 동일하게 기재해야 동작합니다. 예를들면 birthdate 로 기재시 동작하지 않습니다. 위의 값과 동일하게 birthDate 로 기재하셔야 됩니다.
[Knowledge-Based] knowledgePrefill 매개변수 값 설정
[Knowledge-Based] knowledgePrefill 매개변수 값 설정
-
name미리 입력할 이름 기입 -
birthDateYYYY-MM-DD 형식으로 기재 -
gendermale 혹은 female 로 기재 -
nationalityISO Alpha-3 국가 코드로 기재 -
SSNSocial Security Number 숫자를 하이픈(-)을 포함하여 기재 -
addressGoogle Maps 에 검색할 키워드 기입 -
phoneNumber국가코드와 전화번호를 기재, 전화번호에는 하이픈(-)을 미포함하여 기재 e.g.{'knowledgePrefill': 'gender=male,birthdate=1990-01-01,SSN=123-12-0001,address=Washington D.C.,phoneNumber=+15555551234'}address에는 Google Maps 에서 검색이 되는 키워드로 기재해주시면 됩니다. 미리 기입한 값은 주소 검색화면 필드에서 보여집니다.
[ID document] allowedIdTypes 매개변수 값 설정
[ID document] allowedIdTypes 매개변수 값 설정
-
passport -
drivers_license -
government_id -
residence_permit -
vehicle_registration_certificate -
visa -
pancard -
aadhaar -
foreign_registrator -
identification_carde.g.{'allowedIdTypes': 'passport,government_id,drivers_license'}
[ID document] allowedDocumentFields 매개변수 값 설정
[ID document] allowedDocumentFields 매개변수 값 설정
-
gender -
nationality -
expiry_date -
number여권번호와 매칭되는 필드 -
issue_date -
id_number -
serial_number -
name -
date_of_birth -
curp_number멕시코 ID 에서만 사용되는 필드 -
version뉴질랜드 운전면허증에 사용되는 필드 -
type_of_permit한국 외국인 등록증에서만 사용되는 필드 e.g.{'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}
[ID document] selectedIDType 매개변수 값 설정
[ID document] selectedIDType 매개변수 값 설정
-
passport -
drivers_license -
government_id -
residence_permit -
vehicle_registration_certificate -
visa -
pancard -
aadhaar -
foreign_registrator -
identification_carde.g.{'selectedIdType': 'passport'}
[ID document] auxidField 매개변수 값 설정
[ID document] auxidField 매개변수 값 설정
-
phoneNumberSMS기반 휴대폰 번호 인증 e.g.{'auxidField': 'phoneNumber'}
각 파라메터 간에 공백이 있으면 안됩니다. ❌ 잘못된 예시
{'knowledgeField': 'gender, nationality, name'}
정확한 옵션은 다음과 같이 쉼표 다음에 공백이 없어야 합니다.{'knowledgeField': 'gender,nationality,name'}
2-1-b. Knowledge-Based 에서 국가 선택화면 건너뛰기
allowedCountries 에 국가를 하나만 기입시 국가 선택화면을 건너뛸 수 있습니다.e.g.
{'allowedCountries': 'USA'}
모든 쿼리 스트링 값은 URL에 인코딩되어야 합니다.
2-2. 고유 유저 ID 및 커스텀 필드
- API 호출 시 KYC 제출자 식별을 위한 고유 유저 ID를 생성할 수 있습니다.
- 최대 3개의 커스텀 필드(cf1, cf2, cf3)를 추가하여 추가 정보를 전송할 수 있습니다.
2-3. 보조 신원 필드 [Auxiliary ID Field]
신분증과 셀피 정보 이외에 검증이 필요한 신원 정보의 경우 (예: 휴대폰 번호) auxidField 옵션을 통해 수집 및 검증할 수 있습니다. 지원하는 필드:phoneNumber: SMS기반 전화번호 인증
주의사항:
- 반드시 encrypted로 암호화해서 사용해야 됩니다.
- 상기의 매개변수 값은 대소문자를 동일하게 기재해야 동작합니다. 예를들면 phonenumber로 기재시 동작하지 않습니다. 위의 값과 동일하게 phoneNumber로 기재하셔야 됩니다.
- selectedIssuingCountry 및 selectedIdType과 동시에 적용할 수 없습니다. 추후 업데이트를 통해 변경될 예정입니다.
- 현재 91개의 국가가 SMS 인증을 지원하지 않습니다.
지원되지 않는 국가 확인auxidField phoneNumber 기능에서 SMS 인증을 지원하지 않는 91개 국가의 상세 목록을 확인하려면 아래 링크를 참조하세요.📋 SMS 인증 미지원 국가 목록 보기
3. Token ID 옵션
tokenId는 Private Mode에서 Liveform 제출 시 사용되는 String 데이터입니다. 목적 : 동일한 URL의 공유 및 중복 사용 방지3-1. Token 검증 방식
다음 조건 중 하나라도 해당되면 검증 실패(에러) 발생:- 시간 만료: 최초 사용으로부터 3분 경과
- 유효한 제출 건 존재: KYC Status가 결정된 제출건 존재 (approved, rejected, pending)
주의
- 위 조건에 해당하지 않으면 여러 사용자가 동시에 동일한 Token ID로 KYC를 진행할 수 있습니다.
3-2. Token ID 확인 방법
- Webhook
- GET Submission API (submission_id를 이용한 단건 조회)
- 대시보드의 Submission CSV 다운로드
3-3. Token ID 사용 URL 구조
- 기본 폼 URL:
https://form.argosidentity.com/?pid={project_Id} - Token ID 포함 URL:
https://form.argosidentity.com/?pid={project_Id}&token={tokenId}
4. 암호화 전용
Dashboard 에서 암호화 전용 옵션을 활성화 시킬 수 있습니다. 활성화 된 이후에는 URL query 형태로 파라미터는pid(프로젝트 id), encrypted 그리고 lang(언어) 만 허용됩니다.
-
https://form.argosidentity.com/?pid={project_Id}&encrypted={encrypted_option}&lang=en(O) -
https://form.argosidentity.com/?pid={project_Id}&encrypted={encrypted_option}&email=your_email_address@argosidentity.com(X) email 은 허용되지 않은 파라미터이므로 접근이 불가합니다.